Skip to content
master
Switch branches/tags
Code

SIRA

Overview

The detailed documentation is at this link.

SIRA stands for Systemic Infrastructure Resilience Analysis. It represents a methodology and supporting code for systematising vulnerability analysis of lifeline infrastructure to natural hazards (i.e. response of infrastructure assets to environmental excitation). SIRA is open source.

The impact assessment is based on the fragilities and configuration of components that comprise the infrastructure system under study. The analytical process is supplemented by an assessment of the system functionality through the post-damage network flow analysis, and approximations for recovery timeframes.

The current focus has been on studying responses of infrastructure facilities (e.g. power generation plants, high voltage substations). Considerable work has been done in the code backend to extend the same methodology to modelling network vulnerability as well (e.g. electricity transmission networks).

SIRA models are based on graph theory. All infrastructure systems are represented as networks. This allows an user to develop arbitrarily complex models of a infrastructure facility or a network to be used in impact simulation.

Setup Instructions

It is good practice to set up a virtual environment for working with developing code. This gives us the tools to manage the package dependencies and requirements in a transparent manner, and impact of dependency changes on software behaviour.

The system is currently being designed as microservices implemented in docker containers. If you have docker installed on your system it is probably easiest to use the containers as described below.

Building the Run Environment Using Docker

Docker configuration is the preferred way to deploy the application. The process of building the docker images and container are outlined below:

Step 1: Delete all containers

$ docker rm $(docker stop $(docker ps -aq))

Step 2: Delete all images

$ docker rmi $(docker images --filter "dangling=true" -q)

Step 3: Build the docker image

$ docker build -t siraimg . --build-arg CACHE_DATE="$(date)"

Required Directory Structure

To set up a scenario or impact simulation project, SIRA expects the following directory structure:

    scenario_dir/
    └── model_x
        │
        ├── input
        │   ├── config_assetx.json
        │   └── model_assetx.json
        └── output
            ├── ...
            └── ...

Explanation of the required structure is as follows:

  • 'scenario directory' - it can be named anything

  • within the scenario directory, there must exist a uniquely named 'model directory' for each scenario or run event.

  • within the 'model directory', the 'input' dir must have two files, in specified format:

  • a model file: it must have the term 'model' at the beginning or end of the file name

  • a config file: it must have the term 'config' at the beginning or end of the file name

  • the outputs are saved in the 'output' dir. If it does not exist, the code will create it at the beginning of the simulation.

Running the Application

The application can be run in a number of modes. The relevant options are:

-d <path_to_input_dir>, --input_directory <path_to_input_dir>
-s, --simulation
-f, --fit
-l, --loss_analysis

The following code snippets assume that it is being run from the root directory of the SIRA code, and the model of interest is in the location sira/scenario_dir/ci_model_x.

The following code runs the simulation and the post processing simultanrously:

$ python sira -d scenario_dir/ci_model_x -sfl

To run only the monte carlo simulation without post-processing:

$ python sira -d scenario_dir/ci_model_x -s

To run for both the model fitting and the loss analysis code:

$ python sira -d scenario_dir/ci_model_x -fl

Note that the fitting and loss analysis steps require the initial simulation to have been run first so that it has the initial output data to perform the analysis on.

Option #1: Run a simulation and destroy the container when done

The following command simulataneously does the following: bind mounts a volume in docker, creates a container in interactive mode, runs a simulation, then destroys the container after simulation ends.

$ docker run -it --rm -v /abs/local/path/<scenario_dir>:/<scenario_dir> \
  siraimg:latest \
  python sira -d <scenario_dir> -sfl --aws

Option #2: Build a container for reuse / experimentation

First, build a docker container from the prebuilt image.

$ docker create --name=sira_x -it siraimg:latest

Then start and attach the container:

$ docker start sira_x
$ docker attach sira_x

It is possible to combine the above steps in one:

$ docker start -a -i sira_x

Run the sira code for the scenario in the specified directory:

$ python sira -d /path/to/scenario_dir -sfl

The process for accessing the required data for simulation from within docker are discussed in the following sections.

Copy data into the container

From outside of docker, on a terminal, use the following command to copy the project folder from container to host:

$ docker cp $(docker ps -alq):/from/path/in/container /to/path/in/host/

This keeps all data and code contained within the single container. But it has the disadvantage that the data is not persistent — if we delete the container, we also lose the data and outputs.

Bind a local directory to a path in Docker container

When setting up to run a docker container, it might be useful to bind a local directory on the host (source) to a directory on the container (destination or target). This allows us to access data on the specified location on the local drive, and write outputs there, from within the container. The generic command to achieve this is:

$ docker run -it \
  --name=docker_container_name \
  --mount source=/path/in/local/host/,\
  destination=/path/in/container,type=bind docker_image_name:latest

A specific example might look like the following: $ docker run -it \ --name=sira_x \ --mount source=/Users/x/code/models/,\ destination=/models,type=bind sira_img:latest

This process maintains the separation of code and data. And data persistence is maintained — we can build and delete a container without affecting the data.

Testing

To run the tests, user needs to be in the root directory of the code, e.g. ~/code/sira. You can use pytest to run the tests, including coverage report:

$ pytest --cov-report term --cov=sira tests/

Alternately, you can just run unittest. This provides more verbose reporting on the tests being run, and where issues are being encountered.

$ python -m unittest discover tests

If you are using docker as described above, you can do this from within the sira container.

Todo

  • While the simulation has been integrated with the json serialisation/deserialisation logic, the redundant classes should be removed and the capacity to create, edit and delete a scenario needs to be developed.

  • The handling of types within the web API is inconsistent; in some cases it works with instances, in others dicts and in others, JSON docs. This inconsistency goes beyond just the web API and makes everything harder to get. One of the main reasons for this is the late addtion of 'attributes'. These are meant to provide metadata about instances and I did not have a clear feel for whether they should be part of the instance or just associated with it. I went for the latter, which I think is the right choice, but did not have the time to make the API consistent throughout.

  • Consider whether a framework like Redux would be useful.

  • Perhaps get rid of ng_select. I started with this before realising how easy simple HTML selects would be to work with and before reading about reactive forms (I’m not sure how/if one could use ng_select with them). One benefit of ng_select may be handling large lists and one may want to do some testing before removing it.