smif.intervention module

This module handles the collection of interventions in a sector. The set of interventions describes the targets of possible physical (or non-physical) decisions which can be made in the sector.

Notes

This module implements:

  • initialisation of the set of interventions from model config

(either a collection of yaml text files, or a database)

  • hold generic list of key/values
  • creation of new interventions by decision logic (rule-based/optimisation solver)
  • maintain or derive set of possible interventions
  • makes the distinction between known-ahead values and build-time values. Location and date are specified at build time, while cost and capacity are a function of time and location.
  • serialisation for passing to models
    • ease of access to full generic data structure
  • output list of interventions for reporting
    • write out with legible or traceable keys and units for verification and understanding

Terminology

name:
An infrastructure intervention (e.g. power station, policy) which holds default attribute/value pairs. These names can be inherited by intervention/intervention definitions to reduce the degree of duplicate data entry.
intervention:
A potential intervention or investment. Interventions are defined in the same way as for interventions, cannot have a build_date defined.

Summary

Classes:

Intervention An potential investment to send to the decision manager
InterventionRegister The collection of Intervention objects

Reference

class smif.intervention.Intervention(name='', data=None, sector='')[source]

Bases: object

An potential investment to send to the decision manager

An Intervention, is an investment which has a name (or name), other attributes (such as capital cost and economic lifetime), and location, but no build date.

The set of interventions are defined within each sector, and these are collected into an InterventionRegister when a smif.controller.SosModel is instantiated by the controller at runtime.

Parameters:
  • name (str, default="") – The type of intervention, which should be unique across all sectors
  • data (dict, default=None) – The dictionary of intervention attributes
  • sector (str, default="") – The sector associated with the intervention
  • intervention's data is set up to be a flexible, plain data structure. (An) –
  • name – The type of intervention, which should be unique across all sectors
  • data – The dictionary of intervention attributes
  • sector – The sector associated with the intervention
sha1sum()[source]

Compute the SHA1 hash of this intervention’s data

Returns:
Return type:str
static deterministic_dict_to_str(data)[source]

Return a reproducible string representation of any dict

Parameters:data (dict) – An intervention attributes dictionary
Returns:A reproducible string representation
Return type:str
sector

The name of the sector model this intervention is used in.

location

The location of this intervention instance (if specified - intervention types may not have explicit locations)

class smif.intervention.InterventionRegister[source]

Bases: object

The collection of Intervention objects

An InterventionRegister contains an immutable collection of sector specific interventions and decision points which can be decided on by the Logic Layer

  • Reads in a collection of interventions defined in each sector model
  • Builds an ordered and immutable collection of interventions
  • Provides interfaces to
    • optimisation/rule-based planning logic
    • SectorModel class model wrappers

Key functions:

  • outputs a complete list of intervention build possibilities (intervention type at location) which are (potentially) constrained by the pre-specified planning instructions and existing infrastructure.
  • translate a binary vector of build instructions (e.g. from optimisation routine) into intervention objects with human-readable key-value pairs
  • translates an immutable collection of intervention objects into a binary vector to pass to the logic-layer.

Notes

Internal data structures

Intervention_types
is a 2D array of integers: each entry is an array representing an Intervention type, each integer indexes attribute_possible_values
attribute_keys
is a 1D array of strings
attribute_possible_values
is a 2D array of simple values, possibly (boolean, integer, float, string, tuple). Each entry is a list of possible values for the attribute at that index.

Invariants

  • there must be one name and one list of possible values per attribute
  • each Intervention type must list one value for each attribute, and that value must be a valid index into the possible_values array
  • each possible_values array should be all of a single type
get_intervention(name)[source]

Returns the named intervention data

register(intervention)[source]

Add a new intervention to the register

Parameters:intervention (Intervention) –
attribute_index(key)[source]

Get the index of an attribute name

attribute_value_index(attr_idx, value)[source]

Get the index of a possible value for a given attribute index

numeric_to_intervention(numeric_intervention)[source]

Convert the numeric representation of an intervention back to intervention (with legible key/value data)

Parameters:numeric_intervention (list) – A list of integers of length self._attribute_keys
Returns:An Intervention object
Return type:Intervention

Examples

Given a (very minimal) possible state of a register:

>>> register = interventionRegister()
>>> register._names = [[1,1,1]]
>>> register._attribute_keys = ["name", "capacity", "sector"]
>>> register._attribute_possible_values = [
...     [None, "water_treatment_plant"],
...     [None, {"value": 5, "units": "ML/day"}],
...     [None, "water_supply"]
... ]

Calling this function would piece together the intervention:

>>> intervention = register.numeric_to_intervention([1,1,1])
>>> print(intervention)
intervention("water_treatment_plant", {"name": "water_treatment_plant",
"capacity": {"units": "ML/day", "value": 5}, "sector": "water_supply"})