Skip to content

MIMOSA 1.3.0

Status: released 17 July 2026

MIMOSA 1.3.0 focuses on reliable simulation, maintainable model construction and documentation for people running and extending the model. The default configuration, optimisation equations and model variable names have not deliberately changed in this release.

Highlights

  • Simulation dependencies are determined from Pyomo expressions rather than parsed text.
  • Simulation runs prepare themselves when needed, including when a model was created with prerun=False.
  • Model components are registered in one readable catalogue in mimosa/abstract_model.py.
  • Shared time, region and baseline inputs are defined separately in mimosa/base_model.py.
  • Duplicate component names, duplicate simulation equations and accidental Pyomo component replacement are detected by validation or tests.
  • Running, extension and scientific documentation has been substantially updated.
  • Important documentation examples are now executed in continuous integration.

Simulation changes

Simulation dependency detection now inspects the Pyomo expression tree for every relevant timestep and region. This replaces the previous approach of parsing one constraint expression as text. The new implementation:

  • detects dependencies that occur only in an initial-period or region-specific branch;
  • supports year labels and other non-consecutive timestep values;
  • distinguishes current-timestep dependencies from references to earlier timesteps;
  • rejects references to future timesteps;
  • includes equations without variable dependencies in the execution order; and
  • rejects multiple equations defining the same left-hand-side variable.

Dependencies on an earlier timestep are recorded for the dependency graph but do not affect the within-timestep execution order. Timesteps are already evaluated sequentially.

MIMOSA.run_simulation() and MIMOSA.prerun_simulation() now prepare the simulator automatically if needed. Code such as the following therefore works without a separate prepare_simulation() call:

from mimosa import MIMOSA, load_params

model = MIMOSA(load_params(), prerun=False)
simulation = model.run_simulation(relative_abatement=0.2)

Calling Simulator.run(), Simulator.find_prerun_bestguess() or dependency plotting directly still requires Simulator.prepare_simulation() first. These methods now raise SimulationNotPreparedError when that step is missing.

See Simulation and optimisation for the main simulation use cases and the distinction between run_simulation() and run_nopolicy_baseline().

Extending the model

The ordered component catalogue is now located in mimosa/abstract_model.py. A component that is always included is registered with:

fixed_component("new_component", new_component.get_constraints)

A component for which users select a submodule is registered with:

selectable_component("biodiversity", biodiversity.BIODIVERSITY_MODULES)

The catalogue is also used to construct ModelContext, removing the previous duplicate registration inside Preprocessor. Configuration names follow two conventions:

  • selectable components use <name> module and <name> module options;
  • components that are always included use <name> options.

Shared model declarations that used to appear at the top of abstract_model.py are now in mimosa/base_model.py. Developers changing the time or region sets, population, baseline GDP or baseline emissions should make those changes there.

See Creating model components, Selectable modules and Model options for the complete extension process.

Preprocessor results

Preprocessor.build_model() now returns a ModelBuildResult with named attributes:

result.concrete_model
result.params
result.equations
result.context

Existing three-value tuple unpacking remains supported:

model, params, equations = preprocessor.build_model()

The result is no longer an actual tuple, so code using numeric indexing such as result[0] must use the named attributes instead. The constructed ModelContext and InstantiatedModel are also retained on the Preprocessor instance.

Validation and testing

The test suite now covers:

  • equation evaluation in both Pyomo and simulation mode;
  • parity between default-model Pyomo equations and simulation results;
  • dependency ordering, branches, previous timesteps, cycles and isolated equations;
  • model-construction stage order;
  • component registration and model options;
  • duplicate equations and component names; and
  • implicit replacement of Pyomo variables, parameters or other components in the default model.

Continuous integration now runs only the maintained tests directory. A separate documentation workflow builds MkDocs in strict mode and executes selected optimisation, baseline, simulation and effort-sharing examples.

Documentation

The documentation now includes expanded guidance on:

  • installing a development checkout and running its tests;
  • simulation and optimisation use cases;
  • creating plain and selectable model components;
  • variables, equations, constraints and soft equalities;
  • model options;
  • parameters, regional mappings and input data;
  • units and unit conversion;
  • emission trading and the distinction between physical and attributed reductions and costs;
  • effort sharing, including its interaction with optimisation and simulation; and
  • welfare, discounting, inequality aversion and optimisation objectives.

The PRISMA workshop examples and other run scripts in the documentation have been updated to current configuration paths and model result names.

Removed social-cost-of-carbon implementation

The old SCC package has been removed

The mimosa.socialcostofcarbon package, including the SCC class, has been removed. There is no direct replacement in MIMOSA 1.3.0. A future implementation is intended to use the normal simulation system, which avoids maintaining a separate calculation path.

Code importing the old implementation must remove or replace imports such as:

from mimosa.socialcostofcarbon.scc import SCC

Updating an existing development branch

Branches that modify mimosa/abstract_model.py, mimosa/core/initializer.py or the simulation dependency code are likely to require manual conflict resolution. When updating such a branch:

  1. preserve the component catalogue in abstract_model.py;
  2. register new components in that catalogue rather than restoring direct construction calls or a second component list in Preprocessor;
  3. move changes to shared time, region or baseline inputs into base_model.py;
  4. preserve expression-tree dependency detection rather than restoring string parsing; and
  5. run python -m pytest tests after resolving the conflicts.

Branches that only change an individual scientific component should generally require few or no special migration steps.