Running MIMOSA

Base run

A basic run of MIMOSA requires 4 steps: loading the parameters, building the model instance, solving the model and finally saving the output. With this code, the default parameter values are used (see Parameter reference).

from mimosa import MIMOSA, load_params

params = load_params()  # (1)!

model1 = MIMOSA(params)  # (2)!
model1.solve()  # (3)!

model1.save("run1")  # (4)!

Read the default parameters
Build the model using the parameters
Once the model is built, send the model to the solver.
Note that if you use the NEOS solver, use the syntax model1.solve(use_neos=True, neos_email="your.email@email.com")
Export the output to the file output/run1.csv

Configuring the time grid

The time.dt parameter sets the initial timestep length, while time.periods optionally maps change years to the new timestep length used after that year. The default grid uses five-year timesteps through 2050 and ten-year timesteps thereafter:

params = load_params()
params["time"]["start"] = 2025
params["time"]["end"] = 2150
params["time"]["dt"] = 5
params["time"]["periods"] = {2050: 10}

Additional changes can be added to the mapping. For example, with end = 2290, {2050: 10, 2150: 20} uses five-year timesteps through 2050, ten-year timesteps through 2150, and twenty-year timesteps thereafter. Every change year and the final year must lie on the resulting grid. Within model equations, m.period_length[t] gives the number of years between timestep t - 1 and t; it is zero for the initial timestep.

Reading the output

Once the script above has finished running, it has produced two output files in the folder output: run1.csv and run1.csv.params.json. The latter is a JSON file with all the input parameters used for this particular run (for reproducibility), together with the MIMOSA version, scenario type and runtime in seconds. For optimisation output, the runtime measures the complete model.solve() call and excludes model creation and prerunning. For simulation output, it measures the model.run_simulation() call that produced the saved result. The CSV file contains all the output data. Every variable in MIMOSA is saved in this file in a format similar to IAMC data format:

output/run1.csv

Variable	Region	Unit	2020	2025	2030	2035	2040	2045	2050	2055	2060	2065	2070	2075	2080	2085	2090	2095	2100	2105	2110	2115	2120	2125	2130	2135	2140	2145	2150
regional_emissions	CAN	GtCO2/yr	0.511577	0.383683	0.255789	0.155544	0.136527	0.113384	0.0944834	0.0845257	0.077836	0.0694752	0.0588413	0.0469933	0.0359533	0.0269266	0.0199594	0.014565	0.0104499	0.0517489	0.0517486	0.0517485	0.0517484	0.0517483	0.0517482	0.0517481	0.051748	0.0517478	0.0517476
regional_emissions	USA	GtCO2/yr	5.39382	4.04537	2.69691	1.34846	0.789513	0.649695	0.531854	0.430432	0.341586	0.262853	0.195861	0.142273	0.101621	0.072636	0.0549502	0.0495887	0.0582421	0.534749	0.534749	0.534749	0.534749	0.534749	0.534749	0.534749	0.534749	0.534748	0.534748
regional_emissions	MEX	GtCO2/yr	0.572878	0.429658	0.286439	0.250682	0.235195	0.210891	0.184067	0.159748	0.137097	0.114491	0.0904155	0.0650686	0.0402638	0.0171455	-0.00403092	-0.0236268	-0.0413935	6.53385e-05	6.49712e-05	6.47857e-05	6.46547e-05	6.45457e-05	6.4444e-05	6.4339e-05	6.42181e-05	6.40555e-05	6.37559e-05
...	...

These output files can be easily imported for plotting software (like using Plotly in Python). An easier way, however, to quickly visualise and compare MIMOSA outputs, is by using the MIMOSA Dashboard. After opening the online Dashboard, simply drag and drop all output files to the drag-and-drop input to visualise one or multiple MIMOSA output files. Also include the parameter files to directly see the difference in input parameters.

Open the MIMOSA Dashboard

Derived global cost variables

Add missing global cost series to the exported results.

Some cost variables are defined only by time and region because their global counterparts are not needed while solving the model. To keep these variables available at the global level without adding equations to the optimisation problem, MIMOSA derives the corresponding series while exporting the results.

A variable is aggregated when it:

is a Pyomo variable indexed by time and region;
has fraction_of_GDP as its unit;
contains costs in its name; and
does not already have a global_<variable name> counterpart.

If an exported <variable name>_abs quantity exists, its regional values are used as the numerator:

\[ \text{global costs}_t = \frac{\sum_r \text{absolute costs}_{t,r}} {\text{global GDP gross}_t}. \]

Otherwise, absolute regional costs are reconstructed from the GDP-relative values:

\[ \text{global costs}_t = \frac{\sum_r \left(\text{costs}_{t,r} \cdot \text{GDP gross}_{t,r}\right)} {\text{global GDP gross}_t}. \]

The resulting global_* rows are added only to the exported CSV file. They are not added as Pyomo components and therefore cannot be accessed as attributes of the model. Global variables that already exist in the model are exported normally and are not replaced by this calculation.

Source code in mimosa/export/save.py

def add_derived_global_cost_rows(rows, m, all_variables):
    """
    Add missing global cost series to the exported results.

    Some cost variables are defined only by time and region because their global
    counterparts are not needed while solving the model. To keep these variables
    available at the global level without adding equations to the optimisation
    problem, MIMOSA derives the corresponding series while exporting the results.

    A variable is aggregated when it:

    - is a Pyomo variable indexed by time and region;
    - has `fraction_of_GDP` as its unit;
    - contains `costs` in its name; and
    - does not already have a `global_<variable name>` counterpart.

    If an exported `<variable name>_abs` quantity exists, its regional values are
    used as the numerator:

    $$
    \\text{global costs}_t =
    \\frac{\\sum_r \\text{absolute costs}_{t,r}}
    {\\text{global GDP gross}_t}.
    $$

    Otherwise, absolute regional costs are reconstructed from the GDP-relative
    values:

    $$
    \\text{global costs}_t =
    \\frac{\\sum_r \\left(\\text{costs}_{t,r}
    \\cdot \\text{GDP gross}_{t,r}\\right)}
    {\\text{global GDP gross}_t}.
    $$

    The resulting `global_*` rows are added only to the exported CSV file. They
    are not added as Pyomo components and therefore cannot be accessed as
    attributes of the model. Global variables that already exist in the model are
    exported normally and are not replaced by this calculation.
    """
    variables_by_name = {
        useful_var.name: useful_var for useful_var in all_variables
    }
    existing_names = set(variables_by_name)

    for useful_var in all_variables:
        source_var = getattr(useful_var.var, "_var", useful_var.var)
        global_name = f"global_{useful_var.name}"

        if (
            getattr(source_var, "ctype", None) is not Var
            or useful_var.indices != ["t", "regions"]
            or str(useful_var.unit) != "fraction_of_GDP"
            or "costs" not in useful_var.name
            or global_name in existing_names
        ):
            continue

        absolute_costs = variables_by_name.get(f"{useful_var.name}_abs")
        global_values = []
        for t in m.t:
            if absolute_costs is not None:
                numerator = sum(
                    value(absolute_costs.var[t, r]) for r in m.regions
                )
            else:
                numerator = sum(
                    value(useful_var.var[t, r]) * value(m.GDP_gross[t, r])
                    for r in m.regions
                )
            global_values.append(numerator / value(m.global_GDP_gross[t]))

        rows.append(
            [global_name, "Global", useful_var.unit, *global_values]
        )