use_cases
See - Actors for a list of actors
- Summary
- Input data
- Configuring individual and collections of models
- Performing model runs and analysing results
- Technical Details
- Actor manages data
- Actor manages infrastructure simulation models
- Actor manages system-of-systems models
- Actor manages model runs
- Some time later, Actor performs a model run
- Actor analyses results
- Actor Manages Scenario Sets
- Actor Manages Narrative Sets
- Actor Manages Spatial Resolution Sets
- Actor Manages Temporal Resolution Sets
A Scenario is a source of data which is used to manage uncertainties beyond the control of a decision maker. For all practical purposes, models treat scenarios as a source of model input values. As with other data sources, scenarios have a spatial and temporal resolution.
A Scenario Set is a collection of scenarios of the same type. When configuring a SosModel, free inputs to a model will be associated with a Scenario Set, deferring the choice of scenario to the definition of the Model Run.
Chris uploads the electricity demand scenario data using the scenario manager.
He first defines a new scenario set called Demand Scenarios, then adds the
central electricity demand scenario to the set, uploading the data from a
flat file. He then selects the spatial and temporal resolution already uploaded
in the gazateer to associate with the central electricity demand scenario.
- Actor navigates to the data management page
- «system» displays list of existing Scenario Sets
- Actor creates a new scenario set and gives it a unique name and description
- Actor manages scenarios
- «system» writes changes to «database»
3 a. Actor edits an existing Scenario Set
- Actor selects existing scenario from the list
- Actor amends attributes
- Actor save changes
- «system» write changes to database
3 b. Actor deletes an existing Scenario Set
- Actor selects existing scenario from the list
- Actor amends attributes
- Actor save changes
- «system» write changes to database
- «system» displays list of existing scenarios
- Actor creates a new scenario
- «system» displays import dialogue
- Actor selects a flat file containing value, locational and time data
- Actor selects relevant metadata including appropriate spatial and temporal resolutions
- «system» reads in data and writes to «database»
3 a. Actor edits an existing scenario
- Actor selects existing scenario from the list
- Actor amends attributes
- Actor save changes
- «system» write changes to database
3 b. Actor deletes an existing scenario
- Actor selects existing scenario from the list
- «system» requests confirmation
- «system» write changes to database
- Actor navigates to the data management page
- «system» displays list of existing Narrative Sets
- Actor creates a new Narrative Set and gives it a unique name and description
- Actor manages narratives
- «system» writes changes to «database»
3 a. Actor edits an existing Narrative Set
- Actor selects existing Narrative Set from the list
- Actor amends attributes
- Actor save changes
- «system» write changes to database
3 b. Actor deletes an existing Narrative Set
- Actor selects existing Narrative Set from the list
- «system» requests delete confirmation
- «system» write changes to database
- «system» displays list of existing narratives
- Actor creates a new narrative
- Actor configures narrative
- «system» writes to «database»
3 a. Actor edits an existing narrative
- Actor selects existing narrative from the list
- Actor amends attributes
- Actor save changes
- «system» write changes to database
3 b. Actor deletes an existing narrative
- Actor selects existing narrative from the list
- «system» requests confirmation
- «system» write changes to database
To be written
- «system» displays list of resolution sets
- Actor creates new resolution definition
- Actor enters unique name, selects type (temporal or spatial) and enters path to the data file
- «system» validates and writes resolution definition to «database»
2 a. Edit existing resolution definition
- Actor selects existing resolution definition
- Actor edits attributes
- «system» validates and writes changes to «database»
2 b. Delete existing resolution definition
- Actor selects existing resolution definition
- «system» confirms deletion action
- «system» writes changes to «database»
An Intervention is a possible action which has a name, a number of
required attributes, including capital cost, economic_lifetime, capacity
and operational_life, other attributes and location, but no build date.
Interventions are intrinsically linked to simulation models in that they correspond to one, and only one simulation model.
Interventions are collected into a package within a SoSModel so that the Decision Manager can choose which to perform, where and when. The Intervention is the smallest divisible unit of a decision within the framework.
- Actor navigates to the intervention manager screen
- «system» displays list of existing interventions
- Actor adds new interventions with required attributes, suggested attributes and/or custom attributes
- Actor saves intervention
- «system» saves intervention to the «database»
3 a. Import interventions from a yaml file
- Actor clicks "import interventions" button, dialogue asks Actor to select a file, (dialogue filters to *.yaml, *.yml files).
- Actor selects one or more yaml files and clicks "import" button. Dialogue box closes.
- Interventions are imported and appear in intervention list.
3 b. Edit an existing intervention
- Actor selects the intervention to edit
- «system» retrieves intervention from database
- Actor makes changes
- «system» writes changes to «database»
3 c. Delete an existing intervention
- Actor selects the intervention to delete
- «system» requests confirmation
- «system» writes changes to «database»
3 a. One or more interventions already exist in list
- «system» displays list of duplicate interventions.
- Actor chooses duplicate from the list to retain
Harpreet is an energy modeller who wishes to couple the energy supply
simulation model she is developing with an existing water supply model. She
wants to investigate the resilience of the electricity system
to constraints on water abstractions during drought events. Harpreet has
written a wrapper for her model executable using the smif.SectorModel class
and identified one key input to the model (electricity_demand) and
two key outputs (water_demand, unmet_demand).
Harpreet also writes a spatial and a temporal resolution definition file
which apply to all inputs and outputs.
Harpreet logs onto the «system» and navigates to her project. She chooses to
create a new model configuration, which she names es_resilience. She then
directs the system to her wrapper file,
registers the spatial and temporal resolutions with the gazateer and uploads
the data.
She then adds the inputs and outputs, associating each of them with the spatial
and temporal resolutions registered previously. She checks the visual
representation of her model configuration and notes the one input and two
outputs detailed on the diagram. Hovering her mouse over, she can view the
meta-data associated with the input and outputs. She adds some notes to her
configuration, and sets the model version to match that of the model
from her version control system.
- How do we manage simulation model versions from the interface?
- Should we use a composite type approach, where a SosModel is a model, a SectorModel is a model and a SosModel comprises of a collection of models? In this situation, a scenario would also be a subclass of Model, with one ModelOutput deferring the actual data loaded to runtime (and specified in the model run).
Each of the simulation models needs to be configured so that it
can be run by smif. Models are wrapped using the SectorModel class which
exposes initialise and simulate methods.
Models have input and output parameters,
each of which have spatial and temporal resolutions definitions stored in the
interval and region registers.
- Actor navigates to simulation model configuration interface page
- «system» displays a list of existing simulation model configurations
- Actor adds a new simulation model configuration
- Actor enters unique model name and the path to the model wrapper (to execute the model)
- «system» displays list of classnames in model wrapper
- Actor chooses the classname from list
- Actor Manages Interventions
- Actor Manages Parameter Configurations
- Actor saves simulation model configuration
- «system» saves configuration to «database»
- «system» returns focus to model configuration interface page now displaying added model configuration
3 a. Edit an existing simulation model configuration
- Actor views the list of model configurations
- Actor selects model configuration to edit
- «system» requests configuration data from «database»
- "Edit model configuration" form is displayed with entries for various attributes.
- Actor edits the entries and saves changes
- «system» saves changes to «database»
3 b. Delete an existing simulation model configuration
- Actor views the list of model configurations
- Actor selects model configuration to delete
- «system» requests confirmation of deletion
- Actor confirms deletion
- «system» saves changes to «database»
2 a. No model configurations exist
- «system» displays message saying that there are no existing configurations
8 a. Database connection error
- Resolve connection problems
Gerald wishes to expose several of the energy demand model parameters to those who will use his model. There are two key model parameters he wishes to add today, smart meter energy savings and technology uptake which needs to be specified for each end-use and technology.
Gerald logs onto the system and navigates to the energy demand model configuration. He navigates to the model parameter list, and adds a new parameter.
The first parameter, smart meter energy savings is a floating point number, with a suggested range from the literature of between 3%-10%. He adds the unique name smart meter energy savings, a helpful description of what this parameter does, the type (float), an absolute range [0, 1] and a suggested range [0.03-0.1], a default value of 0.03 and % for the units attribute.
Gerald adds another new parameter with the name technology uptake %%tech%% %%end-use%%. First, Gerald defines the two dimensions over which the technology uptake parameter will be expanded. He adds the set tech contains a list of three technologies [washing machine, dishwasher, incandescent lighting, LED lighting] and the set end-use contains [wet, lighting] to the parameter configuration. He then appends the default values of the parameter attributes to the parameter, including range: [0, 1], type: float, description: "Technology uptake for %%tech%% for end-use %%end-use%%". After saving the parameters are visible for each of the tech and end-use combinations e.g.
name: technology uptake washing machine wet
range: [0, 1]
type: float
description: "Technology uptake for washing machine for end-use wet"
- «system» displays list of model parameters
- Actor creates new parameter configuration with a unique (to the simulation model) name, plus attributes including description, default value, range, suggested range, dimension, type (float, int, bool),
- «system» validates changes and writes parameter configuration to «database»
2 a. Edit an existing parameter
- Actor selects a parameter to edit from the list
- Actor amends parameter attributes
- «system» validates changes and writes changes to «database»
2 b. Delete an existing parameter
- Actor selects parameter to delete
- «system» requests confirmation of deletion
- «system» saves changes to «database»
1 a. No parameters exist yet
- «system» prompts Actor to create a new parameter configuration
2 a. Parameter fails validation checks e.g. default value not in range
- «system» prompts Actor to amend parameter attributes
A SosModel is a collection of simulation models with a requirement for data input.
Chris, Harpreet's colleague, has finished work on the water supply model, and has already configured it using the «system». He's now ready to define a new system-of-systems model (SosModel), which will couple the two simulation models together.
Chris logs into the «system» and selects the water-energy-resilience project.
He navigates to the SosModel configuration page and follows the instructions
shown as this is the first time he's configured a SosModel. The instructions
direct him to create a new SosModel configuration. Presented with a list
of previously defined simulation models, he selects the energy model which was
configured by his colleague Harpreet called es_resilience. He reviews the
notes and description associated with the energy model and scans them for any
particular issues Harpreet identified.
He then selects his water model and confirms the additions to his SosModel
project.
Now two models exist in the SosModel configuration, Chris needs to link the
model input and outputs to one another to define dependencies. The «system»
displays a visual representation of the models inputs and outputs.
He connects the water_demand output from energy model to the water_demand
input of the water supply model.
A «system» warning notifies Chris that he has connected
inputs and outputs with a different spatio-temporal resolution. Luckily,
Chris is prepared, and has written a function to cope with this which he wishes
to use instead of the default assumption of area weighting. He selects the
function and adds it to the configuration. Chris now selects the remaining
input to the energy model, electricity demand, and categorises its source as
a scenario input. Then, he selects the rainfall input to the water supply
model and categorises its source as a scenario input. This will allow him to
select multiple different scenarios when running this SosModel i.e. defer the
selection of the model inputs to the definition of the model run.
Chris saves the SosModel configuration and goes for a cup of tea.
- Actor navigates to SosModel configuration
- «system» shows list of existing SosModel configurations
- Actor creates a new SosModel
- «system» displays a list of available simulation model configurations
- Actor selects one or more simulation models from list
- Actor manages simulation models as required
- «system» provides list of the aggregate model inputs required and the model outputs produced by the collection of simulation models
- Actor links the inputs and outputs between pairs of models, where relevant, to define the data dependencies between the models
- Actor defines custom spatio-temporal conversion functions along each of the dependencies, or accepts the default assumption of area weighting
- «system» computes the running order of the models suggested by the graph of dependencies and indicates where iteration will be necessary
- When happy with the collection of simulation models in the SosModel, the defined dependencies, the running order, and the remaining inputs and outputs, the Actor saves the configuration
- «system» validates SosModel configuration
- The focus returns to the list of existing SosModel configurations, now displaying the newly created SosModel
4 a. There are no existing simulation model configurations
- «system» asks Actor to add a new SosModel configuration
4 b. The required simulatiom model configuration does not exist
- «system» asks Actor to add a new SosModel configuration
7 None of the simulation model configurations have inputs or outputs
- Edge case - no use for smif in this situation. Simulation model configurations are invalid
10 Running order is infeasible
- Raise an error and return to linking of inputs and outputs step
13 Database connection fails and unable to save configuration
- Save configuration locally to text file
3 a. Edit an existing SosModel
- Actor selects SosModel to edit
- «system» retrieves SosModel configuration
- Actor edits SosModel configuration and saves changes
- «system» writes changes to «database»
3 b. Copy an existing SosModel
- Actor selects SosModel to copy
- «system» duplicates SosModel configuration and requests unique name
- Actor enters unique name for new SosModel
- «system» writes changes to «database»
3 c. Delete an existing SosModel
- Actor views the list of SosModel configurations
- Actor selects SosModel to delete
- «system» requests confirmation of deletion
- Actor confirms deletion
- «system» saves changes to «database»
Harpreet and Chris now wish to conduct a number of model runs using their
combined energy and water system-of-systems model. They start by defining a
reference scenario model run. Harpreet navigates to the model run configuration
page, and observes the empty list of model runs. Clicking on the 'New Model Run'
button, she enters a description of the model run, and selects the SosModel
configuration es_resilience from a list. A visual graphic representing the
SosModel pops up showing the inputs rainfall and electricity demand and the
outputs unmet demand. The unmet demand parameter is automatically linked
to a results node. The rainfall and electricity demand are unlinked.
Harpreet selects the rainfall sub-category of climate scenario central case
from a series of drop down menus, and rainfall appears as a data source on
the visualisation. She drags a link between the two rainfall nodes to link
them, accepting the default area-weighting for spatio-temporal conversion.
She then selects the electricity demand data source from the New Data Source
menu and links that to the electricity demand node.
The Model Run collects scenarios, timesteps, narratives, and system-of-system models into a package which can be deployed and run.
Once a Model Run has been performed (simulated) successfully, then the configuration is locked to maintain data provenance. Model Runs can only be duplicated, edited and rerun.
Actor chooses to create a new model run
- Actor navigates to the model run screen
- «system» displays a list of model runs
- Actor creates a new model run, entering a unique name, and choosing a SosModel from the list of available SosModel
- Actor chooses from a list of time steps which define the years for which the model will run
- For all inputs to the SosModel which do not match to a data source (either an external data source or another model output), «system» displays a warning
- For each NarrativeSet, Actor chooses a narrative
- For each model input: Actor provides data for model input
- Actor saves the model run configuration
- «system» saves new configuration to the «database»
- «system» adds displays configuration name and summary metadata in the Model Run list
-
No SosModel definitions have been configured
- Configure a SosModel
2 a. Configure a new model run from an existing model run
- Actor creates a new Model Run, checking a tick box indicating that she wishes to copy an existing Model Run
- «system» notifies Actor to choose an existing Model Run
- Actor selects from a list of model run configurations
- New model run is created on «system»
- «system» notifies Actor to enter a unique name for the model run
- Actor is able to edit the configuration and save/cancel the changes.
- «system» tags the model run with a warning symbol if it appears to duplicate an existing model run (nothing is different from the parent model run).
2 b. Copy an existing Model Run
2 c. Delete an existing Model Run
2 d. Edit an existing Model Run. Only non-running
Within a Model Run definition, any free-hanging model inputs in the chosen SosModel must be linked to scenario data
- Actor chooses to add scenario data for the model input.
- «system» displays list of available scenarios within the scenario set defined wihtin the sector model definition.
- Actor selects one of the scenarios
-
No scenarios have been defined
- «system» asks Actor to define scenario data sources
After finishing the configuration of the model run, Harpreet navigates to the
Model Run list, and scans through the list. She filters by model run status, to
show only runs with the status Ready. She selects the model run, and clicks
Submit Model Run. The system responds informing her that the run has been
submitted to the job queue
- Actor selects a model run
- Actor submits run for simulation
- «system» locks and deploys model run
- «system» notifies Actor that model run has been submitted
- «system» creates results entry for model run
- «system» notifies Actor of successful completion
- «system» populates results entry with data from «database»
3 a. Model run fails 3 b. Model is infeasible (optimisation)
- PlanningHorizon is a parameter of the ModelRun
- Behaviour of Decision Manager is a function of PlanningHorizon and DecisionModule type (planning/rules/optimisation)
- Actor builds SosModel object adding SectorModels and Dependencies
- Actor creates instance of ModelRunner and passes SosModel object to ModelRunner
- ModelRunner Runs the Model and returns results
- «system» saves results to database
- Actor receives the run order from ModelRun along with SosModel, ModelHorizon, DecisionManager, Scenario, and Narrative objects.
- For each year in the ModelHorizon:
- Actor asks DecisionManager for decision information
- DecisionManager responds with a list of Decisions
- Actor passes scenario data reference to SosModel and asks SosModel to initialise itself
- Actor passes the decision to the SosModel and runs a simulation
Harpreet returns to the Model Run screen and filters on Successful
status. No model run appears, as her run has not yet finished. She removes the
filter and sorts by Submission Time and finds her Model Run at the top of
the list. She selects it and tries to click View Results, but the button is
greyed out.
Later, Harpreet returns to the Model Run screen and filters on Successful
status. He model run appears at the top of the list.
She selects it and clicks View Results. The black results dashboard is
displayed with space where a range of useful metrics could be shown. She
configures the dashboard with a number of useful result widgets, so that she can
ensure at a glance that the model is performing as it should.
- Actor navigates to results viewer
- «system» displays list of completed model runs with linked results
- Actor selects model run
- «system» displays model results
- Actor navigates to bundle viewer
- «system» displays list of bundles
- Actor Manage bundles
- Actor selects a bundle
- «system» retrieves bundle from «database» and displays results comparison
4 a. Bundle contains model runs with no results
- «system» shows results of only model runs with results and warning for others
5 a. Model run results are identical
- «system» displays warning that results difference cannot be shown as results are identical
A bundle is a collection of model runs within a project which enables results comparison of one or more model runs.
- Actor navigates to bundle viewer
- «system» displays list of existing bundles
- Actor creates new bundle
- «system» displays list of model runs of all statuses
- Actor selects one or more model runs to add to bundle
- «system» saves bundle to «database»
Actor is on the model run page and a successfully completed model run exists in the model run list
- «system» displays list of model runs
- Actor selects completed model run in the list of model runs
- «system» displays results dashboard for model run
Derek defines a series of business rules in the rule-based decision layer which represent how the solid waste sector performs its regulatory duties. He does this by linking the value of model outputs with conditions and defining actions to be taken when those conditions are not met.
He starts up the model run. The model runner configures the decision manager with the rule-based algorithm. The algorithm compiles the rules, runs the SosModel simulation (which includes the solid waste model) for the first time period in a first iteration. A high 'emissions' model output causes one of the rule conditions to fail, and the algorithm chooses one intervetion from a set of interventions as the action. The algorithm reruns for a second iteration and the new action corrects the path of the model. Now all the conditions are met, the model completes successfully, and the sequence of decisions is returned to the model runner.
While the model is running, Derek observes the log which details the actions which are triggered by the model outputs and the performance of the model.
Jenny sets up her model-run with an optimisation algorithm which chooses decisions according to the criteria of least cost. The planning window is set to the default value, which is the same length as the model horizon. She sets the model running. The algorithm runs a number of iterations until it arrives at the lowest cost.
In each iteration, the algorithm selects, for each timestep in the horizon, a number of interventions from the list of available interventions and runs the simulation on the SosModel.
After each run of the SosModel, the algorithm now receives results of the simulation and assesses whether it should continue exploring the decision space or exploit the current best available decision.
Jenny views the progress of the algorithm via the logs, which detail the time, interventions and model results for each iteration and timestep the algorithm visited.
Once the algorithm terminates, it returns the sequence of interventions in each timestep that meet the objective function and constraints.
Jenny modifies her optimisation algorithm to try to represent the short-term decision horizon in the water supply sector. She sets the planning window to 10 years, meaning that in each timestep, the algorithm only looks 10 years ahead when assessing whether the current decision is optimal, all other information is disregarded. This results in the creation of a sub-problem with a horizon of 10 years rather than the entire model horizon. The algorithm iterates over this sub-problem until it finds an optimal solution, fixes the decisions in the initial timestep, and then moves to the next timestep whereupon the process begins again.
Interventions are chosen in each timestep in a Planning View. Interventions are only persisted for the first timestep in the Planning View.
The set of Planning Views is a deterministic function of the model horizon and the planning window. If the planning window does not cover the model horizon, on each iteration, the algorithm moves to the PlanningView which begins with the next timestep and continues until the whole model horizon has been covered. The system state is copied from the end of the previous timestep.
An Iteration is a single pass through the timesteps in a planning view.
Modeller sets PlanningWindow parameter to 1
- ModelRunner requests PlanningView for SosModel configuration
- PlanningView returns decision epochs (set of timesteps for which to make decisions) for first year
- ModelRunner creates new Iteration with current year and planning view.
- ModelRunner sends iteration to decision manager with a request for decisions.
- Decision Manager adds decisions to Iteration.
- ModelRunner performs Iteration by sending decisions to SosModel with simulate command.
- SosModel sends ModelRunner results.
- ModelRunner attaches results to Iteration
1 a. Planning Window is 1 < x < ModelHorizon
- In each timestep, decisions are chosen for the current timestep, and then each timestep in the PlanningView is performed to assess performance. Algorithm then moves to the next timestep. 1 b. Planning Window is set to 0 (don't use window)
- ModelRunner runs over all timesteps in the model horizon
- Actor navigates to planning interface
- «system» displays list of strategies
- Actor creates a new pre-specified planning strategy with a unique name and a description
- For each of the sectors in turn, Actor associates one or more interventions from the list populated by the sector models with a timestep from the Model Run
- «system» writes the data to the «database»
- {as above}
- Interface doesn't let Actor create a new planning strategy and displays a warning message saying that no interventions have been defined.
-
DM asks strategy for a decision
-
Strategy requests list of available interventions
-
SosModel returns list of interventions
-
Controller requests results from Model Runner for Model Run
-
Model Runner looks up Strategy Configuration for Model Run
-
Model Runner Loads SosModel Data
-
Model Runner initialises Decision Manager with configuration
-
Model Runner requests decisions from Decision Manager for Time Horizon
-
Decision Manager
Title: Actor: Scenario:
Extensions: (when things go wrong)
Precondition: (what must be true to begin this use case)
Postcondition: Stakeholders: Technology list: Scope: Level:
