Python reference

This page summarises the functions and methods intended for ordinary MIMOSA runs. For worked examples, see Changing parameters and Simulation and optimisation.

Loading parameters

mimosa.load_params(user_yaml_filename=None)

Load, validate and parse a MIMOSA configuration.

Values not supplied by the user are taken from config_default.yaml.

Parameters:

Name	Type	Description	Default
user_yaml_filename	Optional[str]	Path to a YAML file containing configuration values that override the defaults. If omitted, only the defaults are loaded.	None

Returns:

Name	Type	Description
dict	dict	Complete parsed configuration for constructing mimosa.MIMOSA.

Raises:

Type	Description
RuntimeWarning	If the user file contains an obsolete, unknown or misspelled configuration entry.

Loading adaptation-readiness data

from mimosa import load_adaptation_readiness

readiness = load_adaptation_readiness()
factor = readiness.loc[("SSP1", "CAN"), "2030"]

mimosa.load_adaptation_readiness()

Return the packaged adaptation-readiness table.

The table is indexed by SSP and Region. Calendar-year columns retain their string labels, as with pandas.read_csv. Each call returns a new table, independent of the current working directory. Data is read only when this function is called.

Example

from mimosa import load_adaptation_readiness

readiness = load_adaptation_readiness()
factor = readiness.loc[("SSP1", "CAN"), "2030"]

Building and running a model

mimosa.MIMOSA

Build and run a MIMOSA model.

Creating this object checks and parses the configuration, builds the selected model components, loads their data and creates a Pyomo concrete model.

Parameters:

Name	Type	Description	Default
params	dict	Configuration dictionary, normally created with mimosa.load_params(). Change its values before creating the model.	required
prerun	bool	If True, prepare the simulator, calculate an initial guess for optimisation and store a no-policy damage baseline. Disable this when only the constructed model is needed or when model construction time is more important than the initial guess.	True

Attributes:

Name	Type	Description
concrete_model	ConcreteModel	Initialized Pyomo model used for optimisation.
equations	list	Equations available to simulation mode.
inputs	ModelInputs	Prepared configuration and data lookup used to build the model.
simulator		Simulator associated with this model.
status		Solver status after solve(); None before a solve starts.
solve_runtime		Wall-clock duration of the most recently completed solve() call in seconds; None before a solve completes.
workflow_control_values		Controls transferred by the most recent sequential workflow; None for an ordinary solve.

params property

dict: Parsed configuration used to construct the model.

Changing this dictionary does not rebuild or update the existing model.

solve(verbose=True, use_neos=False, **kwargs)

Optimise the Pyomo model locally with IPOPT or remotely through NEOS.

Parameters:

Name	Type	Description	Default
verbose	bool	Print IPOPT output during a local solve.	True
use_neos	bool	Submit the model to NEOS instead of using local IPOPT.	False
**kwargs	Any	Solver-specific options. Local IPOPT accepts halt_on_ampl_error, ipopt_maxiter, ipopt_output_file and ipopt_executable (an optional path to a specific IPOPT build). NEOS requires neos_email and optionally accepts solver_name.	{}

Raises:

Type	Description
SolverException	If the solver does not finish with status OK.

run_simulation(**control_variables_kwargs)

Evaluate the model equations for supplied control variables.

Every control variable that is omitted or set to None is set to zero. Available control names can be inspected with model.simulator.control_variables.

Parameters:

Name	Type	Description	Default
**control_variables_kwargs	Any	Values for control variables, keyed by variable name. Each value can be a number applied to all indices, a NumPy array matching the variable's dimensions, a dictionary keyed like the Pyomo variable, or None for zero.	{}

Returns:

Name	Type	Description
SimulationObjectModel	SimulationObjectModel	Calculated simulation results. Its runtime attribute contains the wall-clock duration of this call in seconds.

Raises:

Type	Description
ValueError	If a supplied name is not a control variable.
AssertionError	If an array has the wrong dimensions.

run_nopolicy_baseline()

Run and store the no-policy reference used for avoided damages.

Mitigation and adaptation are both disabled. The resulting damage costs are stored in the Pyomo model as nopolicy_damage_costs for subsequent policy runs. An ACCREU model with analytical adaptation uses a temporary no-adaptation model for this reference.

Returns:

Name	Type	Description
SimulationObjectModel	SimulationObjectModel	No-policy simulation results.

save(filename=None, **kwargs)

Save optimisation results and their configuration.

This creates <filename>.csv and <filename>.csv.params.json.

Parameters:

Name	Type	Description	Default
filename	Optional[str]	Base filename without an extension.	None
**kwargs	Any	Output options. folder selects the output directory and hash_suffix=True adds a configuration hash to the filename.	{}

Example

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

save_simulation(simulation_obj, filename, **kwargs)

Save simulation results and their configuration.

This creates <filename>.csv and <filename>.csv.params.json.

Parameters:

Name	Type	Description	Default
simulation_obj	SimulationObjectModel	Results returned by run_simulation() or run_nopolicy_baseline().	required
filename	str	Base filename without an extension.	required
**kwargs	Any	Output options. folder selects the output directory and hash_suffix=True adds a configuration hash to the filename.	{}

Example

model = MIMOSA(params)
simulation = model.run_nopolicy_baseline()
model.save_simulation(simulation, "nopolicy_baseline")