Decision Layer

A general decision layer that enables development of alternative decision algorithms

Develop a generic decision layer which enables users to:

• define decision algorithms
• reason about infrastructure planning across simulation models
• manage interventions

Components

The "Decision Layer" consists of a number of components. These include:

• SosModel - contains a number of SectorModels and holds an collection of SectorModels' interventions
• InterventionRegister - an immutable list of interventions
• Intervention - a single intervention associated with a SectorModel
• SectorModel - a model which simulations the operation of a system and whose structure is comprised of Interventions
• Strategy - a collection of rules or instructions on how to pick interventions in each planning timestep and decision iteration
• DecisionManager - holds a bundle of strategies, mediates between strategies and provides a clean interface to the ModelRunner
• ModelRunner - has responsibility for solving a SosModel. This may involve running multiple decision iterations for each planning year, or running multiple planning years in each decision iteration, depending upon the strategy, or collection of strategies, the structure of the SosModel (i.e. the dependencies between SectorModels within the SosModel).

Design ideas

• The state of a model (a list of Intervention that exist in a planning timestep) are stored through the DataHandle
• A SectorModel does not need to be aware of the mechanism of planning decisions, and is instantiated with a list of interventions that exist for the current timestep (the model's state), or reads the state from the DataHandle
• The ModelRunner get_decisions() from the DecisionManager, collects the Intervention data from the InterventionRegister and writes the list of Interventions (the state) to the DataHandle
• Interventions are aware of their SectorModel association

Stories

Rename initial_conditions to historical_interventions

Labels:

• smif
• smif_decision_layer

Config name-change, within model

Add planned_interventions section to modelrun config

Labels:

• smif
• smif_decision_layer

planned_interventions:
  model_name:
    - a.csv
    - b.csv

DecisionModule class implementation/docs

Labels:

• smif
• smif_decision_layer

Firm up design of DecisionModule (possibly in isolation, initially - see related stories).

DecisionModule init:

• can access its own parameters
• any direct knowledge of SosModel?

DecisionModule decide method:

• could receive list of timestep/decision_i that just completed
• can access interventions available per-timestep
• can access results per-timestep/decision_i
• output a request for list of timestep/decision_i to simulate
  • including information about predecessor for each
• output interventions to apply (list of names) per-timestep/decision_i requested

Plan refactor of smif.decision

Labels:

• smif

• smif_decision_layer

  • planned interventions applied

• single decision module loaded and configured

• decision module object interface documented/ready for config

Document approach to results for objective functions

Labels:

• smif
• smif_decision_layer

Suggest that it would be a practical pattern for a SosModel to include a ResultsAggregator (or several similar) to do aggregation or calculation over Model results in anticipation of the needs of a DecisionModel - then DecisionModel can read results straightforwardly and not need to be concerned too much with dimensions/conversions etc.

Document implementing 'dynamic' networks with state

Labels:

• smif
• smif_decision_layer

Any state (inter-timestep dependency) that carries information about interventions (e.g. reservoir level, degradation of roads...) must be indexed by a fixed dimension of intervention ids, because Specs and dimensions are defined up front.

Solved by having fixed intervention list up front, which can be activated/deactivated as necessary.

Document this somewhere.

Helpers for maintaining bundle/timeline state

Labels:

• smif

• smif_decision_layer

  To maintain a data structure which can answer:

• which timestep/decision_i immediately preceded this timestep/decision_i

• (hence) what timeline of timestep/decision_i led to this point

Suggest a tree (or forest) rooted at first-timestep, first-decision_i(s), with timestep/decision_i identifiers on nodes, so queries can be answered by finding a node then finding immediate parent or walking ancestor-by-ancestor to the root.

Maintain with an add operation: add( new_node_id, parent_id) where new_node_id is a new timestep/decision_i and parent_id is the timestep/decision_i that preceded it (or None).

Add decision module config

Labels:

• smif
• smif_decision_layer

name: ""
description: ""
parameters: []
model_classname: ""
path: "dm.py"

Add decision modules section to GUI

Add decision module config entry to model run config

Additional interventions available on a model run

Use case is some particular interventions that a modeller wants to test out without adding them more permanently to a model's set of interventions

Encapsulate bundle-linking decision/timestep data structure

Labels:

• smif
• smif_decision_layer

Aiming to make it easier to implement a decision module.

Encapsulate modelrun/bundle linking state.

Actions:

• get new decision iteration (not satisfied, same timestep)
• get next timestep (satisfied, moving on)

Queries:

• given (current timestep, current iteration) get (previous timestep, relevant iteration)
• given (current timestep, timestep of interest, current iteration) get relevant iteration
• given (timestep, iteration), get all (timestep, iteration) preceding pairs - either one-to-one 'best-only' decision iteration per timestep or many-to-one all decision iterations considered per timestep

Planning rules should be general and defined in data

Labels:

• smif
• smif_decision_layer

Planning rules, which trigger investment dependent on some logic, should be defined by data, rather than in code. For example, "an investment in new electricity generation capacity should occur when capacity margin decreases below threshold x" should be expressed as a link between a decision variable input (an asset or subset of asset), and an output metric (capacity margin in this case), and the rule type. This rule should then be defined in code and the rule 'compiled' at runtime.

Interventions may belong to a category

Labels:

• smif
• smif_decision_layer

An intervention has a category with associates a meta-data template with that intervention. An attribute set is linked to the category. Attributes include location, name, model id and cost. Some of these are shared across intervention categories and are machine readable e.g. for GUI geolocation and visualisation; others are required for the target simulation model.

For example, energy supply has separate intervention categories defined for:

• electricity network (overhead lines)
• gas network (pipes and pumps)
• gas storage
• gas terminals
• power stations

Location can be a

• point
• line
• polygon and needs to be expressed in terms of the region definitions used by the model.

All interventions within a category can be stored in a csv file, where column headers are elements in the intervention category

A PlanningView creates a mapping between the current timestep and the planning window

Labels:

• smif
• smif_decision_layer

Use Case: Planning Window

Description

Interventions are chosen in each timestep in a Planning View. Interventions are only persisted for the first timestep in the Planning View.

The set of Planning Views is a deterministic function of the model horizon and the planning window. If the planning window does not cover the model horizon, on each iteration, the algorithm moves to the PlanningView which begins with the next timestep and continues until the whole model horizon has been covered. The system state is copied from the end of the previous timestep.

An Iteration is a single pass through the timesteps in a planning view.

PreCondition:

Modeller sets PlanningWindow parameter to 1

Main Success Scenario

1. ModelRunner requests PlanningView for SosModel configuration
2. PlanningView returns decision epochs (set of timesteps for which to make decisions) for first year
3. ModelRunner creates new Iteration with current year and planning view.
4. ModelRunner sends iteration to decision manager with a request for decisions.
5. Decision Manager adds decisions to Iteration.
6. ModelRunner performs Iteration by sending decisions to SosModel with simulate command.
7. SosModel sends ModelRunner results.
8. ModelRunner attaches results to Iteration

Extensions

1 a. Planning Window is 1 < x < ModelHorizon

1. In each timestep, decisions are chosen for the current timestep, and then each timestep in the PlanningView is performed to assess performance. Algorithm then moves to the next timestep. 1 b. Planning Window is set to 0 (don't use window)
2. ModelRunner runs over all timesteps in the model horizon

Log warnings when simplifying assumptions are made about state when aggregating the planning horizon

Labels:

• logging

• smif_decision_layer

• simplifying assumptions regarding non-asset state variables (reservoir levels remain constant or are interpolated)

• annual running of the water-supply model

• using average dependency assumptions from the other models