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 input parameter 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
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?
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, the path to the model wrapper, and the model configuration directory.
- «system» displays list of classnames in model wrapper
- Actor chooses the classname from list
- Actor Manages Interventions
- Actor saves simulation model configuration
- «system» saves configuration to «database»
- «system» returns focus to model configuration interface page now displaying added model configuration
-
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»
-
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
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 input parameters 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 input parameter: Actor provides data for input parameter
- 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 input parameters in the chosen SosModel must be linked to scenario data
- Actor chooses to add scenario data for the input parameter.
- «system» displays list of available scenarios
- 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 Model Run
- Behaviour of Decision Manager is a function of PlanningHorizon and DecisionModule type (planning/rules/optimisation)
- Actor Initialise Model Run
- Actor Requests Decisions
- Decision Manager Makes Decisions
- Actor Runs simulation with decisions
- Actor Persists results
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
- 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:
