4 Infrastructure Model Setup
The system model is defined 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. The required script convert_excel_files_to_json.py is available in the sira/tools directory for this purpose.
The format and function of the worksheets (i.e. model definition modules) are described in the following subsections:
4.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’]
4.2 List of Components: component_list
The component_list has the following parameters:
- 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.
- site_id
- Description:
The ID for the hazard location matched to the component. This value must match one of the values in the hazard definition file under the column of the same header. A negative value indicates that the related component serves as a modelling artefact and not included hazard impact simulation.
- Data Type:
Int.
4.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)
4.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:
‘water_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.
4.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
4.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. Must match set of 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 [2] 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_99pct
- 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.99} = \mu + Z_{0.99} \sigma \\ \Rightarrow &X_{0.99} = \mu + \Phi^{-1}(0.99) \sigma \\ \Rightarrow &\sigma = \frac{X_{0.99} - \mu}{\Phi^{-1}(0.99)} \end{align}\end{split}\]- Data Type:
Float
- data_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
4.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
- Description:
The type of component, based on the typology definitions being used in the system model. The entries here are the same as noted under component_type in the ‘Component Type Damage Algorithms’ table.
- Data Type:
Alphanumeric 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. The entries here are the same as noted under damage_state in the ‘Component Type Damage Algorithms’ table.
- Data Type:
String. Must match set of pre-determined state names.
- 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.