smif.model package¶

Implements a composite scenario/sector model/system-of-systems model

Begin by declaring the atomic units (scenarios and sector models) which make up a the composite system-of-systems model and then add these to the composite. Declare dependencies by using the add_dependency() method, passing in a reference to the source model object, and a pointer to the model output and sink parameter name for the destination model.

Run the model by calling the simulate() method, passing in a dictionary containing data for any free hanging model inputs, not linked through a dependency. A fully defined SosModel should have no hanging model inputs, and can therefore be called using simulate() with no arguments.

Responsibility for passing required data to the contained models lies with the calling class. This means data is only ever passed one layer down. This simplifies the interface, and allows as little or as much hiding of data, dependencies and model inputs as required.

Example

A very simple example with just one scenario:

>>> elec_scenario = ScenarioModel('scenario')
>>> elec_scenario.add_output('demand', 'national', 'annual', 'GWh')
>>> sos_model = SosModel('simple')
>>> sos_model.add_model(elec_scenario)
>>> sos_model.simulate(2010)
{'scenario': {'demand': array([123])}}

A more comprehensive example with one scenario and one scenario model:

>>> elec_scenario = ScenarioModel('scenario')
>>> elec_scenario.add_output('demand', 'national', 'annual', 'GWh')
>>> class EnergyModel(SectorModel):
...   def extract_obj(self):
...     pass
...   def simulate(self, timestep, data):
...     return {self.name: {'cost': data['input'] * 2}}
...
>>> energy_model = EnergyModel('model')
>>> energy_model.add_input('input', 'national', 'annual', 'GWh')
>>> energy_model.add_dependency(elec_scenario, 'demand', 'input', lambda x: x)
>>> sos_model = SosModel('sos')
>>> sos_model.add_model(elec_scenario)
>>> sos_model.add_model(energy_model)
>>> sos_model.simulate(2010)
{'model': {'cost': array([[246]])}, 'scenario': {'demand': array([[123]])}}

class smif.model.Model(name)[source]¶

Bases: object

Abstract class represents the interface used to implement the model classes SectorModel and ScenarioModel.

Parameters:: name (str)

add_input(spec)[source]¶

Add an input

Parameters:: spec (smif.metadata.Spec)

add_output(spec)[source]¶

Add an output

Parameters:: spec (smif.metadata.Spec)

add_parameter(spec)[source]¶

Add a parameter

Parameters:: spec (smif.metadata.Spec)

as_dict()[source]¶

Serialize the SectorModel object as a dictionary

Return type:: dict

classmethod from_dict(config)[source]¶: Create object from dictionary serialisation

property inputs¶

All model inputs defined at this layer

Returns:: dict of {input_name
Return type:: smif.metadata.Spec}

property outputs¶

All model outputs defined at this layer

Returns:: dict of {output_name
Return type:: smif.metadata.Spec}

property parameters¶

Model parameters

Returns:: dict of {parameter_name
Return type:: smif.data_layer.data_array.DataArray}

simulate(data)[source]¶

Override to implement the generation of model results

Generate results for timestep using data

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

class smif.model.ModelOperation(*values)[source]¶

Bases: Enum

Enumerate that describes the possible operations on Models

BEFORE_MODEL_RUN = 'before_model_run'¶

SIMULATE = 'simulate'¶

class smif.model.ScenarioModel(name)[source]¶

Bases: Model

Represents exogenous scenario data

Parameters:: name (str) – The name of this scenario (scenario set/abstract scenario/scenario group) - like sector model name

name¶

Name of this scenario

Type:: str

scenario¶

Instance of scenario (concrete instance)

Type:: str

as_dict()[source]¶: Serialise ScenarioModel to dict

classmethod from_dict(data)[source]¶: Create ScenarioModel from dict serialisation

simulate(data)[source]¶: No-op, as the data is assumed to be already available in the store

class smif.model.SectorModel(name)[source]¶

Bases: 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 must be overridden are:

SectorModel.simulate()
SectorModel.extract_obj()

An implementation may also override:

SectorModel.before_model_run()

before_model_run(data)[source]¶

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) Access decision/system state (i.e. initial_conditions)

simulate(data)[source]¶

Implement this method to run the model

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

Notes

See docs on 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 methods such as:

parameter_value = data.get_parameter('my_parameter_name')

Other useful methods are get_base_timestep_data(), get_previous_timestep_data(), get_parameter(), get_data(), get_parameters() and get_results().

get_state() returns a list of intervention dict for the current timestep get_current_interventions() returns a list of dict where each dict is an intervention

class smif.model.SosModel(name)[source]¶

Bases: object

Consists of the collection of models joined via dependencies

Parameters:: name (str) – The unique name of the SosModel

add_dependency(source_model, source_output_name, sink_model, sink_input_name, timestep=RelativeTimestep.CURRENT)[source]¶

Adds a dependency to this system-of-systems model

Parameters:

source_model (smif.model.model.Model) – A reference to the source ~smif.model.model.Model object
source_output_name (string) – The name of the model_output defined in the source_model
source_model – A reference to the source ~smif.model.model.Model object
sink_name (string) – The name of a model_input defined in this object
timestep (smif.metadata.RelativeTimestep, optional) – The relative timestep of the dependency, defaults to CURRENT, may be PREVIOUS.

add_model(model)[source]¶

Adds a model to the system-of-systems model

Parameters:: model (smif.model.model.Model)

add_narrative(narrative)[source]¶

Add a narrative to the system-of-systems model

Parameters:: narrative (dict)

as_dict()[source]¶

Serialize the SosModel object

Return type:: dict

check_dependencies()[source]¶: For each contained model, compare dependency list against list of available models

property dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property free_inputs¶

Returns the free inputs to models which are not yet linked to a dependency.

Returns:: dict of {(model_name, input_name)
Return type:: smif.metadata.Spec}

classmethod from_dict(data, models=None)[source]¶

Create a SosModel from config data

Parameters:

data (dict) – Configuration data. Must include name. May include description. If models are provided, must include dependencies.
models (list of Model) – Optional. If provided, must include each ScenarioModel and SectorModel referred to in the data[‘dependencies’]

get_model(model_name)[source]¶

Get a model by name

Parameters:: model_name (str)
Return type:: smif.model.model.Model

property model_dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property models¶

The models contained within this system-of-systems model

Return type:: list[smif.model.model.Model]

property outputs¶

All model outputs provided by models contained within this SosModel

Returns:: dict of {(model_name, output_name)
Return type:: smif.metadata.Spec}

property scenario_dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property scenario_models¶

Scenario model objects contained in the SosModel

Returns:: A list of scenario model objects
Return type:: list

property sector_models¶

Sector model objects contained in the SosModel

Returns:: A list of sector model objects
Return type:: list

Submodules¶

smif.model.dependency module¶

Dependencies represent the flow of data explicitly, with reference to the source model output and sink model input.

A Dependency is an edge in the model process graph. No processing happens on dependency edges, only on the Model nodes.

A Dependency can have a timestep specified - by default this is the current timestep, but a system-of-systems model may also want to specify that data should be provided from the previous timestep or a base timestep.

class smif.model.dependency.Dependency(source_model, source, sink_model, sink, timestep=RelativeTimestep.CURRENT)[source]¶

Bases: object

Link a model input to a data source

Parameters:

source_model (smif.model.Model) – The source model object
source (smif.metadata.Spec) – The source output description
sink_model (smif.model.Model) – The sink model object
sink (smif.metadata.Spec) – The sink input description
timestep (smif.metadata.RelativeTimestep, optional) – The relative timestep of the dependency, defaults to CURRENT

as_dict()[source]¶: Serialise to dictionary representation

smif.model.model module¶

Model abstract class

class smif.model.model.Model(name)[source]¶

Bases: object

Abstract class represents the interface used to implement the model classes SectorModel and ScenarioModel.

Parameters:: name (str)

add_input(spec)[source]¶

Add an input

Parameters:: spec (smif.metadata.Spec)

add_output(spec)[source]¶

Add an output

Parameters:: spec (smif.metadata.Spec)

add_parameter(spec)[source]¶

Add a parameter

Parameters:: spec (smif.metadata.Spec)

as_dict()[source]¶

Serialize the SectorModel object as a dictionary

Return type:: dict

classmethod from_dict(config)[source]¶: Create object from dictionary serialisation

property inputs¶

All model inputs defined at this layer

Returns:: dict of {input_name
Return type:: smif.metadata.Spec}

property outputs¶

All model outputs defined at this layer

Returns:: dict of {output_name
Return type:: smif.metadata.Spec}

property parameters¶

Model parameters

Returns:: dict of {parameter_name
Return type:: smif.data_layer.data_array.DataArray}

simulate(data)[source]¶

Override to implement the generation of model results

Generate results for timestep using data

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

class smif.model.model.ModelOperation(*values)[source]¶

Bases: Enum

Enumerate that describes the possible operations on Models

BEFORE_MODEL_RUN = 'before_model_run'¶

SIMULATE = 'simulate'¶

class smif.model.model.ScenarioModel(name)[source]¶

Bases: Model

Represents exogenous scenario data

Parameters:: name (str) – The name of this scenario (scenario set/abstract scenario/scenario group) - like sector model name

name¶

Name of this scenario

Type:: str

scenario¶

Instance of scenario (concrete instance)

Type:: str

as_dict()[source]¶: Serialise ScenarioModel to dict

classmethod from_dict(data)[source]¶: Create ScenarioModel from dict serialisation

simulate(data)[source]¶: No-op, as the data is assumed to be already available in the store

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.

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 scalar/vector values to the framework to enable measurements of performance, particularly for the purposes of optimisation and rule-based approaches

class smif.model.sector_model.SectorModel(name)[source]¶

Bases: 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 must be overridden are:

SectorModel.simulate()
SectorModel.extract_obj()

An implementation may also override:

SectorModel.before_model_run()

before_model_run(data)[source]¶

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) Access decision/system state (i.e. initial_conditions)

simulate(data)[source]¶

Implement this method to run the model

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

Notes

See docs on 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 methods such as:

parameter_value = data.get_parameter('my_parameter_name')

Other useful methods are get_base_timestep_data(), get_previous_timestep_data(), get_parameter(), get_data(), get_parameters() and get_results().

get_state() returns a list of intervention dict for the current timestep get_current_interventions() returns a list of dict where each dict is an intervention

smif.model.sos_model module¶

This module coordinates the software components that make up the integration framework.

A system of systems model contains simulation and scenario models, and the dependencies between the models.

class smif.model.sos_model.SosModel(name)[source]¶

Bases: object

Consists of the collection of models joined via dependencies

Parameters:: name (str) – The unique name of the SosModel

add_dependency(source_model, source_output_name, sink_model, sink_input_name, timestep=RelativeTimestep.CURRENT)[source]¶

Adds a dependency to this system-of-systems model

Parameters:

source_model (smif.model.model.Model) – A reference to the source ~smif.model.model.Model object
source_output_name (string) – The name of the model_output defined in the source_model
source_model – A reference to the source ~smif.model.model.Model object
sink_name (string) – The name of a model_input defined in this object
timestep (smif.metadata.RelativeTimestep, optional) – The relative timestep of the dependency, defaults to CURRENT, may be PREVIOUS.

add_model(model)[source]¶

Adds a model to the system-of-systems model

Parameters:: model (smif.model.model.Model)

add_narrative(narrative)[source]¶

Add a narrative to the system-of-systems model

Parameters:: narrative (dict)

as_dict()[source]¶

Serialize the SosModel object

Return type:: dict

check_dependencies()[source]¶: For each contained model, compare dependency list against list of available models

property dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property free_inputs¶

Returns the free inputs to models which are not yet linked to a dependency.

Returns:: dict of {(model_name, input_name)
Return type:: smif.metadata.Spec}

classmethod from_dict(data, models=None)[source]¶

Create a SosModel from config data

Parameters:

data (dict) – Configuration data. Must include name. May include description. If models are provided, must include dependencies.
models (list of Model) – Optional. If provided, must include each ScenarioModel and SectorModel referred to in the data[‘dependencies’]

get_model(model_name)[source]¶

Get a model by name

Parameters:: model_name (str)
Return type:: smif.model.model.Model

property model_dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property models¶

The models contained within this system-of-systems model

Return type:: list[smif.model.model.Model]

property outputs¶

All model outputs provided by models contained within this SosModel

Returns:: dict of {(model_name, output_name)
Return type:: smif.metadata.Spec}

property scenario_dependencies¶

Dependency connections between models within this system-of-systems model

Return type:: iterable[smif.model.dependency.Dependency]

property scenario_models¶

Scenario model objects contained in the SosModel

Returns:: A list of scenario model objects
Return type:: list

property sector_models¶

Sector model objects contained in the SosModel

Returns:: A list of sector model objects
Return type:: list

smif.model package¶

Submodules¶

smif.model.dependency module¶

smif.model.model module¶

smif.model.sector_model module¶

Key Functions¶

smif.model.sos_model module¶

smif

Navigation

Related Topics