3 Simulation and Model Setup¶

The simulation setup requires two different sets of inputs. These two sets of input data are contained in two separate files:

The config file: this file sets up the simulation scenario parameters
The model file: this defines the components, their connections, along with the fragility, loss, and recovery parameters for the infrastructure model.

These files, their parameters, data layout, and sample input data are presented in the remainder of this Section.

Naming Requirement of Input File: The model file name must begin or end with the term ‘model’. Similarly, the config file must have the term ‘config’ at the beginning or end of its name.

Location Requirement for Input Files: The input files must reside within a directory named input. The parent directory is named after the infrastructure asset by convention, but it can have any name allowed by the local file system. This dir can be located in any storage location where the user has access. The code is informed of the location with a flag -d at execution time.

The outputs generated from the simulation are stored in a directory called output within the same parent directory.

For illustration purposed we assume a hypothetical project “PROJECT HAN”, with the project folder located in the root directory. We also assume that within the project, we are modelling two systems named GISKARD and DANEEL. For this given setup, input-output dir structure for the project will be as follows:

.
└── <PROJECT_HAN>
    ├── <SYSTEM_GISKARD>
    │   ├── input
    │   │   ├── config_system_GR.json
    │   │   └── model_system_GR.json
    │   └── output
    │       ├── ...
    │       ├── ...
    │       └── ...
    │
    └── <SYSTEM_DANEEL>
        ├── input
        │   ├── config_system_DO.json
        │   └── model_system_DO.json
        │
        └── output
            ├── ...
            ├── ...
            └── ...

3.1 Simulation Setup File¶

The code needs a setup file for configuring the simulation scenario. The expected file format is JSON. The code can support any of three formats: ini, conf, or json, though formats other than JSON are discouraged and details of their implementation will not be discussed here.

The following table lists the parameters in the config file, with a brief description and representative values.

SCENARIO_PARAMS

SCENARIO_NAME

Description: Name for identifying simulation scenario
Data Type: String
Example: ‘Coal-fired Generation Plant 600W’

INTENSITY_MEASURE_PARAM

Description: Engineering Demand Parameter
Data Type: String
Example: ‘PGA’

INTENSITY_MEASURE_UNIT

Description: Demand Parameter Unit
Data Type: String
Example: ‘g’

HAZARD_PARAMS

HAZARD_INPUT_METHOD

Description: How the hazard is supplied. Must be one of two options: ‘calculated_array’ or ‘hazard_file’
Data Type: String
Example: ‘calculated_array’

HAZARD_TYPE

Description: The type of hazard for the impact simulation.
Data Type: String
Example: ‘earthquake’
Valid values: [‘earthquake’, ‘tropical cyclone’, ‘flood’]

INTENSITY_MEASURE_MIN

Description: Minimum value for internsity measurement (IM) parameter
Data Type: Float
Example: 0.0

INTENSITY_MEASURE_MAX

Description: Maximum value for internsity measurement (IM) parameter
Data Type: Float
Example: 1.5

INTENSITY_MEASURE_STEP

Description: Step size for incrementing the IM param
Data Type: Float
Example: 0.01

NUM_SAMPLES

Description: Iterations for Monte Carlo process
Data Type: Integer
Example: 500

FOCAL_HAZARD_SCENARIOS

Description: The value(s) or scenario(s) at which to undertake detailed assessment of system response
Data Type: List of strings
Example: [0.50, 0.55]

RESTORATION_PARAMS

TIME_UNIT

Description: Unit of time for restoration time calculations
Data Type: String
Example: ‘week’

RESTORE_PCT_CHKPOINTS

Description: Number of steps to assess functionality
Data Type: Integer
Example: 21

RESTORE_TIME_STEP

Description: Time increment for restoration period
Data Type: Integer
Example: 1

RESTORE_TIME_MAX

Description: Maximum value for restoration period assessment
Data Type: Integer
Example: 300

RESTORATION_STREAMS

Description: The number of simultaneous components to work on
Data Type: List of integers
Example: [5, 10, 20]

SYSTEM_METADATA

INFRASTRUCTURE_LEVEL

Description: Define infrastructure as a facility or network
Data Type: String
Example: facility

SYSTEM_CLASSES

Description: The allowed infrastructure system types
Data Type: List of strings
Example: [‘PowerStation’, ‘Substation’]

SYSTEM_CLASS

Description: The infrastructure system type to be modelled
Data Type: String
Example: ‘PowerStation’

SYSTEM_SUBCLASS

Description: Sub-category of system
Data Type: String
Example: ‘Coal Fired’

COMMODITY_FLOW_TYPES

Description: Number of input commodity types
Data Type: Integer
Example: 2

SYS_CONF_FILE_NAME

Description: File name for system config and fragility info
Data Type: String
Example: ‘sys_config_ps.xlsx’

SWITCHES

FIT_PE_DATA

Description: Flag for fitting Prob of Exceedance data
Data Type: Boolean
Example: True

FIT_RESTORATION_DATA

Description: Fit model to simulated restoration data
Data Type: Boolean
Example: True

SAVE_VARS_NPY

Description: Switch to indicate whether to save simulated values in binary numpy format
Data Type: Boolean
Example: True

MULTIPROCESS

Description: Switch to indicate whether to use multi-core processing. 0 \(\rightarrow\) False, 1 \(\rightarrow\) True
Data Type: Integer
Example: 1

RUN_CONTEXT

Description: Switch to indicate whether to run a full simulation, or run test code. 0 \(\rightarrow\) run tests, 1 \(\rightarrow\) normal run.
Data Type: Integer
Example: 1

3.2 Infrastructure Model Definition File¶

The system model is presently built using an MS Excel spreadsheet file. It contains seven required worksheets, each representing modules that define different aspect of the infrastructure model. The names of the worksheets are fixed. The Excel file must be converted to JSON format before it can be ingested by SIRA. There are scripts provided in the ‘scripts’ directory for this purpose.

The format and function of the worksheets (i.e. model definition modules) are described in the following subsections:

3.2.1 Basic System Metadata: system_meta¶

This module of the model defines core metadata relevant to the simulation of a given infrastructure model. There is a free text ‘notes’ field for each of the parameters. Users are encouraged to provide detailed information that may be relevant to the model configuration and post-simulation validation of results.

INFRASTRUCTURE_LEVEL

Description: The scope of the infrastructure system.
Values: Valid values are ‘facility’ or ‘network’

SYSTEM_CLASS

Description

The name of the asset class. It must have a corresponding class definition in the module sira.modelling.infrastructure.

Values

The current set of valid system classes are as outlined in this list:

[‘PowerStation’, ‘Substation’, ‘PotableWaterTreatmentPlant’, ‘PWTP’, ‘WasteWaterTreatmentPlant’, ‘WWTP’, ‘PotableWaterPumpStation’]

SYSTEM_SUBCLASS

Description: The subclass of the parent infrastructure system as specified in SYSTEM_CLASS. For example, for the SYSTEM_CLASS ‘Substation’, the logical system_subclass options can be ‘transmission’, ‘distribution’, ‘collector’, etc.
Values: Presently this is not implemented in code, but used for informational purposes and for compatibility with planned future functionality expansion.

SYSTEM_COMPONENT_LOCATION_CONF

Description

Specifies whether the location information for system components are specified in component list definition.

A value of ‘undefined’ indicates that the location information for the components is not relevant to its vulnerability analysis, AND the graph-drawing methods are not constrained in placement of the components in the system topology diagram.

A value of ‘defined’ indicates that the location information of the components may be relevant to the vulnerability analysis process, AND the graph-drawing methods should respect the provided positional data in placement of the components in the system topology diagram.

Values

Valid values must match: [‘defined’, ‘undefined’]. If INFRASTRUCTURE_LEVEL==’network’, then the value must be defined.

RESTORATION_TIME_UNIT

Description: The unit of time used for defining the component restoration algorithms.
Values: [‘days’, ‘weeks’, ‘months’, ‘years’]

3.2.2 List of Components: component_list¶

The component_list has the following parameters:

model_params__component_list

component_id

Description: Unique id for a component in the system. This is an instance of component_type.
Data Type: String. It is recommended to use alphanumeric characters, starting with a letter, and logically distinct parts of the name separated by underscores.
Example: ‘transformer_tx1’

component_type

Description: The typology of a system component. Represents a general category of equipment.
Data Type: String. It is recommended to use alphanumeric characters, starting with a letter, and logically distinct parts of the name separated by spaces.
Example: ‘Stepup Transformer’

component_class

Description: Represent a broad category of equipment performing a general task. A number of component types can be grouped under this, e.g. ‘Power Transformer 100MVA 230/69’ and ‘Power Transformer 50MVA 230/69’ are both under the same component_class of ‘Power Transformer’.
Data Type: String. It is recommended to use alphanumeric characters, starting with a letter, and logically distinct parts of the name separated by spaces.
Example: ‘Emission Management’ – stacks and ash disposal systems belong to different typologies, but both contribute to the function of emission management.

cost_fraction

Description: Normalised value of an instance of a component given as as a fraction of the total system cost, wih the total system cost being 1.0.
Data Type: Float. \({\{x \in \mathbb{R} \mid 0 \le x \le 1\}}\)
Example: 0.03

node_type

Description: This indicates the role of the node (component) within network representing the system. For details, see Classification of Nodes.
Data Type: String. Must be one of these four values in the set: (‘supply’, ‘transshipment’, ‘dependency’, ‘sink’)
Example: ‘supply’

node_cluster

Description: This is an optional parameter to assist is drawing the system diagram. It indicates how the different components should be grouped together.
Data Type: String
Example: ‘Boiler System’

operating_capacity

Description: Operational capacity of the component. One (1.0) indicates full functionality, and zero (0.0) indicates complete loss of functionality. Typically at the start of the simulation all components will have a value of 1.0.
Data Type: Float. \({\{x \in \mathbb{R} \mid 0 \leq x \leq 1\}}\)
Example: 1.0 (default value)

pos_x

Description: The x-position or longitude value of the component.
Data Type: Float.

pos_y

Description: The y-position or latitude value of the component.
Data Type: Float.

3.2.3 Connections between Components: component_connections¶

origin

Description

The node (component) to which the tail of a directional edge is connected.

For bidirectional connections, two edges must be defined within opposing directionality, e.g. A \(\rightarrow\) B, and B \(\rightarrow\) A. For undirected graphs the origin/destination designation is immaterial.

Data Type

String. Must be one of the entries in the list of components defined under component_id in the module component_list.

Example

‘stack_1’

destination

Description: The node (component) on which the head of a directional edge terminates. For undirected graphs the origin/destination designation is immaterial.
Data Type: String. Must be one of the entries in the list of components defined under component_id in the module component_list.
Example: ‘turbine_condenser_1’

link_capacity

Description: Capacity of the edge. Its value can be more than the required flow of 1.0, which would represent excess capacity on the line.
Data Type: Float. \({\{x \in \mathbb{R}\ \mid \ 0 \leq x \leq 1\}}\)
Example: 1.0 (default value)

weight

Description: This parameter can be used to prioritise an edge or a series of edges (a path) over another edge or set of edges. This is intended to set preference for a particular path where path redundancies exist.
Data Type: Integer
Example: 1 (default value)

3.2.4 Configuration of Supply Nodes: supply_setup¶

input_node

Description: The component_id of the input node.
Data Type: String. Must be one of the entries in the component_id columns in the component_list table, and its node_type must be supply.
Example: ‘coal_supply’

input_capacity

Description: The operational capacity of the node. It can be a real value if known, or be given as a fraction of total normalised value of 100%.
Data Type: Float. \({\{x \in \mathbb{R} \mid 0.0 \lt x \leq 100.0\}}\)
Example: 100.0 (default value)

capacity_fraction

Description: The normalised value of the total required input commodity entering the system the given input node. The total quantity of required material is normalised to 1.0.
Data Type: Float. \({\{x \in \mathbb{R} \mid 0.0 \lt x \leq 1.0\}}\)
Example: 1.0

commodity_type

Description

The type of commodity entering into the system through the specified input node.

Data Type

String.

Example

A thermal power station will have two primary input commodities: fuel (for example coal) and water. So, for a coal-fired power station, there will need to be two input nodes defined (at a minumum), with the two types of commodity_type being ‘coal’ and ‘water’.

For an electric substation the commodity_type is electricity. For a water treatment plant, it will be untreated water.

3.2.5 Configuration of Output Nodes: output_setup¶

output_node

Description

These are the ‘sink’ nodes representing the load or the aggregate consumer of the product(s) of the system.

These are not real components, but a modelling construct. These nodes are not considered in the fragility calculations.

Data Type

String. Must be one of the entries in the list of components defined under component_id in the module component_list, and must be of node_type sink.

Example

‘output_1’

production_node

Description: These are the real terminal nodes within the infrastructure system model. The completed product or output of a system exits the system boundary through this node.
Data Type: String. Must be one of the entries in the list of components defined under component_id in the module component_list, and must be of node_type transshipment.
Example: ‘gen_1’

output_node_capacity

Description

The part of total production capacity of the system that a specific production node is responsible for.

The unit depends on the type of product the system produces (e.g. MW for generator plant). The unit is defined as part of the system metadata.

Data Type

Float

Example

300

capacity_fraction

Description: The fraction of total production capacity of the output nodes. The sum of capacities of all nodes must equal 1.0.
Data Type: Float \({\{x \in \mathbb{R} \mid 0 < x \leq 1\}}\)
Example: 0.5

priority

Description: This parameter is used to assign relative sequential priority for output nodes for the purposes of post-disaster recovery prioritisation.
Data Type: Integer. \({\{x \in \mathbb{Z} \mid 1 \leq x \leq n\}}\), where \({n}\) is the total number of output nodes
Example: NA

3.2.6 Component Type Damage Algorithms: comp_type_dmg_algo¶

id

Description: A sequential integer value assigned to each algorithm. It is used solely for internal programming logic.
Data Type: Integer

component_type

Description

The type of component, based on the typology definitions being used in the system model.

Example: ‘Demineralisation Plant’

Data Type

Alphanumeric characters. May use dashes ‘-‘ or underscores ‘_’. Avoid using special characters.

damage_state

Description

The list of discrete damage states used in defining the damage scale being modelled within the system. The ‘None’ damage state is not explicitly listed.

Example: For a four-state sequential damage scale, the following damage states are used:

DS1 Slight
DS2 Moderate
DS3 Extensive
DS4 Complete

Data Type

String. Fixed, pre-determined state names.

is_piecewise

Description: Flag that states whether the function is piecewise defined, or defined by a single function.
Data Type: String [‘yes’, ‘no’]

damage_function

Description

Name of the probability distribution representing the damage function. This should be a Cumulative Distribution Function (CDF).

Log-normal curves are predominant in this discipline. However, any function can be supported by adding its definition to the module sira.modelling.responsemodels.

Example: ‘lognormal’

Data Type

String. MUST match name of a function defined in sira.modelling.responsemodels.

median

Description

Median of the damage function. This corresponds to the ‘scale’ parameter of the lognormal implementation in scipy.

For scipy lognormal implementation, \(\text{scale} = \text{median} = \mathrm{e}^{\mu}\), where μ is the mean of the log of the samples.

A median will need to be defined for each damage state. It should typically be progressively higher for more severe damage states:

\({\mu_{DS1} \leq \mu_{DS2} \leq \mu_{DS3} \leq \mu_{DS4}}\)

Data Type

Float.

beta

Description

The log-standard deviation, or put another way, the standard deviation of the log of the variate. This corresponds to the ‘shape’ parameter of the lognormal implementation in scipy.

It will need to be defined for each damage state. The value of beta should be such that the curves for the defined damaged states do not overlap.

Data Type

Float.

location

Description: The location parameter for lognormal function, as implemented in scipy. In scipy it is used primarily for the purpose of having a common method for defining all functions. In practice, we always set it to zero.
Data Type: Float.

damage_ratio

Description

The fractional loss of a component’s value resulting from incurred damages resulting it being in a given damage state. This parameter links a damage state to expected direct loss, expressed as a fraction of total component value.

Example: Damage ratio of 0.30 for damage state “DS2 Moderate”

Data Type

Float. \({\{x \in \mathbb{R} \mid 0.0 \leq x\}}\). A value of 0 indicates no loss of value, and a value of 1.0 indicates complete loss. In special cases the the value of loss ratio can be greater than 1.0, which indicates complete loss of component and additional cost of removal, disposal, or securing of destroyed component.

functionality

Description

An unitless normalised value indicating the functional capacity of a component for a given damage state. This parameter links a damage state to expected post-impact residual functionality (or production capacity) of the component.

Example: A stack of a thermal power station may be expected to remain fully functional (functionality==1), under ‘Slight’ damage state, e.g. under conditions of minor damage to structure with deformation of holding down bolts and with some bracing connections.

Data Type

Float. \({\{x \in \mathbb{R} \mid 0.0 \leq x \leq 1.0\}}\).

A value of 0 indicates no loss of value, and a value of 1.0 indicates complete loss. In special cases the the value of loss ratio can be greater than 1.0, which indicates complete loss of component and additional cost of removal, disposal, or securing or destroyed component.

minimum

Description

Minimum value for which the damage algorithm is applicable.

Example: The algorithms presented by Anagnos [1] for 500kV circuit breakers are only applicable for PGA values of 0.15g and above, for the various noted failure modes.

Data Type

Float.

upper_limit

Description: The maximum value of hazard intensity for which the given algorithm may be applicable.
Data Type: Float. If upper limit is not explicity defined for an algorithm, use ‘NA’.

lower_limit

Description: The minimum value of hazard intensity for which the given algorithm may be applicable.
Data Type: Float. If upper limit is not explicity defined for an algorithm, use ‘NA’.

recovery_function

Description

Name of the probability distribution representing the damage function.

Normal CDF, traingular function or a uniform distribution function are commmon examples for recovery functions. However, any function can be supported by adding its definition to the module sira.modelling.responsemodels.

Example: ‘Normal’

Data Type

String. MUST match name of a function defined in sira.modelling.responsemodels.

recovery_param1

Description: The first param of the recovery function. This is the ‘location’ paramter. For a Normal distribution, it is the mean of the distribution.
Data Type: Float.

recovery_param2

Description: The second param of the recovery function. This is the ‘scale’ paramter. For a Normal distribution, it is the standard deviation of the distribution.
Data Type: Float.

recovery_95percentile

Description: [Optional paramter] In the process of expert elicitation of recovery parameters, it is often difficult to get the concept of standard deviation across to an audience of experts unpracticed in statistical concepts. In such cases it is easier to obtain a 95th percentile value for recovery time, and translate that to standard deviation for a normal distribution using the following equation:

\[\begin{split}\begin{align} &X_{0.95} = \mu + Z_{0.95} \sigma \\ \Rightarrow &X_{0.95} = \mu + \Phi^{-1}(0.95) \sigma \\ \Rightarrow &\sigma = \frac{X_{0.95} - \mu}{\Phi^{-1}(0.95)} \end{align}\end{split}\]
Data Type: Float

fragility_source

Description: Source or reference from which the fragility algorithm was taken or adapted, how it was adapted, or how it was developed.
Data Type: Free text

3.2.7 Definition of Damage States: damage_state_def¶

This table documents the physical damage characteristics that are implied by the damage states used to model the fragility of the system components.

component_type

The entries here are the same as noted under component_type in the ‘Component Type Damage Algorithms’ table.

damage_state

The entries here are the same as noted under damage_state in the ‘Component Type Damage Algorithms’ table.

damage_state_definitions

Description

The physical damage descriptors corresponding to the damage states.

Example: A circuit breaker can be considered to be in an ‘Exensive’ damage state for the following damage definition: “Cracking of interrupter casing. Interrupter head falling off in some instances. In other instances damage to conductor connections.”

Data Type

Free text.