Merge pull request #276 from olorinthewhite/master

Amendment of the "mathematical description"

doc/api.rst

@@ -1,4 +1,4 @@
-'urbs' module description
+'urbs' Module Description
 =========================
 This part gives a brief overview over the architecture of the program.
 The data flow in an urbs model is visualized in the following graph:
@@ -16,7 +16,7 @@ functions will be discussed. The scripts used for these are the following
 
 identify.py
 ~~~~~~~~~~~
-In this scripts the dictionary of input dataframes 'data' is parsed to conclude
+In this script the dictionary of input dataframes 'data' is parsed to conclude
 the structure of the problem to be built.
 
 .. automodule:: urbs.identify

doc/implementation.rst

@@ -3,7 +3,7 @@
 Model Implementation
 ********************
 
-In this Section the **implementation** of the theoretical concepts of the model
+In this section the **implementation** of the theoretical concepts of the model
 is described. This includes listing and describing all relevant sets,
 parameters, variables and constraints linking mathematical notation with the
 corresponding code fragment. 

doc/implementdoc/equ-commodity.rst

@@ -3,7 +3,7 @@
 Commodity Constraints
 ^^^^^^^^^^^^^^^^^^^^^
 
-**Commodity Balance** The function commodity balance calculates the in- and
+**Commodity Balance**: The function commodity balance calculates the in- and
 outflows into all processes, storages and transmission of a commodity :math:`c`
 in a site :math:`v` in support timeframe :math:`y` at a timestep :math:`t`. The
 value of the function :math:`\mathrm{CB}` being greater than zero
@@ -93,7 +93,7 @@ annually by the energy system in the site :math:`v` and support timeframe
 :math:`y`. This amount is limited by the parameter maximum annual stock supply
 limit per vertex :math:`\overline{L}_{yvc}`. The annual usage of stock
 commodity is calculated by the sum of the products of the parameter weight
-:math:`w` and the parameter stock commodity source term :math:`\rho_{yvct}`,
+:math:`w` and the variable stock commodity source term :math:`\rho_{yvct}`,
 summed over all timesteps :math:`t \in T_m`. The mathematical explanation of
 this rule is given in :ref:`theory-min`.
 
@@ -119,7 +119,7 @@ at the timestep :math:`t`. The limit is defined by the parameter maximum sell
 supply limit per hour :math:`\overline{g}_{yvc}`. To satisfy this constraint,
 the value of the variable sell commodity source term :math:`\varrho_{yvct}`
 must be less than or equal to the value of the parameter maximum sell supply
-limit per hour :math:`\overline{g}_{vc}` multiplied with the length of the
+limit per hour :math:`\overline{g}_{yvc}` multiplied with the length of the
 time steps :math:`\Delta t`. The mathematical explanation of this rule is given
 in :ref:`theory-buysell`.
 
@@ -142,7 +142,7 @@ sold annually by the energy system in the site :math:`v` and support timeframe
 :math:`y`. The limit is defined by the parameter maximum annual sell supply
 limit per vertex :math:`\overline{G}_{yvc}`. The annual usage of sell commodity
 is calculated by the sum of the products of the parameter weight :math:`w` and
-the parameter sell commodity source term :math:`\varrho_{yvct}`, summed over
+the variable sell commodity source term :math:`\varrho_{yvct}`, summed over
 all timesteps :math:`t \in T_m`. The mathematical explanation of this rule is
 given in :ref:`theory-buysell`.
 
@@ -166,7 +166,7 @@ timestep :math:`t`. The limit is defined by the parameter maximum buy
 supply limit per time step :math:`\overline{b}_{yvc}`. To satisfy this
 constraint, the value of the variable buy commodity source term
 :math:`\psi_{yvct}` must be less than or equal to the value of the parameter
-maximum buy supply limit per time step :math:`\overline{b}_{vc}`, multiplied by
+maximum buy supply limit per time step :math:`\overline{b}_{yvc}`, multiplied by
 the length of the time steps :math:`\Delta t`. The mathematical explanation of
 this rule is given in :ref:`theory-buysell`.
 
@@ -189,9 +189,9 @@ energy system in the site :math:`v` in support timeframe :math:`y`. The limit
 is defined by the parameter maximum annual buy supply limit per vertex
 :math:`\overline{B}_{yvc}`. To satisfy this constraint, the annual usage of buy
 commodity must be less than or equal to the value of the parameter buy supply
-limit per vertex :math:`\overline{B}_{vc}`. The annual usage of buy commodity
+limit per vertex :math:`\overline{B}_{yvc}`. The annual usage of buy commodity
 is calculated by the sum of the products of the parameter weight :math:`w` and
-the parameter buy commodity source term :math:`\psi_{yvct}`, summed over all
+the variable buy commodity source term :math:`\psi_{yvct}`, summed over all
 modeled timesteps :math:`t \in T_m`. The mathematical explanation of this rule
 is given in :ref:`theory-buysell`.
 
@@ -209,7 +209,7 @@ calculated by the following code fragment:
 
 
 **Environmental Output Per Step Rule**: The constraint environmental output per
-step rule applies only for commodities of type "Env"
+step rule applies only for commodities of type ":ref:`Env <env-commodity-def>`"
 (:math:`c \in C_\text{env}`). This constraint limits the amount of
 environmental commodity :math:`c \in C_\text{env}`, that can be released to
 environment by the energy system in the site :math:`v` in support timeframe
@@ -218,7 +218,7 @@ maximum environmental output per time step :math:`\overline{m}_{yvc}`. To
 satisfy this constraint, the negative value of the commodity balance for the
 given environmental commodity :math:`c \in C_\text{env}` must be less than or
 equal to the value of the parameter maximum environmental output per time step
-:math:`\overline{m}_{vc}`, multiplied by the length of the time steps
+:math:`\overline{m}_{yvc}`, multiplied by the length of the time steps
 :math:`\Delta t`. The mathematical explanation of this rule is given
 in :ref:`theory-min`.
 
@@ -243,7 +243,7 @@ energy system in the site :math:`v` in support timeframe :math:`y`. The limit
 is defined by the parameter maximum annual environmental output limit per
 vertex :math:`\overline{M}_{yvc}`. To satisfy this constraint, the annual
 release of environmental commodity must be less than or equal to the value of
-the parameter maximum annual environmental output :math:`\overline{M}_{vc}`.
+the parameter maximum annual environmental output :math:`\overline{M}_{yvc}`.
 The annual release of environmental commodity is calculated by the sum of the
 products of the parameter weight :math:`w` and the negative value of commodity
 balance function, summed over all modeled time steps :math:`t \in T_m`. The
@@ -364,7 +364,7 @@ a set recovery period :math:`o_{yvc}`. Since the recovery period
 by the length of the time steps :math:`\Delta t`. The mathematical explanation
 of this rule is given in :ref:`theory-dsm`.
 
-In script ``dsm.py`` the constraint DSM Recovery rule is defined by the
+In script ``dsm.py`` the constraint DSM recovery rule is defined by the
 following code fragment:
 
 ::
@@ -384,16 +384,16 @@ Global Environmental Constraint
 
 **Global CO2 Limit Rule**: The constraint global CO2 limit rule applies to the
 whole energy system in one support timeframe :math:`y`, that is to say it
-applies to every site and timestep. This constraints restricts the total amount
-of CO2 to environment. The constraint states that the sum of released CO2
-across all sites :math:`v\in V` and timesteps :math:`t \in t_m` must be less
+applies to every site and timestep. This constraint restricts the total amount
+of CO2 emission to environment. The constraint states that the sum of released CO2
+across all sites :math:`v\in V` and timesteps :math:`t \in T_m` must be less
 than or equal to the parameter maximum global annual CO2 emission limit
 :math:`\overline{L}_{CO_{2},y}`, where the amount of released CO2 in a single
 site :math:`v` at a single timestep :math:`t` is calculated by the product of
 commodity balance of environmental commodities :math:`\mathrm{CB}(y,v,CO_{2},t)`
 and the parameter weight :math:`w`. This constraint is skipped if the value of
-the parameter :math:`\overline{L}_{CO_{2}}` is set to ``inf``. The mathematical
-explanation of this rule is given in :ref:`theory-min`.
+the parameter :math:`\overline{L}_{CO_{2},y}` is set to ``inf``. The mathematical
+explanation of this rule is given in :ref:`Multinode Optimization Model<Global CO2 Limit>` .
 
 In script ``model.py`` the constraint annual global CO2 limit rule is defined
 and calculated by the following code fragment:
@@ -403,12 +403,12 @@ and calculated by the following code fragment:
 
 **Global CO2 Budget Rule**: The constraint global CO2 budget rule applies to
 the whole energy system over the entire modeling horizon, that is to say it
-applies to every support timeframe, site and timestep. This constraints
-restricts the total amount of CO2 to environment. The constraint states that
+applies to every support timeframe, site and timestep. This constraint
+restricts the total amount of CO2 emission to environment. The constraint states that
 the sum of released CO2 across all support timeframe :math:`y\in Y`, sites
-:math:`v\in V` and timesteps :math:`t \in t_m` must be less than or equal to
+:math:`v\in V` and timesteps :math:`t \in T_m` must be less than or equal to
 the parameter maximum global CO2 emission budget
-:math:`\overline{\overline{L}}_{CO_{2},y}`, where the amount of released CO2 in
+:math:`\overline{\overline{L}}_{CO_{2}}`, where the amount of released CO2 in
 a single support timeframe :math:`y` in a single site :math:`v` and at a single
 timestep :math:`t` is calculated by the product of the commodity balance of
 environmental commodities :math:`\mathrm{CB}(y,v,CO_{2},t)` and the parameter

doc/implementdoc/equ-costs.rst

@@ -10,8 +10,8 @@ the following expression:
 
 .. math::
     \zeta = \zeta_\text{inv} + \zeta_\text{fix} + \zeta_\text{var} +
-    \zeta_\text{fuel} + \zeta_\text{rev} + \zeta_\text{pur} +
-    \zeta_\text{startup} \leq \overline{L}_{cost}
+    \zeta_\text{fuel} + \zeta_\text{env} + \zeta_\text{rev} +
+    \zeta_\text{pur} \leq \overline{L}_{cost}
 
 This constraint is given in ``model.py`` by the following code fragment.  
 

doc/implementdoc/equ-objective.rst

@@ -3,13 +3,13 @@
 .. _objective:
 
 
-Objective function
+Objective Function
 ^^^^^^^^^^^^^^^^^^
 
 There are two possible choices of objective function for urbs problems, either
 the costs (default option) or the total CO2-emissions can be minimized.
 
-If the total CO2-emissions are minimized the objective function takes the form:
+If the total CO2-emissions are minimized, the objective function takes the form:
 
 .. math::
 
@@ -30,8 +30,8 @@ mathematical notation is as following:
 
 .. math::
     \zeta = (\zeta_\text{inv} + \zeta_\text{fix} + \zeta_\text{var} +
-    \zeta_\text{fuel} + \zeta_\text{rev} + \zeta_\text{pur} +
-    \zeta_\text{startup})
+    \zeta_\text{fuel} + \zeta_\text{env} + \zeta_\text{rev} +
+    \zeta_\text{pur})
 
 The calculation of the variable total system cost is given in ``model.py`` by
 the following code fragment.  
@@ -41,8 +41,8 @@ the following code fragment.
 
 The variable total system cost :math:`\zeta` is basically calculated by the
 summation of every type of total costs. As previously mentioned in section
-:ref:`sec-cost-types`, these cost types are : ``Investment``, ``Fix``,
-``Variable``, ``Fuel``, ``Revenue``, ``Purchase``.
+:ref:`sec-cost-types`, these cost types are : ``Invest``, ``Fixed``,
+``Variable``, ``Fuel``, ``Environmental``, ``Revenue``, ``Purchase``.
 
 In script ``model.py`` the individual cost functions are calculated by
 the following code fragment:

doc/implementdoc/equ-process.rst

@@ -72,7 +72,7 @@ a commodity is an intermittent supply commodity :math:`c \in C_\text{sup}`. The
 variable process input commodity flow is defined by the constraint as the
 product of the variable total process capacity :math:`\kappa_{yvp}` and the
 parameter intermittent supply capacity factor :math:`s_{yvct}`, scaled by the 
-size of the time steps :math: `\Delta t`. The mathematical explanation of this
+size of the timesteps :math:`\Delta t`. The mathematical explanation of this
 rule is given in :ref:`theory-min`.
 
 In script ``model.py`` the constraint intermittent supply rule is defined and
@@ -88,12 +88,12 @@ calculated by the following code fragment:
 .. literalinclude:: /../urbs/model.py
    :pyobject: def_intermittent_supply_rule
 
-**Process Throughput By Capacity Rule**: The constraint process throughput by
+**Process Throughput by Capacity Rule**: The constraint process throughput by
 capacity rule limits the variable process throughput :math:`\tau_{yvpt}`. This
 constraint prevents processes from exceeding their capacity. The constraint
 states that the variable process throughput must be less than or equal to the
 variable total process capacity :math:`\kappa_{yvp}`, scaled by the size
-of the time steps :math: `\Delta t`. The mathematical explanation of this rule
+of the timesteps :math:`\Delta t`. The mathematical explanation of this rule
 is given in :ref:`theory-min`.
 
 In script ``model.py`` the constraint process throughput by capacity rule is
@@ -115,7 +115,7 @@ gradient rule limits the process power gradient
 processes from exceeding their maximal possible change in activity from one
 time step to the next. The constraint states that absolute power gradient must
 be less than or equal to the maximal power gradient :math:`\overline{PG}_{yvp}`
-parameter (scaled to capacity and by time step duration). The mathematical
+parameter (scaled to capacity and by timestep duration). The mathematical
 explanation of this rule is given in :ref:`theory-min`.
 
 In script ``model.py`` the constraint process throughput gradient rule is split
@@ -189,7 +189,7 @@ and calculated by the following code fragment:
    :pyobject: res_sell_buy_symmetry_rule
 
 
-**Process time variable output rule**: This constraint multiplies the process
+**Process Time Variable Output Rule**: This constraint multiplies the process
 efficiency with the parameter time series :math:`f_{yvpt}^\text{out}`. The
 process output for all commodities is thus manipulated depending on time. This
 constraint is not valid for environmental commodities since these are typically
@@ -212,7 +212,7 @@ defined and calculated by the following code fragment:
 .. _sec-partial-startup-constr:
 
 
-Process Constraints for partial operation
+Process Constraints for Partial Operation
 -----------------------------------------
 The process constraints for partial operation described in the following are
 only activated if in the input file there is a value set in the column
@@ -226,7 +226,7 @@ and full load. It is important to understand that this partial load formulation
 can only work if its accompanied by a non-zero value for the minimum partial
 load fraction :math:`\underline{P}_{yvp}`.
 
-**Throughput by Min fraction Rule**: This constraint limits the minimal
+**Throughput by Min Fraction Rule**: This constraint limits the minimal
 operational state of a process downward, making sure that the minimal part load
 fraction is honored. The mathematical explanation of this rule is given in
 :ref:`theory-min`.
@@ -245,14 +245,14 @@ following code fragment:
    :pyobject: res_throughput_by_capacity_min_rule
 
 **Partial Process Input Rule**: The link between operational state
-:math:`tau_{yvpt}` and commodity in/outputs is changed from a simple
+:math:`\tau_{yvpt}` and commodity in/outputs is changed from a simple
 linear behavior to a more complex one. Instead of constant in- and output
 ratios these are now interpolated linearly between the value for full operation
 :math:`r^{\text{in/out}}_{yvp}` at full load and the minimum in/output ratios
 :math:`\underline{r}^{\text{in/out}}_{yvp}` at the minimum operation point. The
 mathematical explanation of this rule is given in :ref:`theory-min`.   
 
-In script `model.py` this expression is written in the following way for the
+In script ``model.py`` this expression is written in the following way for the
 input ratio (and analogous for the output ratios):
 ::