Skip to content

Commit 7cca007

Browse files
committed
documentation update
1 parent 48ba53a commit 7cca007

7 files changed

Lines changed: 132 additions & 91 deletions

File tree

docs/source/_static/css/custom.css

Lines changed: 29 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,33 @@
33
Sphinx theme customisation
44
-------------------------------
55
*/
6+
@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,100;0,300;0,400;0,700;0,900;1,100;1,300;1,400;1,700;1,900&display=swap');
67
@import url('https://fonts.googleapis.com/css?family=Roboto');
7-
@import url('https://fonts.googleapis.com/css?family=Fira+Code');
8-
@import url('https://fonts.googleapis.com/css?family=Lora:400');
98

10-
@import url('https://fonts.googleapis.com/css2?family=Arbutus+Slab&display=swap');
9+
@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500&display=swap');
10+
11+
@import url('https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,400..700;1,400..700&display=swap');
1112
@import url('https://fonts.googleapis.com/css2?family=Roboto+Slab:wght@100..900&display=swap');
12-
@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,100;0,300;0,400;0,700;0,900;1,100;1,300;1,400;1,700;1,900&display=swap');
13+
@import url('https://fonts.googleapis.com/css2?family=Arbutus+Slab&display=swap');
14+
15+
/*
16+
@import url('https://fonts.googleapis.com/css2?family=Libre+Baskerville:ital,wght@0,400..700;1,400..700&display=swap');
17+
*/
1318

1419
body {
1520
background-color: #edf0f2;
1621
margin: 0;
1722
padding: 0;
18-
font-family: 'Lato', 'Helvetica', sans-serif;
23+
font-family: 'Lato', 'Roboto', 'Helvetica', sans-serif;
1924
font-size: 16px;
2025
color: #333333;
2126
line-height: 1.5;
2227
}
2328

2429
h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
2530
color: #333333;
26-
font-weight: 500;
27-
font-family: 'Roboto Slab', 'Arbutus Slab', 'Lora', serif;
31+
font-weight: 600;
32+
font-family: 'Lora', 'Roboto Slab', 'Arbutus Slab', serif;
2833
line-height: 115%;
2934
}
3035

@@ -59,15 +64,15 @@ h1, h2, h3, h4, h5, h6 {
5964
*/
6065

6166
h1 {
62-
font-size: 39px;
67+
font-size: 38px;
6368
padding: 10px 0px 10px 0px;
6469
margin: 20px 0px 20px 0px;
6570
background-color: none;
6671
width: 100%;
6772
}
6873

6974
h2 {
70-
font-size: 30px;
75+
font-size: 28px;
7176
padding: 10px 5px 10px 0px;
7277
margin: 5px 0 5px 0px;
7378
}
@@ -81,17 +86,17 @@ h3 {
8186
h2:before {
8287
content: ' ';
8388
display: block;
84-
width: 65px;
89+
width: 60px;
8590
padding-top: 25px;
86-
border-top: 9px solid #6d6d6d;
91+
border-top: 8px solid #444444;
8792
}
8893

8994
h3:before {
9095
content: ' ';
9196
display: block;
92-
width: 65px;
97+
width: 67px;
9398
padding-top: 20px;
94-
border-top: 4px solid #797878;
99+
border-top: 4px solid #444444; /* #797878 */
95100
}
96101

97102
.rst-content table.docutils td,
@@ -172,14 +177,14 @@ a:hover {
172177
/* Customise Definition List */
173178
.rst-content dl:not(.docutils) dt {
174179
display: table;
175-
margin: 12px 0 10px 0;
180+
margin: 10px 0 10px 0;
176181
font-size: 95%;
177182
line-height: normal;
178-
background: #e7f2fa;
183+
background: #FFFFFF; /* #e7f2fa */
179184
color: #2980B9;
180-
border-left: solid 4px #6ab0de;
185+
border-left: solid 5px #aaa; /* #79bae6; #6ab0de; */
181186
border-top: none;
182-
padding: 6px;
187+
padding: 1px 4px 2px 8px;
183188
position: relative;
184189
}
185190

@@ -200,7 +205,7 @@ a:hover {
200205

201206
.rst-content dl dt {
202207
font-weight: bold;
203-
margin-bottom: 3px;
208+
margin-bottom: 0.5em;
204209
margin-top: 0.5em;
205210
margin-left: 14px;
206211
}
@@ -213,8 +218,8 @@ a:hover {
213218
.rst-content p.rubric {
214219
margin-bottom: 6px;
215220
margin-top: 20px;
216-
font-weight: bolder;
217-
font-size: 115%;
221+
font-weight: 600;
222+
font-size: 100%;
218223
}
219224

220225
/* Customize admonition directives */
@@ -243,7 +248,7 @@ a:hover {
243248

244249
@font-face {
245250
font-family: "Fira Code";
246-
src: url('source/_static/fonts/FiraCode/FiraCode-VF.ttf') format('truetype');
251+
src: url('../fonts/FiraCode/FiraCode-VF.ttf') format('truetype');
247252
font-weight: normal;
248253
font-style: normal;
249254
}
@@ -252,7 +257,7 @@ a:hover {
252257
font-family: "Fira Code", Consolas, monospace;
253258
font-weight: 500;
254259
font-style: normal;
255-
font-size: 100%;
260+
font-size: 95%;
256261
color: #cf493a; /*#CD0C19;#FF5052;#CC4851;#0070C0;*/
257262
}
258263

@@ -262,7 +267,8 @@ a:hover {
262267
.rst-content div[class^='highlight'] pre,
263268
.rst-content pre.literal-block {
264269
font-family: "Fira Code", Consolas, monospace;
265-
font-variant-ligatures: none; /* Disable ligatures if preferred */
270+
font-size: 85%;
271+
font-variant-ligatures: common-ligatures; /* Enable ligatures */
266272
}
267273

268274
/* override table width restrictions */

docs/source/_static/files/model_params__sim_config_hazard.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
`HAZARD_INPUT_DIR`
5656
:Description: Path for hazard file location
5757
:Data Type: String
58-
:Example: "../_PROJECTX_hazard_portfolio/scenario_files"
58+
:Example: "../PROJECTX_hazard_portfolio/scenario_files"
5959

6060
`HAZARD_INPUT_FILE`
6161
:Description: Name of hazard input file

docs/source/_static/files/refs.bib

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,3 +126,10 @@ @INPROCEEDINGS{Shinozuka-etal-1981
126126
address = "Oakland, CA, USA"
127127
}
128128

129+
@TECHREPORT{INCOSE2020,
130+
author = "International Council on Systems Engineering (INCOSE)",
131+
title = "Systems Engineering Definitions",
132+
institution = "INCOSE",
133+
year = "2020",
134+
url = "https://www.incose.org/wp-content/uploads/legacy/default-document-library/incose-se-definitions-tp-2020-002-06.pdf"
135+
}

docs/source/ch02_concept.rst

Lines changed: 74 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,27 @@ dictionary, is:
2727
"a regularly interacting or interdependent group
2828
of items forming a unified whole."
2929

30-
The International Council on Systems Engineering (INCOSE)
31-
`defines a system thus <https://www.incose.org/about-systems-engineering>`_:
30+
The International Council on Systems Engineering (INCOSE) has the following
31+
`simple definition <https://www.incose.org/about-systems-engineering>`_
32+
for a system on its website:
3233

33-
"A system is a construct or collection of different
34-
elements that together produce results not obtainable
35-
by the elements alone."
34+
"A system is a set of elements that work together to produce
35+
results that the individual elements couldn't achieve alone."
36+
37+
INCOSE also provides a more specific definition of a 'complex system'
38+
that emphasises the non-trivial relationships between cause and effect,
39+
associated its 'emergent' properties :cite:`INCOSE2020`:
40+
41+
"A complex system is a system in which there are non-trivial
42+
relationships between cause and effect: each effect may be due
43+
to multiple causes; each cause may contribute to multiple
44+
effects; causes and effects may be related as feedback loops,
45+
both positive and negative; and cause-effect chains are cyclic
46+
and highly entangled rather than linear and separable."
47+
48+
This definition of a complex system is particularly relevant to the SIRA modelling framework, as it captures the essence of the interdependencies and interactions that characterise infrastructure systems. The SIRA simulation approach is designed to account for these complexities and provide insights
49+
into how disruptions from hazards can lead to potentially unpredictable behaviours and propagate through the system, affecting its overall
50+
functionality.
3651

3752
The specific meaning of a system and its boundaries depend on the context,
3853
and it is important to understand how this term is used within the SIRA
@@ -42,56 +57,65 @@ The central idea in the SIRA modelling construct is this:
4257
All lifeline infrastructure 'systems' within the modelling framework are
4358
conceptualised as a network of interconnected nodes.
4459

45-
The 'nodes' or vertices and connecting edges have different meaning based
46-
on the level of abstraction, which is clarified in following subsections.
60+
The nodes or vertices, and connecting edges, have different meaning based
61+
on the level of abstraction, which is explained in following subsections.
4762

48-
This modelling approach affords a very high degree of flexibility and
49-
scalability, making it possible accommodate diverse sectors and assets
50-
of varying scales and complexities.
63+
This modelling approach affords a high degree of flexibility and
64+
scalability, making it possible to accommodate multiple sectors and assets
65+
of varying scale and complexity.
5166

5267
Furthermore, it allows the user to:
5368

54-
(a) model the effect of impaired or destroyed components on the
69+
(a) model the effect of impaired or destroyed components on the
5570
operational capacity of the overall system;
5671

57-
(b) use graph theory to assess the graduated capacity degradation, and
72+
(b) use graph theory to assess the graduated capacity degradation, and
5873
restoration, through modelling flow through the network; and
5974

60-
(c) detect prioritised 'paths', or sets of components, within network
61-
that need to be repaired or restored in order to restore the flow through
62-
the network which represents the productive capacity of the system.
75+
(c) detect prioritised 'paths', or sets of connected components, within
76+
the network that need to be repaired or recovered in order to restore
77+
the flow through the network which represents the productive capacity
78+
of the system.
79+
6380

64-
Terminology in Context: An Infrastructure System
65-
------------------------------------------------
81+
Infrastructure System Hierarchy
82+
-------------------------------
6683

67-
The elements in an infrastructure (or lifeline) system are conceptualised
84+
The elements in an infrastructure (or lifeline) system can be conceptualised
6885
as being structured in a three-level hierarchy:
6986

7087
**Level 1 : Infrastructure Network --** This is the top level of
7188
interconnected infrastructure systems where infrastructure facilities are
72-
connected to form a network or networks.
89+
connected to form a network or connect to other networks.
7390

74-
**Level 2 : Infrastructure Facility --** The concept of facilities used in this
75-
framework map closely to the typology of macro-components as defined in the
76-
Synerg-G program :cite:`SynerG2010,Pitilakis-etal-2014`, and align with the
77-
definition systems as defined in :cite:`Rinaldi-etal-2001`.
78-
79-
**Level 3 : Infrastructure Microcomponent --** This concept of components map
80-
closely to the typology of micro-components as defined in the Synerg-G program
91+
**Level 2 : Infrastructure Facility --** Facilities are geospatially discrete
92+
assets that can be linked to a specific physical location and provide a
93+
specific service, e.g. a power station or a substation.
94+
The concept of facilities used in this framework map closely to the typology
95+
of macro-components as defined in the Synerg-G program
8196
:cite:`SynerG2010,Pitilakis-etal-2014`, and align with the definition of
82-
subsystems as defined in :cite:`Rinaldi-etal-2001`.
97+
systems as defined in :cite:`Rinaldi-etal-2001`.
98+
99+
**Level 3 : Infrastructure Microcomponent --** These are the physical elements
100+
that constitute the infrastructure facility, e.g. a transformer or circuit
101+
breaker within an electrical substation.
102+
This concept of components map closely to the typology of micro-components as
103+
defined in the Synerg-G program :cite:`SynerG2010,Pitilakis-etal-2014`, and
104+
align with the definition of subsystems as defined in :cite:`Rinaldi-etal-2001`.
83105

84-
This applies to discussions on a *complete* that is responsible for
106+
This applies to discussions on a complete system that is responsible for
85107
delivering some service. This also applies to classification of assets,
86-
and how information about those assets they are stored and referenced
108+
and how information about those assets are stored and referenced
87109
in a database.
88110

89-
Terminology in Context: A Model of a Lifeline Infrastructure
90-
------------------------------------------------------------
91111

92-
In the context of a specific infrastructure model developed for hazard
93-
impact assessment, the following terms and ideas apply (and are implemented
94-
in the simulation code).
112+
Structure of a SIRA Model of a Lifeline Infrastructure
113+
------------------------------------------------------
114+
115+
In the context of a specific infrastructure model, developed for hazard
116+
impact assessment, the following terms and ideas apply. These are the
117+
building blocks of of SIRA model and map to the objects implemented in
118+
the simulation code.
95119

96120
**The System Model:** This defines a logical set of assets that is an
97121
abstraction of a real equivalent asset. The usage of the term system in this
@@ -104,21 +128,22 @@ to a network or a facility. The context of the simulation will
104128
disambiguate its meaning.
105129

106130
**Component:** It is the high-level element within the network (or graph) that
107-
represents the **System Model**. A collection of interconnected
131+
represents the *System Model*. A collection of interconnected
108132
components with specific attributes and roles comprise the System
109133
in the context of the simulation model.
110134

111135
The asset being studied will determine what is considered a system or what
112136
is considered a component within the context of the simulation.
113137

114-
**If the system under study is a NETWORK**, then the System Model is a
115-
Level 1 element, i.e. an *Infrastructure Network*, and the Components are
138+
**If the physical system under study is a NETWORK**, then the System Model is
139+
a Level 1 element, i.e. an *Infrastructure Network*, and the Components are
116140
Level 2 elements, i.e. *Infrastructure Facilities*.
117141

118-
**If the system under study is a FACILITY**, then the System Model is a
119-
Level 2 element, i.e. an *Infrastructure Facility*, and the Components are
142+
**If the physical system under study is a FACILITY**, then the System Model is
143+
a Level 2 element, i.e. an *Infrastructure Facility*, and the Components are
120144
Level 3 elements, i.e. *Infrastructure Microcomponents*.
121145

146+
122147
.. _model-node-classification:
123148

124149
Classification of Nodes within a Model of an Infrastructure System
@@ -131,7 +156,7 @@ four categories:
131156

132157
1. **Supply nodes**: These nodes represent the entry points into the system
133158
for required inputs or commodities. As for example, coal and water can
134-
be the required commodities into a thermal power station. In the case
159+
be the required 'commodities' into a thermal power station. In the case
135160
of the substation, required input is electricity from power stations or
136161
other substations.
137162

@@ -154,13 +179,14 @@ four categories:
154179

155180
4. **Transhipment nodes**: These are nodes that transform, transport, or
156181
store system inputs to give effect to processes that produces the outputs
157-
required of the system. Majority of the nodes within a system fall into
182+
required of the system. Majority of the nodes within a system fall into
158183
this category.
159184

160185
The component configuration and redundancies are captured as edges connecting
161-
the nodes. Constraints on flow through specific paths, or sets of nodes, can
162-
be represented as capacities of edges connecting those nodes. Figure 2.1
163-
illustrates this concept for a thermal power station.
186+
the nodes. Constraints on flow through specific paths, or sets of nodes, can
187+
be represented as capacities of edges connecting those nodes.
188+
:numref:`pwrstn_schematic_diagram` illustrates this concept for
189+
a thermal power station.
164190

165191
.. _pwrstn_schematic_diagram:
166192

@@ -186,13 +212,13 @@ Connection paths and 'production capacities' along those paths within a
186212
system are calculated as the maximum flow through those paths.
187213
The `igraph <http://igraph.org/python/>`_ Python package was used as the
188214
network modelling platform to calculate graph metrics for a post-hazard
189-
damaged system model.
215+
damaged system model.
190216

191217

192218
System Loss Modelling
193219
=====================
194220

195-
For a given value of level of ground shaking, a set of random samples is
221+
For a given level of ground shaking, a set of random samples is
196222
generated, and the damage state of each component is calculated for each
197223
random sample based on the fragility function of the given component.
198224
Given the assessed damage state of all the system components, the system
@@ -201,7 +227,7 @@ is run through a Monte Carlo process for the set of random samples to
201227
assess the system response at the selected ground shaking intensity. To
202228
obtain a characterisation of the system and develop fragility algorithms
203229
for the system (e.g. the power station) the process is repeated for a
204-
range of PGA values. This Process is shown in Figure 2.2.
230+
range of PGA values. This Process is shown in :numref:`fig_hazard_loss_link`.
205231

206232
.. _fig_hazard_loss_link:
207233

@@ -337,7 +363,7 @@ high priority line. This exercise may allow the operator to eliminate
337363
the potentially long procurement or transportation time for a replacement
338364
unit, and thereby expedite the restoration of the high priority lines.
339365

340-
The outputs from the restoration model are:
366+
The outputs from the restoration model are:
341367

342368
1) a simple Gantt chart with each component needing repair,
343369

0 commit comments

Comments
 (0)