Enable textmacros package for sphinx

* Convert all \text{*_*} to \text{*\_*}

Author: glatterf42

doc/conf.py

@@ -160,6 +160,10 @@
 mathjax3_config = dict(
     tex=dict(
         macros={k.replace("_", ""): r"\text{" + k + "}" for k in text_macros.split()},
+        packages={"[+]": ["textmacros"]},
+    ),
+    loader=dict(
+        load=["[tex]/textmacros"],
     ),
 )
 

doc/efficiency.rst

@@ -16,7 +16,7 @@ As an additional benefit, we do not need to define an explicit efficiency parame
 or "main" input and output fuels.  
 
 The recommended approach is illustrated below for multiple examples. 
-The decision variables :math:`\text{CAP_NEW}`, :math:`\text{CAP}` and :math:`\text{ACT}` as well as all bounds 
+The decision variables :math:`\text{CAP\_NEW}`, :math:`\text{CAP}` and :math:`\text{ACT}` as well as all bounds 
 are always understood to be in the same units. All cost parameters also have to be provided 
 in monetary units per these units - there is no "automatic rescaling" done either within the ixmp API
 or in the GAMS implementation pre- or postprocessing.

doc/time.rst

@@ -82,9 +82,9 @@ Example 5
    Using the same setup as Example 2:
 
    - Discounting for the element ``1010`` involves discounting for years ``1001``, ``1002``, ... , ``1010``.
-   - Using the standard PV formula, we have that, for the year ``1001`` the discount factor would be :math:`(1 + \text{interest_rate})^{1000 - 1001}`, for the year  ``1002`` the discount factor would be :math:`(1 + \text{interest_rate})^{1000 - 1002}`, and so on.
-   - Therefore, the period discount factor for the element ``1010`` is :math:`\text{df}_{1010} = (1 + \text{interest_rate})^{1000 - 1001} + ... + (1 + \text{interest_rate})^{1000 - 1010}`
-   - Analogously, the period discount factor for the element ``1020`` is :math:`\text{df}_{1020} = (1 + \text{interest_rate})^{1000 - 1011} + ... + (1 + \text{interest_rate})^{1000 - 1020}`
+   - Using the standard PV formula, we have that, for the year ``1001`` the discount factor would be :math:`(1 + \text{interest\_rate})^{1000 - 1001}`, for the year  ``1002`` the discount factor would be :math:`(1 + \text{interest\_rate})^{1000 - 1002}`, and so on.
+   - Therefore, the period discount factor for the element ``1010`` is :math:`\text{df}_{1010} = (1 + \text{interest\_rate})^{1000 - 1001} + ... + (1 + \text{interest\_rate})^{1000 - 1010}`
+   - Analogously, the period discount factor for the element ``1020`` is :math:`\text{df}_{1020} = (1 + \text{interest\_rate})^{1000 - 1011} + ... + (1 + \text{interest\_rate})^{1000 - 1020}`
    - So, if we have a cost of ``K_1010`` for the element ``1010``, its discounted value would be ``df_1010 * K_1010``, which means, all the years in  element ``1010`` have a representative cost of ``K_1010`` that is discounted up to the initial ``year`` of the setup, namely, the year ``1000``.
 
 In practice, since the representative year of a period is always its final year, the actual calculation of the period discount factor within the model is performed backwards, i.e., starting from the final year of the period until the initial year.

message_ix/model/MACRO/macro_core.gms

@@ -32,25 +32,25 @@
 *
 * A listing of all parameters used in MACRO together with a decription can be found in the table below.
 *
-* ================================== ================================================================================================================================
-* Parameter                          Description
-* ================================== ================================================================================================================================
-* :math:`\text{duration_period}_y`   Number of years in time period :math:`y` (forward diff)
-* :math:`\text{total_cost}_{n,y}`    Total system costs in region :math:`n` and period :math:`y` from MESSAGE model run
-* :math:`\text{enestart}_{n,s,y}`    Consumption level of (commercial) end-use services :math:`s` in region :math:`n` and period :math:`y` from MESSAGE model run
-* :math:`\text{eneprice}_{n,s,y}`    Shadow prices of (commercial) end-use services :math:`s` in region :math:`n` and period :math:`y` from MESSAGE model run
-* :math:`\epsilon_n`                 Elasticity of substitution between capital-labor and total energy in region :math:`n`
-* :math:`\rho_n`                     :math:`\epsilon - 1 / \epsilon` where :math:`\epsilon` is the elasticity of subsitution in region :math:`n`
-* :math:`\text{depr}_n`              Annual depreciation rate in region :math:`n`
-* :math:`\alpha_n`                   Capital value share parameter in region :math:`n`
-* :math:`a_n`                        Production function coefficient of capital and labor in region :math:`n`
-* :math:`b_{n,s}`                    Production function coefficients of the different end-use sectors in region :math:`n`, sector :math:`s` and period :math:`y`
-* :math:`\text{udf}_{n,y}`           Utility discount factor in period year in region :math:`n` and period :math:`y`
-* :math:`\text{newlab}_{n,y}`        New vintage of labor force in region :math:`n` and period :math:`y`
-* :math:`\text{grow}_{n,y}`          Annual growth rates of potential GDP in region :math:`n` and period :math:`y`
-* :math:`\text{aeei}_{n,s,y}`        Autonomous energy efficiency improvement (AEEI) in region :math:`n`, sector :math:`s` and period :math:`y`
-* :math:`\text{fin_time}_{n,y}`      finite time horizon correction factor in utility function in region :math:`n` and period :math:`y`
-* ================================== ================================================================================================================================
+* =================================== ================================================================================================================================
+* Parameter                           Description
+* =================================== ================================================================================================================================
+* :math:`\text{duration\_period}_y`   Number of years in time period :math:`y` (forward diff)
+* :math:`\text{total\_cost}_{n,y}`    Total system costs in region :math:`n` and period :math:`y` from MESSAGE model run
+* :math:`\text{enestart}_{n,s,y}`     Consumption level of (commercial) end-use services :math:`s` in region :math:`n` and period :math:`y` from MESSAGE model run
+* :math:`\text{eneprice}_{n,s,y}`     Shadow prices of (commercial) end-use services :math:`s` in region :math:`n` and period :math:`y` from MESSAGE model run
+* :math:`\epsilon_n`                  Elasticity of substitution between capital-labor and total energy in region :math:`n`
+* :math:`\rho_n`                      :math:`\epsilon - 1 / \epsilon` where :math:`\epsilon` is the elasticity of subsitution in region :math:`n`
+* :math:`\text{depr}_n`               Annual depreciation rate in region :math:`n`
+* :math:`\alpha_n`                    Capital value share parameter in region :math:`n`
+* :math:`a_n`                         Production function coefficient of capital and labor in region :math:`n`
+* :math:`b_{n,s}`                     Production function coefficients of the different end-use sectors in region :math:`n`, sector :math:`s` and period :math:`y`
+* :math:`\text{udf}_{n,y}`            Utility discount factor in period year in region :math:`n` and period :math:`y`
+* :math:`\text{newlab}_{n,y}`         New vintage of labor force in region :math:`n` and period :math:`y`
+* :math:`\text{grow}_{n,y}`           Annual growth rates of potential GDP in region :math:`n` and period :math:`y`
+* :math:`\text{aeei}_{n,s,y}`         Autonomous energy efficiency improvement (AEEI) in region :math:`n`, sector :math:`s` and period :math:`y`
+* :math:`\text{fin\_time}_{n,y}`      finite time horizon correction factor in utility function in region :math:`n` and period :math:`y`
+* =================================== ================================================================================================================================
 ***
 
 *----------------------------------------------------------------------------------------------------------------------*
@@ -138,14 +138,14 @@ EQUATIONS
 * The utility function which is maximized sums up the discounted logarithm of consumption of a single representative producer-consumer over the entire time horizon
 * of the model.
 *
-* .. math:: \text{UTILITY} = \sum_{n} \bigg( &  \sum_{y |  (  (  {ord}( y )   >  1 )  \wedge  (  {ord}( y )   <   | y |  )  )} \text{udf}_{n, y} \cdot {\log}( \text{C}_{n, y} ) \cdot \text{duration_period}_{y} \\
-*                                 + &\sum_{y |  (  {ord}( y ) =  | y | ) } \text{udf}_{n, y} \cdot {\log}( \text{C}_{n, y} ) \cdot \big( \text{duration_period}_{y-1} + \frac{1}{\text{fin_time}_{n, y}} \big) \bigg)
+* .. math:: \text{UTILITY} = \sum_{n} \bigg( &  \sum_{y |  (  (  {ord}( y )   >  1 )  \wedge  (  {ord}( y )   <   | y |  )  )} \text{udf}_{n, y} \cdot {\log}( \text{C}_{n, y} ) \cdot \text{duration\_period}_{y} \\
+*                                 + &\sum_{y |  (  {ord}( y ) =  | y | ) } \text{udf}_{n, y} \cdot {\log}( \text{C}_{n, y} ) \cdot \big( \text{duration\_period}_{y-1} + \frac{1}{\text{fin\_time}_{n, y}} \big) \bigg)
 *
 * The utility discount rate for period :math:`y` is set to :math:`\text{drate}_{n} - \text{grow}_{n,y}`, where :math:`\text{drate}_{n}` is the discount rate used in MESSAGE, typically set to 5%,
 * and :math:`\text{grow}` is the potential GDP growth rate. This choice ensures that in the steady state, the optimal growth rate is identical to the potential GDP growth rates :math:`\text{grow}`.
-* The values for the utility discount rates are chosen for descriptive rather than normative reasons. The term :math:`\frac{\text{duration_period}_{y} + \text{duration_period}_{y-1}}{2}` mutliples the
-* discounted logarithm of consumption with the period length. The final period is treated separately to include a correction factor :math:`\frac{1}{\text{fin_time}_{n, y}}` reflecting
-* the finite time horizon of the model. Note that the sum over nodes :math:`\text{node_active}` is artificial, because :math:`\text{node_active}` only contains one element.
+* The values for the utility discount rates are chosen for descriptive rather than normative reasons. The term :math:`\frac{\text{duration\_period}_{y} + \text{duration\_period}_{y-1}}{2}` mutliples the
+* discounted logarithm of consumption with the period length. The final period is treated separately to include a correction factor :math:`\frac{1}{\text{fin\_time}_{n, y}}` reflecting
+* the finite time horizon of the model. Note that the sum over nodes :math:`\text{node\_active}` is artificial, because :math:`\text{node\_active}` only contains one element.
 *
 ***
 
@@ -181,7 +181,7 @@ C(node_active, year) + I(node_active, year) + EC(node_active, year)
 * The accumulation of capital in the sectors not represented in MESSAGE is governed by new capital stock equation. Net capital formation :math:`\text{KN}_{n,y}` is derived from gross
 * investments :math:`\text{I}_{n,y}` minus depreciation of previsouly existing capital stock.
 *
-* .. math:: \text{KN}_{n,y} = \text{duration_period}_{y} \cdot \text{I}_{n,y} \qquad \forall{n, y > 1}
+* .. math:: \text{KN}_{n,y} = \text{duration\_period}_{y} \cdot \text{I}_{n,y} \qquad \forall{n, y > 1}
 *
 * Here, the initial boundary condition for the base year :math:`y_0` implies for the investments that :math:`\text{I}_{n,y_0} = (\text{grow}_{n,y_0} + \text{depr}_{n}) \cdot \text{kgdp}_{n} \cdot \text{gdp}_{n,y_0}`.
 ***
@@ -212,7 +212,7 @@ YN(node_active, year) =E=
 * Equivalent to the total production equation above, the total capital stock, again excluding those sectors which are modeled in MESSAGE, is then simply a summation
 * of capital stock in the previous period :math:`y-1`, depreciated with the depreciation rate :math:`\text{depr}_{n}`, and the capital stock added in the current period :math:`y`.
 *
-* .. math:: \text{K}_{n, y} = \text{K}_{n, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration_period}_{y}} + \text{KN}_{n, y} \qquad \forall{ n, y > 1}
+* .. math:: \text{K}_{n, y} = \text{K}_{n, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration\_period}_{y}} + \text{KN}_{n, y} \qquad \forall{ n, y > 1}
 *
 ***
 
@@ -227,7 +227,7 @@ SUM(year2$( seq_period(year2,year) ), K(node_active, year2)) * (1 - depr(node_ac
 * Total production in the economy (excluding energy sectors) is the sum of production from  assets that were already existing in the previous period :math:`y-1`,
 * depreciated with the depreciation rate :math:`\text{depr}_{n}`, and the new vintage of production from period :math:`y`.
 *
-* .. math:: \text{Y}_{n, y} = \text{Y}_{n, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration_period}_{y}} + \text{YN}_{n, y} \qquad \forall{ n, y > 1}
+* .. math:: \text{Y}_{n, y} = \text{Y}_{n, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration\_period}_{y}} + \text{YN}_{n, y} \qquad \forall{ n, y > 1}
 *
 ***
 
@@ -243,7 +243,7 @@ SUM(year2$( seq_period(year2,year) ), Y(node_active, year2)) * (1 - depr(node_ac
 * in the previous period :math:`y-1`, depreciated with the depreciation rate :math:`\text{depr}_{n}`, and the the new vintage of energy production from
 * period :math:`y`.
 *
-* .. math:: \text{PRODENE}_{n, s, y} = \text{PRODENE}_{n, s, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration_period}_{y}} + \text{NEWENE}_{n, s, y} \qquad \forall{ n, s, y > 1}
+* .. math:: \text{PRODENE}_{n, s, y} = \text{PRODENE}_{n, s, y-1} \cdot { \left( 1 - \text{depr}_n \right) }^{\text{duration\_period}_{y}} + \text{NEWENE}_{n, s, y} \qquad \forall{ n, s, y > 1}
 *
 ***
 
@@ -258,11 +258,11 @@ SUM(year2$( seq_period(year2,year) ), PRODENE(node_active, sector, year2)) * (1
 * The relationship below establishes the link between physical energy :math:`\text{PHYSENE}_{r, s, y}` as accounted in MESSAGE for the six commerical energy demands :math:`s` and
 * energy in terms of monetary value :math:`\text{PRODENE}_{n, s, y}` as specified in the production function of MACRO.
 *
-* .. math:: \text{PHYSENE}_{n, s, y} \geq \text{PRODENE}_{n, s, y} \cdot \text{aeei_factor}_{n, s, y} \qquad \forall{ n, s, y > 1}
+* .. math:: \text{PHYSENE}_{n, s, y} \geq \text{PRODENE}_{n, s, y} \cdot \text{aeei\_factor}_{n, s, y} \qquad \forall{ n, s, y > 1}
 *
 * The cumulative effect of autonomous energy efficiency improvements (AEEI) is captured in
-* :math:`\text{aeei_factor}_{n,s,y} = \text{aeei_factor}_{n, s, y-1} \cdot (1 - \text{aeei}_{n,s,y})^{\text{duration_period}_{y}}`
-* with :math:`\text{aeei_factor}_{n,s,y=1} = 1`. Therefore, choosing the :math:`\text{aeei}_{n,s,y}` coefficients appropriately offers the possibility to calibrate MACRO to a certain energy demand trajectory
+* :math:`\text{aeei\_factor}_{n,s,y} = \text{aeei\_factor}_{n, s, y-1} \cdot (1 - \text{aeei}_{n,s,y})^{\text{duration\_period}_{y}}`
+* with :math:`\text{aeei\_factor}_{n,s,y=1} = 1`. Therefore, choosing the :math:`\text{aeei}_{n,s,y}` coefficients appropriately offers the possibility to calibrate MACRO to a certain energy demand trajectory
 * from MESSAGE.
 *
 ***
@@ -278,7 +278,7 @@ PRODENE(node_active, sector, year) * aeei_factor(node_active, sector, year)
 * Energy system costs are based on a previous MESSAGE model run. The approximation of energy system costs in vicinity of the MESSAGE solution are approximated by a Taylor expansion with the
 * first order term using shadow prices :math:`\text{eneprice}_{s, y, n}` of the MESSAGE model's solution and a quadratic second-order term.
 *
-* .. math:: \text{EC}_{n, y} =  & \text{total_cost}_{n, r} \\
+* .. math:: \text{EC}_{n, y} =  & \text{total\_cost}_{n, r} \\
 *                        + & \displaystyle \sum_{s} \text{eneprice}_{s, y, n} \cdot \left( \text{PHYSENE}_{n, s, y} - \text{enestart}_{s, y, n} \right) \\
 *                        + & \displaystyle \sum_{s} \frac{\text{eneprice}_{s, y, n}}{\text{enestart}_{s, y, n}} \cdot \left( \text{PHYSENE}_{n, s, y} - \text{enestart}_{s, y, n} \right)^2 \qquad \forall{ n, y > 1}
 *