Parameters

Parameteres are values used in MIMOSA that can be changed without changing the code. A new parameter called new_param can be added in the get_constraints function of any component:

def get_constraints(m):
    # ... existing code ...

    m.new_param = Param()

    # ... existing code ...

This creates an abstract parameter (without a value). It still needs a value. This can be done for scalars (non-regional parameters) using the default configuration file and for regional parameters using CSV input values.

Parameters from config file: non-regional parameters

All parameters that are not regional have an entry in the config_default.yaml file (located in the folder mimosa/inputdata/config/). This defines the type of the parameter (numerical, boolean, string, etc.), the default value, and the range of possible values. For example, the following entry defines the parameter economics - PRTP:

mimosa/inputdata/config/config_default.yaml

...
economics:
  PRTP:
    descr: Pure rate of time preference
    type: float
    min: 0
    max: 0.2
    default: 0.015
...

Each parameter entry in the configuration file contains the following fields:

• descr: A description of the parameter
• type: The type of the parameter (e.g. float, int, str, bool, ...)
• default: The default value of the parameter
• Optionally some extra fields depending on the type of parameter

The next step is to link this configuration entry to the Param in MIMOSA. This is done using the doc field when defining the Param:

m.PRTP = Param(doc="::economics.PRTP")

Note that the config_default.yaml file is structured as a nested dictionary. In this case, the PRTP parameter is located within the economics group. This structure can be arbitrary and doesn't need to match the name of the component. It is purely used to structure the configuration file.

When running MIMOSA, the command params = load_params() loads all the default values from the configuration file as a nested dictionary. These values can be changed by modifying the params dictionary:

from mimosa import MIMOSA, load_params

params = load_params() 
params["economics"]["PRTP"] = 0.001
...

After this step, MIMOSA always double checks the dictionary params to check if all the parameter values have the correct type and match specifications of the configuration entry (for example, if the value is within the specified range). If not, MIMOSA will raise an error.

Types of parameter values

In the example above, the PRTP has a type float. The following types are supported (especially note that for numerical values with units (values that are not dimensionless), the type quantity should be used):

Parser types

float

Numerical value (float)

Extra properties:

• min: lower bound of parameter (default: -inf)
• max: upper bound of parameter (default: +inf)

Example usage:

time:
  dt:
    default: 5
    descr: Timestep in years
    max: 20
    min: 0.5
    type: float

int

Numerical value (integer)

Extra properties:

• min: lower bound of parameter (default: -inf)
• max: upper bound of parameter (default: +inf)

Example usage:

time:
  start:
    default: 2020
    descr: Year in which the model starts
    max: 2100
    min: 1900
    type: int

bool

Boolean value (true or false).

Example usage:

economics:
  damages:
    ignore damages:
      default: false
      descr: Flag to not take into account the damages in the GDP (but damages are calculated)
      type: bool

str

String value

enum

Enum (discrete list of options)

Extra properties:

• values: list of allowed values

Example usage:

SSP:
  default: SSP2
  descr: SSP, used for population, baseline GDP and baseline emissions
  type: enum
  values:
  - SSP1
  - SSP2
  - SSP3
  - SSP4
  - SSP5

quantity

Quantity (value with unit). The provided value will be converted to the unit, if possible.

For example, if the unit of a parameter is GtCO2, and the parameter value provided by the user is "1000 MtCO2", the value will be converted automatically to "1 GtCO2". The value passed to MIMOSA will therefore be 1, and not 1000. If the user provides "1000 US$", MIMOSA will raise an exception, as this cannot be converted to GtCO2.

Extra properties:

• unit: Unit of the quantity

Example usage:

economics:
  MAC:
    gamma:
      default: 2601 USD2005/tCO2
      descr: Calibration level of the MAC (carbon price for 100% reduction)
      type: quantity
      unit: currency_unit/emissionsrate_unit

list

List of values. The values are also parsed individually, depending on the parser type given in the property values.

Extra properties:

• values: parser information for the values. For example, the values can be int, float, values with units, etc.

Example usage:

regionsmappings:
  default:
  - conversiontable: inputdata/regions/IMAGE26_COACCH.csv
    regionstype1: IMAGE26
    regionstype2: COACCH
  - conversiontable: inputdata/regions/IMAGE26_ADRICE2010.csv
    regionstype1: IMAGE26
    regionstype2: ADRICE2010
  - conversiontable: inputdata/regions/IMAGE26_ADRICE2012.csv
    regionstype1: IMAGE26
    regionstype2: ADRICE2012
  descr: List of region types and their conversion tables. Only used for regional parameters,
    not for aggregating or disaggregating variables or other output.
  type: list
  values:
    descr: Dictionary with keys `regionstype1`, `regionstype2` and `conversiontable`.
    type: dict

dict

Dictionary with keys and values. The values are also parsed individually, depending on the parser type given in the property values.

Extra properties:

• values: parser information for the values. For example, the values can be int, float, values with units, etc.
• keys: parser information for the keys

Example usage:

regional_parameter_files:
  default:
    COACCH:
      filename: inputdata/regionalparams/COACCH.csv
      regionstype: COACCH
    MAC:
      filename: inputdata/regionalparams/mac.csv
      regionstype: IMAGE26
    economics:
      filename: inputdata/regionalparams/economics.csv
      regionstype: IMAGE26
  descr: Dictionary of regional parameter files. If the regionstype of the file is different
    from the regionstype of the model, the file is converted using the `regionsmappings`
    parameter.
  keys:
    descr: Names of the parameter category (e.g. 'MAC', 'damage', 'adaptation', etc.)
      used when assigning the values to the regional parameters.
    type: str
  type: dict
  values:
    descr: Dictionary with keys `filename` and `regionstype`
    type: dict

datasource

Data source for a variable. It's a dictionary with the keys variable, unit, scenario, model, and file.

Example usage:

input:
  variables:
    GDP:
      default:
        file: inputdata/data/data_IMAGE_SSP.csv
        model: IMAGE
        scenario: '{SSP}-Ref-SPA0-V17'
        unit: currency_unit
        variable: GDP|PPP
      descr: Data source of GDP
      type: datasource

filepath

Filepath value. Currently exactly the same as the string type.

str_or_plain_dict

Either a string or a dictionary. The keys/values of the dictionary are not checked or parsed separately.

Regional parameters

The configuration file can be used to set scalar parameters. However, some parameters are regional. These are created like:

m.new_regional_param = Param(m.regions)

Initializing their value is done in three steps:

1. Create a CSV file with a column region and the columns with regional parameter values you want to use:

   In the folder mimosa/inputdata/regionalparams/, create a new CSV file:

   mimosa
   │   ...
   │
   └─── inputdata
       └─── config
           │   config_default.csv
       └─── regionalparams
           │   economics.csv
           |   mac.csv 
           |   newfile.csv
           |   ...
   

   This file should have at least a column region and one (or more) columns for the regional values:

   mimosa/inputdata/regionalparams/newfile.csv

   region	newparam1	newparam2	...
   CAN	1.992	2.317	...
   USA	2.035	1.745
   ...	...	...

   Note that this file can contain multiple columns (for multiple regional parameters). It is good practice to group the parameter values when the parameters are somehow related with each other.

   ---

2. Register this regional parameter file in the configuration file under the key regional_parameter_files:

   mimosa/inputdata/config/config_default.yaml

   ...
   regional_parameter_files:
     ...
     default:
       economics:
         filename: inputdata/regionalparams/economics.csv
         regionstype: IMAGE26
       newparamgroup:
         filename: inputdata/regionalparams/newfile.csv
         regionstype: IMAGE26
       ...
   

   What if my parameter values have a different regional resolution?

   Todo

   ---

3. Link the Param to the relevant column in the CSV file:

   m.new_regional_param = Param(m.regions, doc="regional::newparamgroup.newparam1")
   

Time and region dependent data

The third type of parameters are time and region dependent parameters. This is typically used for baseline data, such as population, GDP, etc.

They are defined like any other parameter, but with the time and regions dimensions. For example, the population data is defined as:

m.population = Param(
    m.t,
    m.regions,
    doc="timeandregional::population",
    units=quant.unit("billion people"), # (1)!
)

1. The units field is optional, but it is good practice to include it. This is especially important for numerical values with units (values that are not dimensionless). The quant module is imported as quant from the mimosa package.

Just like regional parameters, the parameter values are linked to the underlying data using the doc field, starting with timeandregional::. The input data source should be in IAMC format. For each parameter, the filename, variable, scenario and model should be specified in the configuration file:

mimosa/inputdata/config/config_default.yaml

...
input:
  variables:
    population: # (1)!
      descr: Data source of population
      type: datasource
      default:
        variable: Population
        unit: population_unit
        scenario: "{SSP}-Ref-SPA0-V17"
        model: IMAGE
        file: inputdata/data/data_IMAGE_SSP.csv
    ...

1. The name defined here (population) should match the name used in the doc field of the parameter definition: timeandregional::population.

The file field should point to the IAMC formatted data file. The IAMC format is a CSV file with the following columns:

mimosa/inputdata/data/data_IMAGE_SSP.csv

Model	Scenario	Region	Variable	Unit	2010	2020	2030	2040	2050	2060	2070	2080	2090	2100
IMAGE	SSP1-Ref-SPA0-V17	BRA	GDP|PPP	billion US$2005/yr	1967.58	2679.72	3829.08	5331.48	6912.49	8386.99	9572.49	10475.8	11043.6	11245.4
IMAGE	SSP2-Ref-SPA0-V17	BRA	GDP|PPP	billion US$2005/yr	1967.58	2697.05	3618.3	4491.94	5378.44	6285.55	7175.7	8083.65	8970.67	9881.11
IMAGE	SSP3-Ref-SPA0-V17	BRA	GDP|PPP	billion US$2005/yr	1967.58	2714.89	3464.9	3888.87	4152.04	4333.24	4462.94	4575.67	4633.92	4679.27
...	...	...	...

Configuration values dependent on other parameter values

In the example above, the name of the scenario depends on the SSP. Every string in the configuration file can contain references to other parameters, and are referred to using curly brackets {}. If you want to refer to a nested parameter (like effort sharing > regime), they should be joined with -:

scenario: "Scenario-with-{SSP}-and-{effort sharing - regime}"

Advanced: dynamic parameter settings

Advanced: complex parameter manipulations with instantiate_params.py