smif.model.sector_model module

This module acts as a bridge to the sector models from the controller

The SectorModel exposes several key methods for running wrapped sector models. To add a sector model to an instance of the framework, first implement SectorModel.

Utility Methods

A number of utility methods are included to ease the integration of a SectorModel wrapper within a System of Systems model. These include:

• get_region_names(region_set_name) - gets a list of region names
• get_interval_names(interval_set_name) - gets a list of interval names

Key Functions

This class performs several key functions which ease the integration of sector models into the system-of-systems framework.

The user must implement the various abstract functions throughout the class to provide an interface to the sector model, which can be called upon by the framework. From the model’s perspective, SectorModel provides a bridge from the sector-specific problem representation to the general representation which allows reasoning across infrastructure systems.

The key functions include:

• converting input/outputs to/from geographies/temporal resolutions
• converting control vectors from the decision layer of the framework, to asset Interventions specific to the sector model
• returning scaler/vector values to the framework to enable measurements of performance, particularly for the purposes of optimisation and rule-based approaches

Summary

Classes:

SectorModel	A representation of the sector model with inputs and outputs
SectorModelBuilder	Build the components that make up a sectormodel from the configuration

Reference

class smif.model.sector_model.SectorModel(name)

Bases: smif.model.Model

A representation of the sector model with inputs and outputs

Implement this class to enable integration of the wrapped simulation model into a system-of-system model.

Parameters:name (str) – The unique name of the sector model

Notes

Implement the various abstract functions throughout the class to provide an interface to the simulation model, which can then be called upon by the framework.

The key methods in the SectorModel class which need to be overridden are:

• SectorModel.initialise()
• SectorModel.simulate()
• SectorModel.extract_obj()

A number of utility methods are included to ease the integration of a SectorModel wrapper within a System of Systems model. These include:

• get_region_names(region_set_name) - Get a list of region names
• get_interval_names(interval_set_name) - Get a list of interval names

For example, within the implementation of the simulate method, call:

self.get_region_names('lad')

to return a list of region names defined in the region register at runtime.

as_dict()

Serialize the SectorModel object as a dictionary

Returns: Return type:dict

add_input(name, spatial_resolution, temporal_resolution, units)

Add an input to the sector model

The inputs should be specified in a list. For example:

- name: electricity_price
  spatial_resolution: GB
  temporal_resolution: annual
  units: £/kWh

Parameters:

• name (str) –
• spatial_resolution (smif.convert.area.RegionSet) –
• temporal_resolution (smif.convert.interval.IntervalSet) –
• units (str) –

add_output(name, spatial_resolution, temporal_resolution, units)

Add an output to the sector model

Parameters:

• name (str) –
• spatial_resolution (smif.convert.area.RegionSet) –
• temporal_resolution (smif.convert.interval.IntervalSet) –
• units (str) –

validate()

Validate that this SectorModel has been set up with sufficient data to run

intervention_names

The names of the interventions

Returns:A list of the names of the interventions Return type:list

initialise(initial_conditions)

Implement this method to set up the model system

This method is called as the SectorModel is constructed, and prior to establishment of dependencies and other data links.

Parameters:initial_conditions (list) – A list of past Interventions, with build dates and locations as necessary to specify the infrastructure system to be modelled.

before_model_run(data)

Implement this method to conduct pre-model run tasks

Parameters:data (smif.data_layer.DataHandle) – Access parameter values (before any model is run, no dependency input data or state is guaranteed to be available)

simulate(data)

Implement this method to run the model

Parameters:data (smif.data_layer.DataHandle) – Access state, parameter values, dependency inputs

Notes

See docs on smif.data_layer.DataHandle for details of how to access inputs, parameters and state and how to set results.

interval

should reference an id from the interval set corresponding to the output parameter, as specified in model configuration

region

should reference a region name from the region set corresponding to the output parameter, as specified in model configuration

To obtain simulation model data in this method, use the data_handle methods such as:

parameter_value = data.get_parameter('my_parameter_name')

Other useful methods are get_base_timestep_data(input_name), get_previous_timestep_data(input_name), get_parameter(parameter_name), get_data(input_name, timestep=None), get_parameters() and get_results(output_name, model_name=None, modelset_iteration=None, decision_iteration=None, timestep=None).

extract_obj(results)

Implement this method to return a scalar value objective function

This method should take the results from the output of the simulate() method, process the results, and return a scalar value which can be used as a component of the objective function by the decision layer

Parameters:results (dict) – A nested dict of the results from the simulate() method Returns:A scalar component generated from the simulation model results Return type:float

get_region_names(region_set_name)

Get the list of region names for region_set_name

Returns:A list of region names Return type:list

get_regions(region_set_name)

Get the list of regions for region_set_name

Returns:A list of GeoJSON-style dicts Return type:list

get_region_centroids(region_set_name)

Get the list of region centroids for region_set_name

Returns:A list of GeoJSON-style dicts, with Point features corresponding to region centroids Return type:list

get_interval_names(interval_set_name)

Get the list of interval names for interval_set_name

Returns:A list of interval names Return type:list

class smif.model.sector_model.SectorModelBuilder(name, sector_model=None)

Bases: object

Build the components that make up a sectormodel from the configuration

Parameters:

• name (str) – The name of the sector model
• sector_model (smif.model.SectorModel, default=None) – The sector model object

Returns:

Return type:

SectorModel

Examples

Call SectorModelBuilder.construct() to populate a SectorModel object and SectorModelBuilder.finish() to return the validated and dependency-checked system-of-systems model.

>>> builder = SectorModelBuilder(name, secctor_model)
>>> builder.construct(config_data)
>>> sos_model = builder.finish()

construct(sector_model_config, timesteps)

Constructs the sector model

Parameters:sector_model_config (dict) – The sector model configuration data

load_model(model_path, classname)

Dynamically load model module

Parameters:

• model_path (str) – The path to the python module which contains the SectorModel implementation
• classname (str) – The name of the class of the SectorModel implementation

add_initial_conditions(initial_conditions)

Adds initial conditions (state) for a model

create_initial_system(initial_conditions)

Set up model with initial system

add_parameters(parameter_config)

Add parameter configuration to sector model

Parameters:parameter_config (list) – A list of dicts with keys name, description, absolute_range, suggested_range, default_value, units, parent

add_inputs(input_dicts)

Add inputs to the sector model

add_outputs(output_dicts)

Add outputs to the sector model

add_interventions(intervention_list)

Add interventions to the sector model

Parameters:intervention_list (list) – A list of dicts of interventions

static intervention_state_from_data()

Unpack an intervention from the initial system to extract StateData

validate()

Check and/or assert that the sector model is correctly set up - should raise errors if invalid

finish()

Validate and return the sector model