smif.intervention module

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

An Asset is the general term for an existing component of an infrastructure system.

The difference between an Intervention and an Asset, is that the latter exists (it has been “built”), whereas the former describes the potential to build an Asset.

The set of assets defines the ‘state’ of the infrastructure system.

Notes

This module implements:

• initialisation of the set of assets from model config (either a collection of yaml text files, or a database)
  • hold generic list of key/values
  • creation of new assets by decision logic (rule-based/optimisation solver)
  • maintain or derive set of possible assets
  • 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 assets for reporting
  • write out with legible or traceable keys and units for verification and understanding

Terminology

name:

A category of infrastructure intervention (e.g. power station, policy) which holds default attribute/value pairs. These names can be inherited by asset/intervention definitions to reduce the degree of duplicate data entry.

asset:

An instance of an intervention, which represents a single investment decisions which will take place, or has taken place. Historical interventions are defined as initial conditions, while future interventions are listed as pre-specified planning. Both historical and future interventions can make use of names to ease data entry. Assets must have location, build_date and name attributes defined.

intervention:

A potential asset or investment. Interventions are defined in the same way as for assets, cannot have a build_date defined.

Summary

Classes:

Asset	An instance of an intervention with a build date.
AssetRegister	Register each asset type
Intervention	An potential investment to send to the logic-layer
InterventionContainer	An container for asset types, interventions and assets.
InterventionRegister	The collection of Intervention objects
Register	Holds interventions, pre-spec’d planning instructions & existing assets

Reference

class smif.intervention.InterventionContainer(name='', data=None, sector='')

Bases: object

An container for asset types, interventions and assets.

An asset’s data is set up to be a flexible, plain data structure.

Parameters:

• name (str, default="") – The type of asset, which should be unique across all sectors
• data (dict, default=None) – The dictionary of asset attributes
• sector (str, default="") – The sector associated with the asset

get_attributes()

Override to return two lists, one containing required attributes, the other containing omitted attributes

Returns:Tuple of lists, one contained required attributes, the other which must be omitted Return type:tuple

sha1sum()

Compute the SHA1 hash of this asset’s data

Returns: Return type:str

static deterministic_dict_to_str()

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 asset is used in.

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

Bases: smif.intervention.InterventionContainer

An potential investment to send to the logic-layer

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 asset, which should be unique across all sectors
• data (dict, default=None) – The dictionary of asset attributes
• sector (str, default="") – The sector associated with the asset

get_attributes()

Ensures location is present and no build date is specified

location

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

class smif.intervention.Asset(name='', data=None, sector='')

Bases: smif.intervention.Intervention

An instance of an intervention with a build date.

Used to represent pre-specified planning and existing infrastructure assets and interventions

Parameters:

• name (str, default="") – The type of asset, which should be unique across all sectors
• data (dict, default=None) – The dictionary of asset attributes
• sector (str, default="") – The sector associated with the asset

get_attributes()

Ensures location is present and no build date is specified

build_date

The build date of this asset instance (if specified - asset types will not have build dates)

class smif.intervention.Register

Bases: object

Holds interventions, pre-spec’d planning instructions & existing assets

• register each asset type/intervention name
• translate a set of assets representing an initial system into numeric representation

register(asset)

Adds a new asset to the collection

class smif.intervention.AssetRegister

Bases: smif.intervention.Register

Register each asset type

register(asset)

Adds a new asset to the collection

class smif.intervention.InterventionRegister

Bases: smif.intervention.Register

The collection of Intervention objects

An InterventionRegister contains an immutable collection of sector specific assets 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 asset build possibilities (asset 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 Asset objects with human-readable key-value pairs
• translates an immutable collection of Asset 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)

Returns the named asset data

register(intervention)

Add a new intervention to the register

Parameters:intervention (Intervention) –

attribute_index(key)

Get the index of an attribute name

attribute_value_index(attr_idx, value)

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

numeric_to_intervention(numeric_asset)

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

Parameters:numeric_asset (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 = AssetRegister()
>>> 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 asset:

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