Skip to content

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)!
  1. Read the default parameters
  2. Build the model using the parameters
  3. 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")
  4. Export the output to the file output/run1.csv

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 simply a JSON file with all the input parameter used for this particular run (for reproducibility). The former is a CSV file that contains all the output data. Every variable in MIMOSA is saved in this value 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

Changing parameters

The default parameters from load_params() are given as a nested dictionary. Every item of this dictionary can be changed. For a complete overview of all parameters that can be changed, see Parameters.

Example 1: carbon budget

In this example, the carbon budget is changed to 500 GtCO2. 

from mimosa import MIMOSA, load_params

params = load_params()

params["emissions"]["carbonbudget"] = "500 GtCO2"  # (1)!

model1 = MIMOSA(params)
model1.solve()

model1.save("run_example_carbonbudget")
  1. Change the parameter of emissions > carbonbudget to the string "500 GtCO2"

Example 2: high damages, high TCRE, low discounting

Multiple parameters can also be changed at the same time. In this example, the high end of the damages and of the climate sensitivity (TCRE) are used, combined with the low end of the discount rate (PRTP).

from mimosa import MIMOSA, load_params

params = load_params()

params["economics"]["damages"]["quantile"] = 0.95
params["temperature"]["TCRE"] = "0.82 delta_degC/(TtCO2)"
params["economics"]["PRTP"] = 0.001

model2 = MIMOSA(params)
model2.solve()

model2.save("run_example2")

Doing multiple runs

Often, MIMOSA needs to be run with multiple values of the same parameter (multiple carbon budgets, multiple discount rates, etc.). While it is possible to simply run the file multiple times, it is much easier to run MIMOSA multiple times directly in the Python script through regular Python loops:

from mimosa import MIMOSA, load_params

for budget in ["500 GtCO2", "700 GtCO2", "1000 GtCO2"]:

    params = load_params()

    params["emissions"]["carbonbudget"] = budget

    model3 = MIMOSA(params)
    model3.solve()

    model3.save(f"run_example3_{budget}")  # (1)!
  1. Don't forget to save each file to a different name, otherwise they will be overwritten at each iteration of the loop.

Doing a baseline run

It can be useful to do a MIMOSA run with zero mitigation: a baseline run. We distinguish two types of baseline runs: either ignoring damages (the true baseline run, in absence of climate policy and climate impacts), or with damages (a no-policy scenario, mainly to investigate the damages if no climate policy were implemented).

from mimosa import MIMOSA, load_params

params = load_params()

params["emissions"]["carbonbudget"] = False
params["economics"]["damages"]["ignore damages"] = True

params["model"]["welfare module"] = "cost_minimising"

# Disable some emission reduction constraints
params["emissions"]["non increasing emissions after 2100"] = False
params["emissions"]["not positive after budget year"] = False
params["emissions"]["inertia"]["regional"] = False
params["emissions"]["inertia"]["global"] = False

params["time"]["end"] = 2150

model = MIMOSA(params)
model.solve()
model.save("baseline_ignore_damages")

from mimosa import MIMOSA, load_params

params = load_params()

params["emissions"]["carbonbudget"] = False
params["economics"]["damages"]["ignore damages"] = False  # (1)!
params["model"]["welfare module"] = "cost_minimising"

# Force the mitigation effort to be zero
params["simulation"]["simulationmode"] = True
params["simulation"]["constraint_variables"] = {
    "relative_abatement": {
        year: {region: 0.0 for region in params["regions"]}
        for year in range(2025, 2151, 5)
    },
}
params["economics"]["MAC"]["gamma"] = "0.00001 USD2005/tCO2"  # (2)!

# Disable some emission reduction constraints
params["emissions"]["non increasing emissions after 2100"] = False
params["emissions"]["not positive after budget year"] = False
params["emissions"]["inertia"]["regional"] = False
params["emissions"]["inertia"]["global"] = False

params["time"]["end"] = 2150

model = MIMOSA(params)
model.solve()
model.save("baseline_no_policy")
  1. This is default, so this line could be removed
  2. Needed for numerical stability

Doing an effort-sharing run

MIMOSA has some built-in effort sharing regimes. In this example, they are used in combination with a carbon budget (but it could be used in CBA mode). The welfare module is set to cost minimising, as this is typically used with effort sharing regimes. Effort sharing would be impossible without emission trading. Finally, this would often be infeasible for some regions, if we didn't allow for some extra financial transfers beyond just emission trading, which is why we set the relative mitigation cost minimum level to a small negative number.

from mimosa import MIMOSA, load_params


# Loop over the three available effort sharing regimes
for regime in [
    "equal_mitigation_costs",
    "equal_total_costs",
    "per_cap_convergence",
]:
    params = load_params()
    params["model"]["emissiontrade module"] = "emissiontrade"
    params["model"]["welfare module"] = "cost_minimising"
    params["emissions"]["carbonbudget"] = "700 GtCO2"
    params["effort sharing"]["regime"] = regime
    params["economics"]["MAC"]["rel_mitigation_costs_min_level"] = -0.3
    params["time"]["end"] = 2100

    model1 = MIMOSA(params)
    model1.solve()
    model1.save(f"run_{regime}")

Advanced: logging

The solve status (optimal, impossible, etc), model solve time and the final maximised value can be logged to an external log file (along with the warnings or errors from the code). This can be very useful when doing many runs overnight. In this code example, the log is written to the file mainlog.log:

import logging
import logging.handlers

from mimosa import MIMOSA, load_params

handler = logging.handlers.WatchedFileHandler("mainlog.log")
handler.setFormatter(
    logging.Formatter("[%(levelname)s, %(asctime)s] %(name)s - %(message)s")
)
root = logging.getLogger()
root.setLevel("INFO")
root.addHandler(handler)

params = load_params()

# Make changes to the params if needed
params["emissions"]["carbonbudget"] = False

model1 = MIMOSA(params)
model1.solve(verbose=False)  # (1)!
model1.save("run1_logged")
  1. By setting verbose=False, the IPOPT output is not printed. If you're doing many runs, this is probably useful. The termination status of IPOPT is logged to the log file anyway.