smif package

Subpackages

• smif.cli package
  • Module contents
    • Folder structure
• smif.convert package
  • Submodules
  • smif.convert.area module
  • smif.convert.interval module
    • Quantities
      • Upscale: Divide
      • Downscale: Sum
    • Remapping
    • Prices
      • Upscale: Fill
      • Downscale: Average
    • Development Notes
  • smif.convert.register module
  • smif.convert.unit module
  • Module contents
• smif.data_layer package
  • Submodules
  • smif.data_layer.load module
  • smif.data_layer.sector_model_config module
  • smif.data_layer.sos_model_config module
  • smif.data_layer.validate module
  • Module contents
• smif.model package
  • Submodules
  • smif.model.dependency module
  • smif.model.model_set module
  • smif.model.scenario_model module
  • smif.model.sector_model module
    • Utility Methods
    • Key Functions
  • smif.model.sos_model module
  • Module contents
• smif.parameters package
  • Submodules
  • smif.parameters.narrative module
  • Module contents

Submodules

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.

class smif.decision.Planning(planned_interventions=None)

Bases: object

Holds the list of planned interventions, where a single planned intervention is an intervention with a build date after which it will be included in the modelled systems.

For example, a small pumping station might be built in Oxford in 2045:

{
    'name': 'small_pumping_station',
    'build_date': 2045
}

planned_interventions

list – A list of pre-specified planned interventions

names

Returns the set of assets defined in the planned interventions

timeperiods

Returns the set of build dates defined in the planned interventions

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.

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

build_date

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

get_attributes()

Ensures location is present and no build date is specified

class smif.intervention.AssetRegister

Bases: smif.intervention.Register

Register each asset type

register(asset)

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

static deterministic_dict_to_str(data)

Return a reproducible string representation of any dict

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

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

sector

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

sha1sum()

Compute the SHA1 hash of this asset’s data

Returns: Return type:str

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

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

get_intervention(name)

Returns the named asset data

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

register(intervention)

Add a new intervention to the register

Parameters:intervention (Intervention) –

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

smif.metadata module

Encapsulates the input or output parameters of a sector model, for example:

- name: petrol_price
  spatial_resolution: GB
  temporal_resolution: annual
  units: £/l
- name: diesel_price
  spatial_resolution: GB
  temporal_resolution: annual
  units: £/l
- name: LPG_price
  spatial_resolution: GB
  temporal_resolution: annual
  units: £/l

class smif.metadata.Metadata(name, spatial_resolution, temporal_resolution, units)

Bases: object

All metadata about a single dataset, typically model input or output

Parameters:

• name (str) – The dataset name
• spatial_resolution (smif.convert.region.RegionSet) – The region set that defines the spatial resolution
• temporal_resolution (smif.convert.interval.IntervalSet) – The interval set that defines the temporal resolution
• units (str) – Name of the units for the dataset values

as_dict()

get_interval_names()

The list of interval names for this temporal resolution

get_region_names()

The list of region names for this spatial resolution

normalise_unit(unit_string, param_name)

Parse unit and return standard string representation

class smif.metadata.MetadataSet(metadata_list)

Bases: object

A container for metadata about model inputs or outputs

Parameters:metadata (list) –

A list of dicts like

{
    'name': 'heat_demand'
    'spatial_resolution': smif.convert.ResolutionSet
    'temporal_resolution': smif.convert.ResolutionSet
    'units': 'kW'
}

Or, a list of smif.metadata.Metadata

Metadata(‘heat_demand’,

smif.convert.area.RegionSet, smif.convert.interval.IntervalSet, ‘kW’)

add_metadata(metadata_item)

Add an item to the set

Parameters:metadata_item (dict) – A dictionary with keys ‘name’, ‘spatial resolution’, ‘temporal resolution’ and ‘units’

add_metadata_object(metadata_object)

Add an metadata object to the set

Parameters:metadata_object (Metadata) – A smif.metadata.Metadata instance

get_spatial_res(name)

The spatial resolution for parameter name

Parameters:name (str) – The name of a model parameter

get_temporal_res(name)

The temporal resolution for parameter name

Parameters:name (str) – The name of a model parameter

get_units(name)

The units used for parameter ‘name’

Parameters:name (str) – The name of a model parameter

metadata

A list of the model parameters

Returns:parameters – A list of smif.Metadata, sorted by name Return type:list

names

A list of the parameter names

spatial_resolutions

A list of the spatial resolutions

Returns:A list of the spatial resolutions associated with the model parameters Return type:list

temporal_resolutions

A list of the temporal resolutions

Returns:A list of the temporal resolutions associated with the model parameters Return type:list

units

A list of the units

Returns:A list of the units associated with the model parameters Return type:list

smif.modelrun module

The Model Run collects scenarios, timesteps, narratives, and model collection into a package which can be built and passed to the ModelRunner to run.

The ModelRunner is responsible for running a ModelRun, including passing in the correct data to the model between timesteps and calling to the DecisionManager to obtain decisions.

ModeRun has attributes: - id - description - sosmodel - timesteps - scenarios - narratives - strategy - status

class smif.modelrun.ModelRun

Bases: object

Collects timesteps, scenarios , narratives and a SosModel together

name

str – The unique name of the model run

timestamp

datetime.datetime – An ISO8601 compatible timestamp of model run creation time

description

str – A friendly description of the model run

sos_model

smif.model.sos_model.SosModel – The contained SosModel

scenarios

dict – For each scenario set, a mapping to a valid scenario within that set

narratives

list – A list of smif.parameters.narrative.Narrative objects

strategies

dict

status

str

logger

logging.Logger

results

dict

as_dict()

Serialises smif.modelrun.ModelRun

Returns a dictionary definition of a ModelRun which is equivalent to that required by smif.modelrun.ModelRunBuilder to construct a new model run

Returns: Return type:dict

model_horizon

Returns the list of timesteps

Returns:A list of timesteps, distinct and sorted in ascending order Return type:list

run()

Builds all the objects and passes them to the ModelRunner

The idea is that this will add ModelRuns to a queue for asychronous processing

class smif.modelrun.ModelRunBuilder

Bases: object

Builds the ModelRun object from the configuration

construct(model_run_config)

Set up the whole ModelRun

Parameters:model_run_config (dict) – A valid model run configuration dictionary

finish()

Returns a configured model run ready for operation

class smif.modelrun.ModelRunner

Bases: object

Runs a ModelRun

solve_model(model_run)

Solve a ModelRun

Parameters:model_run (smif.modelrun.ModelRun) –

smif.optimisation module

Implements the interface to optimization functionality

This module defines an OptimizerTemplate which lays out the fundamental steps of any optimization algorithm. To implement your own algorithm, create a child class which inherits OptimizerTemplate and implement the methods.

class smif.optimisation.OptimizerTemplate

Bases: abc.ABC

initialize(available_interventions)

Setup the optimization problem

Parameters:available_interventions (int) – The number of dimensions

optimization_function

The function which will be minimized by the algorithm

The optimization function should return a scalar and accept a vector of binary decision variables

results

The results from a successful optimization

run()

Override to implement an optimization algorithm

The optimization algorithm should return the optimal decision vector and objective function

Module contents

smif

class smif.StateData(target, data)

Bases: object

A piece of state data

Parameters:

• target – The id or name of the object described by this state
• data – The state attribute/data to apply - could typically be a dict of attributes