Skip to content

Commit

Permalink
Merge pull request #275 from iiasa/parameter_doc_new
Browse files Browse the repository at this point in the history 
Addition of parameter definitions in MESSAGEix documentation
  • Loading branch information
@GamzeUnlu95
GamzeUnlu95 authored Dec 19, 2019
2 parents 40ad4b5 + 8ea28c2 commit 357fb37
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 36 deletions.
6 changes: 6 additions & 0 deletions message_ix/model/MESSAGE/model_core.gms
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1174,6 +1174,8 @@ TOTAL_CAPACITY_BOUND_LO(node,inv_tec,year)$( is_bound_total_capacity_lo(node,inv
;

***
* .. _activity_bound_up:
*
* Equation ACTIVITY_BOUND_UP
* """"""""""""""""""""""""""
* This constraint provides upper bounds by mode of a technology activity, summed over all vintages.
Expand Down Expand Up @@ -1214,6 +1216,8 @@ ACTIVITY_BOUND_ALL_MODES_UP(node,tec,year,time)$( is_bound_activity_up(node,tec,
;

***
* .. _acitvity_bound_lo:
*
* Equation ACTIVITY_BOUND_LO
* """"""""""""""""""""""""""
* This constraint provides lower bounds by mode of a technology activity, summed over
Expand Down Expand Up @@ -1258,6 +1262,8 @@ ACTIVITY_BOUND_ALL_MODES_LO(node,tec,year,time)$( bound_activity_lo(node,tec,yea

*----------------------------------------------------------------------------------------------------------------------*
***
* .. _share_constraints:
*
* Constraints on shares of technologies and commodities
* -----------------------------------------------------
* This section allows to include upper and lower bounds on the shares of modes used by a technology
Expand Down
113 changes: 77 additions & 36 deletions message_ix/model/MESSAGE/parameter_def.gms
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,12 @@ Parameters
* Parameters of the `Resources` section
* -------------------------------------
*
* In |MESSAGEix|, the volume of resources at the start of the model horizon is defined by ``resource_volume``. The quantity of the
* resources that are extracted per year is dependent on two parameters. The first is ``bound_extraction_up``, which constraints
* the maximum extraction of the resources (by grade) in a year. The second is ``resource_remaining``, which is the maximum
* extraction of the remaining resources in a certain year, as a percentage. Extraction costs for resources are represented by
* ``resource_cost`` parameter.
*
* .. list-table::
* :widths: 25 75
* :header-rows: 1
Expand All @@ -92,8 +98,8 @@ Parameters
* * - historical_extraction [#hist]_
* - ``node`` | ``commodity`` | ``grade`` | ``year``
*
* .. [#stock] This parameter allows (exogenous) additions to the commodity stock over the model horizon,
* e.g., precipitation that replenishes the water table.
* .. [#stock] Commodity stock refers to an exogenous (initial) quantity of commodity in stock. This parameter allows
* (exogenous) additions to the commodity stock over the model horizon, e.g., precipitation that replenishes the water table.
*
* .. [#hist] Historical values of new capacity and activity can be used for parametrising the vintage structure
* of existing capacity and implement dynamic constraints in the first model period.
Expand Down Expand Up @@ -126,12 +132,13 @@ Parameter
* - ``node`` | ``commodity`` | ``year``
*
* .. [#demand] The parameter ``demand`` in a ``MESSAGE``-scheme ``ixmp``.Scenario is translated
* to the parameter ``demand_fixed`` in the MESSAGE implementation in GAMS. The variable ``DEMAND`` is introduced
* to the parameter ``demand_fixed`` in the |MESSAGEix| implementation in GAMS. The variable ``DEMAND`` is introduced
* as an auxiliary reporting variable; it equals ``demand_fixed`` in a `MESSAGE`-standalone run and reports
* the final demand including the price response in an iterative `MESSAGE-MACRO` solution.
*
* .. [#peakload] The parameters ``peak_load_factor`` and ``reliability_factor`` are based on the formulation proposed
* by Sullivan et al., 2013 :cite:`sullivan_VRE_2013`. It is used in :ref:`reliability_constraint`.
* .. [#peakload] The parameters ``peak_load_factor`` (maximum peak load factor for reliability constraint of firm capacity) and
* ``reliability_factor`` (reliability of a technology (per rating)) are based on the formulation proposed by Sullivan et al., 2013 :cite:`sullivan_VRE_2013`.
* It is used in :ref:`reliability_constraint`.
*
***

Expand All @@ -150,11 +157,11 @@ Parameter
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*
* .. list-table::
* :widths: 25 75
* :widths: 25 60
* :header-rows: 1
*
* * - Parameter name
* - Index names
* - Index dimensions
* * - input [#tecvintage]_
* - ``node_loc`` | ``tec`` | ``year_vtg`` | ``year_act`` | ``mode`` |
* ``node_origin`` | ``commodity`` | ``level`` | ``time`` | ``time_origin``
Expand All @@ -169,7 +176,7 @@ Parameter
* - ``node_loc`` | ``tec`` | ``year_vtg`` | ``year_act`` | ``mode`` | ``time``
* * - levelized_cost [#levelizedcost]_
* - ``node_loc`` | ``tec`` | ``year_vtg`` | ``time``
* * - construction_time
* * - construction_time [#construction]_
* - ``node_loc`` | ``tec`` | ``year_vtg``
* * - technical_lifetime
* - ``node_loc`` | ``tec`` | ``year_vtg``
Expand All @@ -183,11 +190,11 @@ Parameter
* - ``node`` | ``technology`` | ``year_act`` | ``commodity`` | ``level`` | ``time`` | ``rating``
* * - reliability_factor [#peakload]_
* - ``node`` | ``technology`` | ``year_act`` | ``commodity`` | ``level`` | ``time`` | ``rating``
* * - flexibility_factor
* * - flexibility_factor [#flexfactor]_
* - ``node_loc`` | ``technology`` | ``year_vtg`` | ``year_act`` | ``mode`` | ``commodity`` | ``level`` | ``time`` | ``rating``
* * - renewable_capacity_factor
* * - renewable_capacity_factor [#renewables]_
* - ``node_loc`` | ``commodity`` | ``grade`` | ``level`` | ``year``
* * - renewable_potential
* * - renewable_potential [#renewables]_
* - ``node`` | ``commodity`` | ``grade`` | ``level`` | ``year``
* * - emission_factor
* - ``node_loc`` | ``tec`` | ``year_vtg`` | ``year_act`` | ``mode`` | ``emission``
Expand All @@ -202,9 +209,14 @@ Parameter
* .. [#construction] The construction time only has an effect on the investment costs; in |MESSAGEix|,
* each unit of new-built capacity is available instantaneously at the beginning of the model period.
*
* .. [#rating] The upper bound of a contribution by any technology to the constraints on system reliability
* (:ref:`reliability_constraint`) and flexibility (:ref:`flexibility_constraint`) can depend on the share
* of the technology output in the total commodity use at a specific level.
* .. [#rating] Maximum share of technology in commodity use per rating. The upper bound of a contribution by any technology to the constraints on system reliability
* (:ref:`reliability_constraint`) and flexibility (:ref:`flexibility_constraint`) can depend on the share of the technology output in the total commodity use at
* a specific level.
*
* .. [#flexfactor] Contribution of technologies towards operation flexibility constraint. It is used in :ref:`flexibility_constraint`.
*
* .. [#renewables] ``renewable_capacity_factor`` refers to the quality of renewable potential by grade and ``renewable_potential`` refers to the size of the renewable potential per grade.
*
***

Parameters
Expand Down Expand Up @@ -234,10 +246,11 @@ Parameters
* Bounds on capacity and activity
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*
* The following parameters specify upper and lower bounds on new capacity, total installed capacity, and activity.
* The following parameters specify upper and lower bounds on new capacity, total installed capacity, and activity. The bounds
* on activity are implemented as the aggregate over all vintages in a specific period (:ref:`activity_bound_up` and :ref:`acitvity_bound_lo`).
*
* .. list-table::
* :widths: 20 80
* :widths: 25 60
* :header-rows: 1
*
* * - Parameter name
Expand All @@ -255,8 +268,6 @@ Parameters
* * - bound_activity_lo
* - ``node_loc`` | ``tec`` | ``year_act`` | ``mode`` | ``time``
*
* The bounds on activity are implemented as the aggregate over all vintages in a specific period
* (cf. Equation ``ACTIVITY_BOUND_UP`` and ``ACTIVITY_BOUND_LO``).
***

Parameters
Expand All @@ -272,7 +283,9 @@ Parameters
* Dynamic constraints on capacity and activity
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*
* The following parameters specify constraints on the growth of new capacity and activity, i.e., market penetration.
* The following parameters specify constraints on the growth of new capacity and activity, i.e., market penetration. The implementation of |MESSAGEix|
* includes the functionality for 'soft' relaxations of dynamic constraints on new-built capacity and activity (see Keppo and Strubegger, 2010
* :cite:`keppo_short_2010`). For more information, please refer to the equations in section :ref:`dynamic_constraints` of the mathematical formulation.
*
* .. list-table::
* :widths: 30 70
Expand Down Expand Up @@ -339,9 +352,13 @@ Parameters
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*
* The implementation of |MESSAGEix| includes the functionality to introduce "add-on technologies" that are specifically
* linked to parent technologies. This feature can be used to model mitigation options (scrubber, cooling).
* Note, that no default addon_conversion is set, to avoid default conversion factors of 1 being set for technologies
* with mutiple modes, of which only a single mode should be linked to the add-on technology.
* linked to parent technologies. This feature can be used to model mitigation options (scrubber, cooling). Upper and
* lower bounds of add-on technologies are defined relative to the parent: ``addon_up`` and ``addon_lo``, respectively.
*
* .. note::
* No default ``addon_conversion`` factor (conversion factor between add-on and parent technology activity) is set.
* This is to avoid default conversion factors of 1 being set for technologies with multiple modes, of which only a
* single mode should be linked to the add-on technology.
*
* .. list-table::
* :widths: 20 80
Expand All @@ -356,7 +373,6 @@ Parameters
* * - addon_lo
* - ``node`` | ``tec`` | ``vintage`` | ``year`` | ``mode`` | ``time`` | ``type_addon``
*
* The upper bound of
***

Parameters
Expand All @@ -375,7 +391,8 @@ Parameters
*
* The implementation of |MESSAGEix| includes the functionality for 'soft' relaxations of dynamic constraints on
* new-built capacity and activity (see Keppo and Strubegger, 2010 :cite:`keppo_short_2010`).
* Refer to the section :ref:`dynamic_constraints`.
* Refer to the section :ref:`dynamic_constraints`. Absolute cost and levelized cost multipliers are used
* for the relaxation of upper and lower bounds.
*
* .. list-table::
* :widths: 20 80
Expand Down Expand Up @@ -437,13 +454,35 @@ Parameters

Parameters
historical_new_capacity(node,tec,year_all) historical new capacity
historical_activity(node,tec,year_all,mode,time) historical acitivity
historical_activity(node,tec,year_all,mode,time) historical activity
;

***
* Auxiliary investment cost parameters and multipliers
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Documentation not yet included.
*
* Auxiliary investment cost parameters include the remaining technical lifetime at the end of model horizon (``beyond_horizon_lifetime``) in addition to the
* different scaling factors and multipliers as listed below. These factors account for remaining capacity (``remaining_capacity``) or construction time of new capacity (``construction_time_factor``),
* the value of investment at the end of model horizon (``end_of_horizon_factor``) or the discount factor of remaining lifetime beyond model horizon (``beyond_horizon_factor``).
*
* .. list-table::
* :widths: 35 50
* :header-rows: 1
*
* * - Parameter name
* - Index names
* * - construction_time_factor
* - ``node`` | ``tec`` | ``year_all``
* * - remaining_capacity
* - ``node`` | ``tec`` | ``year_all``
* * - end_of_horizon_factor
* - ``node`` | ``tec`` | ``year_all``
* * - beyond_horizon_lifetime
* - ``node`` | ``tec`` | ``year_all``
* * - beyond_horizon_factor
* - ``node`` | ``tec`` | ``year_all``
*
*
***

Parameters
Expand All @@ -464,7 +503,7 @@ Parameters
*
* The implementation of |MESSAGEix| includes a flexible and versatile accounting of emissions across different
* categories and species, with the option to define upper bounds and taxes on various (aggregates of) emissions
* and pollutants), (sets of) technologies, and (sets of) years.
* and pollutants, (sets of) technologies, and (sets of) years.
*
* .. list-table::
* :widths: 25 75
Expand All @@ -481,13 +520,14 @@ Parameters
* * - tax_emission
* - ``node`` | ``type_emission`` | ``type_tec`` | ``type_year``
*
* .. [#em_scaling] The parameters ``emission_scaling`` allows to efficiently aggregate different emissions/pollutants
* and set bounds or taxes on various categories.
* .. [#em_scaling] The parameter ``emission_scaling`` is the scaling factor to harmonize bounds or taxes across types of
* emissions. It allows to efficiently aggregate different emissions/pollutants and set bounds or taxes on various categories.
*
***

Parameters
historical_emission(node,emission,type_tec,year_all) historical emissions by technology type (including land)
emission_scaling(type_emission,emission) scaling factor to harmonize bounds or taxes across tpes
emission_scaling(type_emission,emission) scaling factor to harmonize bounds or taxes across types
bound_emission(node,type_emission,type_tec,type_year) upper bound on emissions
tax_emission(node,type_emission,type_tec,type_year) emission tax
;
Expand All @@ -502,7 +542,7 @@ Parameters
*
* The implementation of |MESSAGEix| includes a land-use model emulator, which draws on exogenous land-use scenarios
* (provided by another model) to derive supply of commodities (e.g., biomass) and emissions
* from agriculture and forestry.
* from agriculture and forestry. The parameters listed below refer to the assigned land scenario.
*
* .. list-table::
* :widths: 25 75
Expand Down Expand Up @@ -572,7 +612,8 @@ Parameters
* Parameters of the `Share Constraints` section
* ---------------------------------------------
*
* Share constraints define the share of a given commodity to be active on a certain level
* Share constraints define the share of a given commodity/mode to be active on a certain level. For the mathematical
* formulation, refer to :ref:`share_constraints`.
*
* .. list-table::
* :widths: 25 75
Expand Down Expand Up @@ -606,9 +647,9 @@ Parameters
* Parameters of the `Relations` section
* -------------------------------------
*
* Generic linear relations are implemented in |MESSAGEix|.
* This feature is intended for development and testing only - all new features should be implemented
* as specific new mathematical formulations and associated sets & parameters.
* Generic linear relations are implemented in |MESSAGEix|. This feature is intended for development and testing only - all new features
* should be implemented as specific new mathematical formulations and associated *sets* & *parameters*. For the formulation of the relations,
* refer to :ref:`section_of_generic_relations`.
*
* .. list-table::
* :widths: 25 75
Expand Down Expand Up @@ -650,7 +691,7 @@ Parameters
*
* The following parameters allow to set variable values to a specific value.
* The value is usually taken from a solution of another model instance
* (e.g., scenarios where a shock sets in later to mimick imperfect foresight).
* (e.g., scenarios where a shock sets in later to mimic imperfect foresight).
*
* The fixed values do not override any upper or lower bounds that may be defined,
* so fixing variables to values outside of that range will yield an infeasible model.
Expand Down

0 comments on commit 357fb37

Please sign in to comment.