Adding parameters and data

Parameters are values used in MIMOSA that can be changed without changing the code.

Adding a parameter

Add a parameter inside a component's get_constraints(m, inputs) function. Import Param from mimosa.common and choose an initializer according to where the values come from:

from mimosa.common import Param, quant

# A fixed value, without a configuration or documentation link
m.new_param = Param(initialize=3.0)

# A value from config_default.yaml
m.PRTP = Param(initialize=inputs.config("economics.PRTP"))

# A value for each region, from a regional parameter CSV
m.init_capitalstock_factor = Param(
    m.regions,
    initialize=inputs.regional("economics", "init_capital_factor"),
)

# Values for each time step and region, from configured input data
m.population = Param(
    m.t, m.regions,
    initialize=inputs.time_regional("population"),
    units=quant.unit("billion people"),
)

Every component receives prepared inputs; you do not need to create it yourself. For configuration lookup, use the full path as one string, such as "economics.PRTP". The input methods also supply the documentation's source metadata in source_key. You can add an optional doc argument for a description, alongside any initializer. Regional and time-dependent values are matched to m.regions and m.t.

The three configurable input types are described below:

Scalar parameters: Scalar parameters (that don't depend on region or time) are defined in the config_default.yaml file and can be modified at runtime by modifying the params dictionary. These parameters are typically used for model settings, such as the pure rate of time preference (PRTP), discount rates, etc.
Regional parameters: Regional parameters (that don't depend on time) are defined in a CSV file and initialized through inputs.regional. These parameters are typically used for regional coefficients for damage functions, emissions factors, etc.
Time and region dependent data: These parameters depend on both time and region, such as population and baseline GDP. Their data comes from CSV files in IAMC format.

1. Parameters from config file: non-regional parameters

Parameters read from configuration 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

Initialize the parameter from its configuration entry, using prepared input lookup:

m.PRTP = Param(initialize=inputs.config("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: Initial timestep length 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: 2025
    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: 2887 USD2010/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:

time:
  periods:
    default:
      2050: 10
    descr: Optional timestep changes, mapping each change year to the timestep length
      in years used after that year
    keys:
      max: 2300
      min: 1901
      type: int
    type: dict
    values:
      max: 20
      min: 0.5
      type: float

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_updated.csv
        model: IMAGE 3.4
        scenario: '{SSP}-Baseline'
        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_num_or_plain_dict

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

2. 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, initialize=inputs.regional("newparamgroup", "newparam1")
)

Initializing their value is done in three steps:

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.yaml
    └─── 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.
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?

Give every regional parameter file a regionstype describing the regions in its region column. If this differs from the model's selected regionstype, MIMOSA looks for a conversion table registered under regionsmappings:
mimosa/inputdata/config/config_default.yaml
```
regionsmappings:
  default:
    - regionstype1: IMAGE26
      regionstype2: NEW_REGIONS
      conversiontable: inputdata/regions/IMAGE26_NEW_REGIONS.csv
```
The conversion CSV must contain columns named IMAGE26 and NEW_REGIONS, with each row connecting regions in the two definitions. The mapping is applied by region_mappers.py. When several source regions map to one target region, numeric parameter values are averaged and non-numeric values use the first value. The same table can also be used in the reverse direction.

This mechanism only converts regional parameter files. It does not aggregate or disaggregate model variables, outputs or time-dependent input data. A new model region definition must also be added to the allowed regionstype values, its region codes must be listed under regions, and time-dependent input data must be available at that resolution.

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

m.new_regional_param = Param(
    m.regions, initialize=inputs.regional("newparamgroup", "newparam1")
)

3. 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 and GDP.

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,
    initialize=inputs.time_regional("population"),
    units=quant.unit("billion people"), # (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). Import quant from mimosa.common. See Units for the standard model units and conversion behaviour.

The lookup selects and interpolates the configured IAMC data source and supplies its documentation metadata automatically. For each input, specify the filename, variable, scenario and model 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}-Baseline"
        model: IMAGE 3.4
        file: inputdata/data/data_IMAGE_SSP_updated.csv
    ...

The name defined here (population) must match the argument to inputs.time_regional("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_updated.csv

Model	Scenario	Region	Variable	Unit	2005	2010	2015	2020	2025	2030	2035	2040	2045	2050	2060	2070	2080	2090	2100
IMAGE 3.4	SSP1-Baseline	BRA	Emissions\|CO2	Mt CO2/yr	2199.87	2039.12	973.075	513.667	1356.38	1022.31	889.333	711.268	595.885	644.763	1236.88	890.895	622.3	332.242	294.228
IMAGE 3.4	SSP1-Baseline	CAN	Emissions\|CO2	Mt CO2/yr	694.244	658.211	673.5	640.166	672.986	627.456	535.89	424.912	334.515	279.017	245.643	236.676	245.991	248.99	241.177
IMAGE 3.4	SSP1-Baseline	CEU	Emissions\|CO2	Mt CO2/yr	819.004	759.19	710.243	706.495	790.84	746.661	675.198	608.905	577.947	537.967	328.471	152.017	161.415	181.708	104.804
...	...	...	...

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 model structure > effortsharing module), they should be joined with -:

scenario: "Scenario-with-{SSP}-and-{model structure - effortsharing module}"

Advanced: explicit input lookup and parameter metadata

Parameter source metadata

Param imported from mimosa.common is a factory that returns a standard Pyomo parameter. Ordinary Pyomo arguments, including initialize, default, units and mutable, work as usual.

The factory also accepts already resolved input values with source metadata:

from mimosa.common import ConcreteModel, Param, SourcedValue

m = ConcreteModel()
m.alpha = Param(
    initialize=SourcedValue(0.3, "::economics.GDP.alpha"),
)
# m.alpha is a Pyomo parameter; m.alpha.source_key is "::economics.GDP.alpha".

SourcedValue does not load or convert data. It carries values and a source key using the existing ::config.path, regional::category.name or timeandregional::variable conventions. The factory stores that key in source_key and passes doc unchanged to Pyomo. For time-and-region parameter cards, an explicit doc takes precedence over the input's configuration description. Without one, the existing description is used.

Ordinary initializers can also be labelled explicitly:

m.alpha = Param(initialize=0.3, source_key="::economics.GDP.alpha")

source_key is a MIMOSA-only argument consumed by the factory, not forwarded to Pyomo. Supplying a key that conflicts with a sourced initializer raises ValueError. Neither source_key nor doc loads or overrides values; always supply initialization separately.

Explicit input lookup

ModelInputs is available from mimosa.core.model_inputs for independent construction code. It consumes validated configuration with references resolved, its parser tree, and the existing DataStore and RegionalParamStore. For example:

from mimosa.common.config.parseconfig import check_params, parse_param_values
from mimosa.common.data import DataStore
from mimosa.common.regional_params import RegionalParamStore
from mimosa.core.model_inputs import ModelInputs

params, parser_tree = check_params({}, return_parser_tree=True)
params = parse_param_values(params)
inputs = ModelInputs(
    params=params,
    parser_tree=parser_tree,
    data_store=DataStore(params),
    regional_store=RegionalParamStore(params, parser_tree),
)

Once the model's sets are defined, parameters can use a single source reference:

m.alpha = Param(initialize=inputs.config("economics.GDP.alpha"))
m.init_capitalstock_factor = Param(
    m.regions,
    initialize=inputs.regional("economics", "init_capital_factor"),
)
m.population = Param(
    m.t, m.regions,
    initialize=inputs.time_regional("population"),
    units=quant.unit("billion people"),
)

These methods return SourcedValue objects. Scalar quantities are converted using their configured units; regional data retains existing mapping and per-region overrides; time-dependent data is interpolated using the existing store. Keys are timestep indices and region names, not calendar years. inputs.t, inputs.regions, inputs.time_grid and inputs.year(t) expose the configured indices and calendar grid. Input lookup itself does not apply component-specific consistency checks.

For Python decisions, use inputs.config_value("model structure.damage module") or retrieve a whole section, such as inputs.config_value("economics.damages.accreu"). Scalar quantity lookups return converted magnitudes, while whole sections retain their parsed contents without recursive quantity conversion. Lookups do not modify the configuration.

inputs.time_config(path) linearly interpolates a non-empty configuration mapping of ascending calendar years to numeric values onto the model time grid. Values outside the keyframe range use the nearest endpoint. It returns timestep-indexed values with the original config path as metadata. The caller chooses the source; for example, mitigation can select its SSP calibration explicitly:

ssp = inputs.config_value("SSP")
m.MAC_SSP_calibration_factor = Param(
    m.t,
    initialize=inputs.time_config(f"economics.MAC.SSP_calibration_factor.{ssp}"),
    units=quant.unit("dimensionless"),
)

Configure inputs before preparing the stores and lookup object.

The component interface is get_constraints(m: ConcreteModel, inputs: ModelInputs). Every component receives prepared input lookup directly. For example, the default welfare_loss_minimising component initializes:

m.elasmu = Param(initialize=inputs.config("economics.elasmu"))

Its params["economics"]["elasmu"]: Elasticity of marginal utility. Type: float. Default: 1.001. Min: 0.1. Max: 10. documentation marker continues to work because the factory preserves the source key in source_key. The Cobb–Douglas component now also uses explicit lookup for its capital-stock coefficient, production parameters and damage-ignore flag. For example:

m.alpha = Param(initialize=inputs.config("economics.GDP.alpha"))
m.init_capitalstock_factor = Param(
    m.regions,
    initialize=inputs.regional("economics", "init_capital_factor"),
    units=quant.unit("dimensionless"),
)

Emissions and mitigation also use explicit lookup; mitigation chooses its regional calibration column and SSP keyframe path locally. Sea-level rise reads its projection through config_value. COACCH also chooses its combined/separate, adaptation and quantile sources locally. Its declarations can select either a sourced value or a constant without a separate doc argument:

m.damage_noslr_a = Param(
    m.regions,
    initialize=1 if combined else inputs.regional("COACCH", f"NoSLR_a (q={quantile})"),
)

Only the selected branch performs a lookup. A plain constant initializes every regional entry and has no source metadata; sourced regional values carry the selected column name. This replaces the former combined-damage backend override while retaining the existing parameter declarations.

ACCREU and ACCREU_CGE also initialize configured and regional parameters explicitly. ACCREU passes inputs to its existing sector helpers; adaptation options are read and validated once by get_adaptation_options(inputs). Its sector calibration objects and equation helpers are retained. Component options use config_value, and ACCREU_CGE selects quantile columns using its existing two-decimal naming convention.

All component configuration/data parameters now use explicit initialization, including the remaining welfare variants, objectives, effort-sharing settings and cost-pool payment limits. Derived parameters retain their existing rules. The mutable no-policy damage parameter is filled later by the baseline hook. Shared base sets and input parameters are initialized before components run, so m.t, m.regions and previously declared values are immediately available. Declare dependencies before any initializer or bound that reads them. Equation lambdas should still use the model passed to them, so the same equations work in simulation and optimization.

For checks that need initialized model values, a standard Pyomo validate callback can keep validation with the parameter declaration. Emissions uses this for its pulse:

def _validate_emissions_pulse(m, pulse_amount):
    pulse_year = value(m.emissions_pulse_year)
    if pulse_amount != 0 and pulse_year not in {m.year(t) for t in m.t}:
        raise ValueError(
            f"Emissions pulse year {pulse_year} is not on the model time grid."
        )
    return True

m.emissions_pulse_year = Param(initialize=inputs.config("emissions.pulse.year"))
m.emissions_pulse_amount = Param(
    initialize=inputs.config("emissions.pulse.amount"),
    validate=_validate_emissions_pulse,
)

Pyomo calls this function when adding the parameter to the concrete model. Dependencies such as the pulse year and time grid must be declared first. The callback returns True for valid values or raises an explanatory error. It adds no solver constraint.

Component helpers can use ordinary imports for type hints and editor completion:

from mimosa.core.model_inputs import ModelInputs

def _get_emissions_constraints(m: ConcreteModel, inputs: ModelInputs):
    # ...
    pass

Parameter type checks

For component filtering or type checks, import PyomoParam from mimosa.common instead.

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