Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Addition of parameter definitions in MESSAGEix documentation #275

Merged
merged 7 commits into from
Dec 19, 2019
Merged

Addition of parameter definitions in MESSAGEix documentation #275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bb8a35b
Add parameter definitions for MESSAGEix
GamzeUnlu95 Nov 27, 2019
800c35a
Update parameter definitions
GamzeUnlu95 Dec 3, 2019
a151b45
review of docu additions by Gamze and correction of typos
francescolovat Dec 12, 2019
a521779
corrected docu to address issue #51
francescolovat Dec 12, 2019
7a7a4a0
revert of commit a521779a69c110946e004ee520bad6339cd854b5
francescolovat Dec 13, 2019
cc2c265
Merge remote-tracking branch 'upstream/master' into parameter_doc_new
francescolovat Dec 19, 2019
8ea28c2
last_changes_before_merge_with_Gamze
francescolovat Dec 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions message_ix/model/MESSAGE/model_core.gms
View file
Open in desktop
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
Open in desktop
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``).
*
GamzeUnlu95 marked this conversation as resolved.
Show resolved Hide resolved
* .. 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