Skip to content

configuration

Jump to bottom
Will Usher edited this page Oct 17, 2017 · 19 revisions

Specification for Project Configuration

A project contains all the components required to configure and run a system of systems model. The components are in decreasing order of dependency:

  • model run list
  • sos model list
  • sector model list
  • scenario set list
  • narrative set list
  • region set list
  • interval set list
  • units

The project folder structure should look something like this:

/nismod2
  project.yml
  /config
    /sector_models
      energy_demand.yml
      energy_supply.yml
    /sos_models
      energy.yml
    /model_runs
      20170918_energy.yml
  /data
    /initial_conditions
      energy_demand_existing.yml
      energy_supply_existing.yml
    /intervals
      # Columns: id, start_hour, end_hour
      hourly.csv
      annual.csv
    /interventions
      # Keys: name, capital_cost, lifetime, capacity, location, custom attributes
      energy_demand.yml
    /narratives
      energy_demand_high_tech.yml
      central_planning.yml
    /regions
      lad.shp
    /scenarios
      # Columns: timestep, region, interval, value
      population_high.csv
    units.yml

The project.yml file contains all metadata and a record of the contents of the configuration and data folders.

Activity Diagram

Configuration Activity Diagram

Project File

An example of a fully populated project.yml file:

project_name: "NISMOD v2.0"
scenario_sets:
- name: population
  description: 'The annual change in UK population'
narrative_sets:
- name: technology
  description: 'Defines the rate and nature of technological change'
- name: governance
  description: 'Defines the nature of governance and influence upon decisions'
region_sets:
- name: lad
  description: 'Local authority districts for the UK'
  filename: lad.shp
interval_sets:
- name: hourly
  description: 'The 8760 hours in the year named by hour'
  filename: hourly.csv
- name: annual
  description: 'One annual timestep, used for aggregate yearly data'
  filename: annual.csv
units: user_units.txt # Pint config file
scenario_data:
- name: 'High Population (ONS)'
  description: 'The High ONS Forecast for UK population out to 2050'
  scenario_set: population
  parameters:
  - name: population_count # Enables one or more outputs to be defined per scenario e.g. counts, density, floor area, household numbers, etc.
    spatial_resolution: lad
    temporal_resolution: annual
    units: people
    filename: population_high.csv
- name: 'Low Population (ONS)'
  description: 'The Low ONS Forecast for UK population out to 2050'
  scenario_set: population
  parameters:
  - name: population_count 
    spatial_resolution: lad
    temporal_resolution: annual
    units: people
    filename: population_low.csv
narrative_data:
- name: 'Energy Demand - High Tech'
  description: 'High penetration of SMART technology on the demand side'
  filename: energy_demand_high_tech.yml
  narrative_set: technology
- name: 'Central Planning'
  description: 'Stronger role for central government in planning and regulation, less emphasis on market-based solutions'
  filename: central_planning.yml
  narrative_set: governance

Note that the contents of the project.yml file is mainly to contain meta data which describes the contents of the data folder.

We may wish to divide up the project.yml file to reflect the requirements to CRUD the various elements of the file, without having to read in and write out the whole file whenever a change is made to an individual element?

Configuring a project

The process of configuring a model commences from the bottom up, from atomic components to more complex composites of these components.

Prior to defining models or loading data, there are a small number of project level specifications:

  • specify project folder/data connection (could be implicit in current folder location)
  • define scenario sets e.g. population, economic growth, climate (Use Case 3)
  • define narrative sets e.g. governance, technology (Use Case 5)

Managing Project Data

Project level data is required by all other elements that make up a system-of-systems model.

Strictly speaking, only the definition of scenario sets are required for configuration of sector model input and outputs, but data is required at runtime.

Model-specific project configuration

From the main project page, the GUI should allow users to CRUD:

  1. sector models
  2. sos models
  3. model runs

Creation of SosModels can only proceed after one or more sector models have been (fully) defined.

Creation of Model Runs can only proceed once one or more SosModels have been defined.

Managing Sector Model Configuration

The process of adding a sector model follows the order shown below:

Asterixed (*) tasks are optional and can be completed later. The system should visually warn the user if these elements are empty.

The addition of a sector model should create the file e.g. energy_demand.yml in the /config/sector_models/ folder.

An example sector model configurationfile:

name: energy_demand
description: 'Computes the energy demand of the UK population for each timestep'
path: ../../models/energy_demand/run.py
classname: EnergyDemandWrapper
inputs:
- name: population
  spatial_resolution: lad
  temporal_resolution: annual
  units: people
outputs:
- name: gas_demand
  spatial_resolution: lad
  temporal_resolution: hourly
  units: GWh
parameters:
- name: assump_diff_floorarea_pp
  description: 'Difference in floor area per person in end year compared to base year'
  absolute_range: (0.5, 2)
  suggested_range: (0.5, 2)
  default_value: 1
  units: percentage
interventions:
- ./energy_demand.yml
initial_conditions:
- energy_demand_existing.yml

Sos Model

A sos model brings together previously defined sector models, scenario sets using dependencies to create a graph of interdependencies.

Tasks:

  • add one or more sector models
  • add one or more scenarios (upto one of each from the scenario sets defined)
  • define dependencies to satisfy all model inputs
name: energy
description: 'A system of systems model which encapsulates the future supply and demand of energy for the UK'
scenario_sets: # Select 0 or more of the scenario sets
- population 
sector_models: # Select 1 or more of the sector models
- energy_demand
- energy_supply
dependencies: # Define dependencies to satisfy all model inputs
- source_model: population
  source_model_output: count
  sink_model: energy_demand
  sink_model_input: population
- source_model: energy_demand
  source_model_output: gas_demand
  sink_model: energy_supply
  sink_model_input: natural_gas_demand
max_iterations: 20
convergence_absolute_tolerance: 1e-5
convergence_relative_tolerance: 1e-5

Model Run

  • define list of timesteps (a subset of consecutive or non-consecutive years from 2015 to 2050 inclusive)
  • add one sos_model
  • decision module
  • add narrative data

An example model run configuration file:

name: 'unique_model_run_name'
description: 'a description of what the model run contains'
stamp: 2017-09-20T12:53:23+00:00
timesteps:
- 2015
- 2020
- 2025
sos_model: energy
decision_module: energy_moea.py # A python implementation of an algorithm
scenarios:
- population: 'High Population (ONS)'
narratives:
- technology:
  - 'Energy Demand - High Tech'
- governance: 'Central Planning'

An Example Narrative File

global:
  discount_rate: 0.05
energy_demand:
  assump_diff_floorarea_pp: 0.5

Example Intervals File

Columns: id, start_hour, end_hour

id,start_hour,end_hour
1,PT0H,PT8760H

Example Scenario File

timestep,region,interval,value
2010,England,1,52000000
2010,Scotland,1,5100000
2010,Wales,1,2900000
2015,England,1,53000000
2015,Scotland,1,5300000
2015,Wales,1,3000000
2020,England,1,54000000
2020,Scotland,1,5500000
2020,Wales,1,3200000

Example Region File

See example geojson file

ITRC Banner

Home

Clone this wiki locally