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.

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	Instantiated Pyomo model used for optimisation.
equations	list	Equations available to simulation mode.
model_context	list	Selected model components and their model options.
simulator		Simulator associated with this model.
status		Solver status after solve(); None before a solve starts.

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 and ipopt_output_file. 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.

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.

All control variables are set to zero. The resulting damage costs are stored in the Pyomo model as nopolicy_damage_costs for subsequent policy runs.

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")