smif.decision module

The decision module handles the three planning levels

Currently, only pre-specified planning is implemented.

The choices made in the three planning levels influence the set of interventions and assets available within a model run.

The interventions available in a model run are stored in the InterventionRegister.

When pre-specified planning are declared, each of the corresponding interventions in the InterventionRegister are moved to the BuiltInterventionRegister.

Once pre-specified planning is instantiated, the action space for rule-based and optimisation approaches can be generated from the remaining Interventions in the InterventionRegister.

Summary

Classes:

DecisionManager	A DecisionManager is initialised with one or more model run strategies that refer to DecisionModules such as pre-specified planning, a rule-based models or multi-objective optimisation.
DecisionModule	Abstract class which provides the interface to decision mechanisms.
PreSpecified	Pre-specified planning
RuleBased	Rule-base decision modules

Reference

class smif.decision.DecisionManager(timesteps, strategies, interventions)

Bases: object

A DecisionManager is initialised with one or more model run strategies that refer to DecisionModules such as pre-specified planning, a rule-based models or multi-objective optimisation. These implementations influence the combination and ordering of decision iterations and model timesteps that need to be performed by the model runner.

The DecisionManager presents a simple decision loop interface to the model runner, in the form of a generator which allows the model runner to iterate over the collection of independent simulations required at each step.

(Not yet implemented.) A DecisionManager collates the output of the decision algorithms and writes the post-decision state through a DataHandle. This allows Models to access a given decision state (identified uniquely by timestep and decision iteration id).

(Not yet implemented.) A DecisionManager may also pass a DataHandle down to a DecisionModule, allowing the DecisionModule to access model results from previous timesteps and decision iterations when making decisions.

Parameters:

• timesteps (list) –
• strategies (list) –

decision_loop()

Generate bundles of simulation steps to run.

Each iteration returns a dict: {decision_iteration (int) => list of timesteps (int)}

With only pre-specified planning, there is a single step in the loop, with a single decision iteration with timesteps covering the entire model horizon.

With a rule based approach, there might be many steps in the loop, each with a single decision iteration and single timestep, moving on once some threshold is satisfied.

With a genetic algorithm, there might be a configurable number of steps in the loop, each with multiple decision iterations (one for each member of the algorithm’s population) and timesteps covering the entire model horizon.

Implicitly, if the bundle returned in an iteration contains multiple decision iterations, they can be performed in parallel. If each decision iteration contains multiple timesteps, they can also be parallelised, so long as there are no temporal dependencies.

get_decision(timestep, iteration)

Return all interventions built in the given timestep

for the given decision iteration.

Parameters:

• timestep (int) – A timestep (planning year)
• iteration (int) – A decision iteration

class smif.decision.DecisionModule(timesteps)

Bases: object

Abstract class which provides the interface to decision mechanisms.

These mechanisms including Pre-Specified Planning, a Rule-based Approach and Multi-objective Optimisation.

This class provides two main public methods, __next__ which is normally called implicitly as a call to the class as an iterator, and get_decision() which takes as arguments a smif.model.Model object, and timestep and decision_iteration integers. The first of these returns a dict of decision_iterations and timesteps over which a SosModel should be iterated. The latter provides a means to furnish the structure of contained Model objects through a list of historical and recent interventions.

Parameters:timesteps (list) – A list of planning timesteps

get_decision(timestep, iteration)

Return decisions for a given timestep and decision iteration

class smif.decision.PreSpecified(timesteps, planned_interventions)

Bases: smif.decision.DecisionModule

Pre-specified planning

Parameters:

• timesteps (list) –
• planned_interventions (list) – A list of dicts {'name': 'intervention_name', 'build_year': 2010} representing historical or planned interventions

get_decision(timestep, iteration=None)

Return a dict of intervention names built in timestep

Parameters:

• timestep (int) – A timestep (planning year)
• iteration (int) – A decision iteration

Returns:

Return type:

list of tuples

Examples

>>> dm = PreSpecified([2010, 2015], [{'name': 'intervention_a', 'build_year': 2010}])
>>> dm.get_decision(2010)
[{'name': intervention_a', 'build_year': 2010}]

buildable(build_year, timestep)

Interventions are deemed available if build_year is less than next timestep

For example, if a is built in 2011 and timesteps are [2005, 2010, 2015, 2020] then buildable returns True for timesteps 2010, 2015 and 2020 and False for 2005.

class smif.decision.RuleBased(timesteps)

Bases: smif.decision.DecisionModule

Rule-base decision modules

get_decision(timestep, iteration)

Return decisions for a given timestep and decision iteration