Merge branch 'main' of https://github.com/parduino/CESG599_NHERI.docu…

…mentation into main

source/case_5.rst

@@ -15,120 +15,92 @@ This page describes basic concepts of geospatial liquefaction hazard modeling.
 Problem Description
 -------------------
 
-Coseismic soil liquefaction is a phenomenon in which the strength and stiffness of a soil is reduced by earthquake shaking. Resilient communities and infrastructure networks, like lifelines or transportation systems, must be built to withstand and respond to hazards posed by coseismic soil liquefaction. Ideally, these predictions could be made quickly, in near-real-time after an event; at high resolution, consistent with the scale of individual assets; and at map-scale, across the regional extent affected by large earthquakes. Common liquefaction models in practice require in-situ testing which cannot be continuously performed across large areas, thus presenting the need for “geospatial” liquefaction models. Prior tests of such models (e.g., [Zhu2017]) have shown both promising potential and severe shortcomings in predicting subsurface conditions with few geospatial predictors[5]. There is a need to advance geospatial liquefaction modeling, integrating geotechnical data, liquefaction mechanics, artificial intelligence (AI), and many geospatial predictor variables to provide reliable, scalable liquefaction predictions for any earthquake event.
+Coseismic soil liquefaction is a phenomenon in which the strength and stiffness of a soil is reduced by earthquake shaking. Resilient communities and infrastructure networks, like lifelines or transportation systems, must be built to withstand and respond to hazards posed by coseismic soil liquefaction. Ideally, these predictions could be made:
 
+* quickly, in near-real-time after an event; 
 
-Solution Strategy
------------------
-
-#. Open the Dr. Layer program. By default we get twelve layers. The top six layers are hardwired into the system with a velocity of specified as very fast. The bottom six layers are hardwired with a velocity of very slow.
-
-#. Select all the layers to all have very slow values using the select all option.
-
-#. On the top left hand corner of the menu box choose the plot box tool and apply a plot box at the top of the layers. Do the same at four arbitrary points along the soil layers. Note the height (:math:`H`) you place the plots.
+* at high resolution, consistent with the scale of individual assets; and 
 
-    <insert image>
+* at map-scale, across the regional extent affected by large earthquakes. 
 
-#. Push the time increment button for about 1 minute.
 
-#. Obtain the angular frequency :math:`(2p/T)`, where :math:`T` is the period i.e. time it takes to complete one revolution.
+Common liquefaction models in practice require in-situ testing which cannot be continuously performed across large areas, thus presenting the need for “geospatial” liquefaction models. Prior tests of such models (e.g., :cite:`Zhu2017`) have shown both promising potential and severe shortcomings in predicting subsurface conditions with few geospatial predictors. There is a need to advance geospatial liquefaction modeling by integrating geotechnical data, liquefaction mechanics, artificial intelligence (AI), and many geospatial predictor variables to provide reliable regional liquefaction predictions for any earthquake event. When integrated with regional hazard assessment capabilities, geospatial liquefcation models will provide value throughout the life of infrastructure projects - from initial desk studies to refined project-specific hazard analyses - and will unlock insights beyond conventional practice, with opportunity to: 
 
-#. Obtain the maximum displacements from the plots by clicking on the crest of the curves with your cursor.
+* prescribe event-specific emergency response and evacuation routes immediately after an earthquake,
 
-.. math::
-    TF = \frac{1}{\cos(\frac{wH}{v_s})}
-
-    AF = \frac{1}{|\cos(\frac{wH}{v_s})|}
+* evaluate network reliability and infrastructure network resiliency using structural databases or other asset inventories, and 
 
+* understand the impacts of earthquake events of vulnerable communities using population demographic data. 
 
-Where
 
-:math:`w` = Angular frequency (2pf)
+Solution Strategy
+-----------------
 
-:math:`H` = distance between any two points in the layers under consideration.
+The state-of-practice geospatial liquefaction model is the :cite:`RB2020` model (updated version of the :cite:`Zhu2017` model), which uses logistic regression to predict probability of liquefaction based on five (5) geospatial variables and trained on a database of liquefaction case histories.
 
-:math:`V` = Velocity of wave travel within the soil layer.
+In this problem, another modeling solution strategy is proposed, according to :cite:`Sanger2024`. The :cite:`Sanger2024` approach parses the problem into that which is empirical and best predicted by AI (the relationship between geospatial variables and subsurface traits) and that which is best predicted by mechanics (liquefaction response, conditioned on those traits). In this approach, the subsurface traits are characterized at point locations using available cone penetration testing (CPT) data. The liquefaction response at each CPT location is computed across a range of magnitude-scale peak ground accelerations (PGAM7.5) using state-of-practice liquefaction manifestation models (e.g., liquefaction potential index, LPI), thereby retaining the knowledge of liquefaction mechanics developed over the last 50+ years. The relationship between manifestation index and PGAM7.5 is represented as a functional form (Eqn 1) with two curve-fitting parameters: A and B (Fig 1). Therefore, the liquefaction response (i.e., A and B) at each CPT location becomes target variables of supervised learning AI models.  
 
-:math:`TF` = Transfer function
+.. math::
+    MI = \left\{ \begin{array}{ll}
+    0, & \text{PGA}_{M7.5} < 0.1g \\
+    \arctan(B \cdot (\text{PGA}_{M7.5} - \frac{A}{B})^2) \cdot 100, & \text{PGA}_{M7.5} \geq 0.1g
+    \end{array} \right.
 
-:math:`AF` = Amplification function
+**Eqn 1.** Manifestation index as a function of A, B, and PGAM7.5. 
 
 
 .. figure:: ./images/manifestationcurve.png
     :scale: 100 %
     :align: center
     :figclass: align-center
+
+    **Fig 1.** Example manifestation curve of LPI vs. PGAM7.5 for a single CPT.
 
+The AI model is trained to predict liquefaction response from a suite of geospatial predictor variables identified as proxies of liquefaction (37 variables). Example predictor variables include mapped or remotely sensed metrics of surface topography and roughness; distance to and elevation above water bodies; geology, geomorphology, hydrology, and more. By applying the final trained AI model to the full predictor datasets, the A and B parameters are predicted geospatially at a defined resolution. A final, key step of the approach is that AI predictions are geostatistically updated via regression kriging in the vicinity of field measurements, such that nearby predictions are based mostly on known subsurface conditions and have lower model uncertainty, whereas distal predictions are based mostly on AI and have greater model uncertainty. In summary, this approach effectively pre-computes liquefaction response across all possible ground motion intensities and durations based on AI-predicted subsurface conditions. These predictions are stored as mapped parameters, awaiting information about a specific earthquake of interest, real or scenario, such as a PGAM7.5 raster from R2D.  
 
+Model predictions were then tested against the leading geospatial model :cite:`RB2020` in three case-history events using receiver operating characteristic and area under the curve analyses (Fig 2). The :cite:`Sanger2024` AI model (before kriging) performed significantly better than :cite:`RB2020` and was further improved by kriging (Fig 3). 
 
-.. figure:: ./images/zhu2017.png
+.. figure:: ./images/sanger2024-roc.png
     :scale: 100 %
     :align: center
     :figclass: align-center
 
+    **Fig 2.** Receiver operator characteristic curves and area under the curve (AUC) analyses comparing :cite:`RB2020` (“R&B”), and the :cite:`Sanger2024` *before* regression kriging (“LPI”).
 
-
-.. figure:: ./images/sanger2024.png
+.. figure:: ./images/zhu2017.png
     :scale: 100 %
     :align: center
     :figclass: align-center
 
+    **(a)**
 
-SimCenter Tool Used
--------------------
-
-REGIONAL RESILIENCE DETERMINATION `R2D <https://simcenter.designsafe-ci.org/research-tools/r2dtool/>`_ TOOL
-
-Example Application
--------------------
-
-.. list-table:: Title
-   :widths: 25 25 50
-   :header-rows: 1
-
-   * - Heading row 1, column 1
-     - Heading row 1, column 2
-     - Heading row 1, column 3
-   * - Row 1, column 1
-     -
-     - Row 1, column 3
-   * - Row 2, column 1
-     - Row 2, column 2
-     - Row 2, column 3
-
-Time can be controlled using either the keyboard or the time control buttons:
-
-* To run time **forward**: Press and hold the 'g' key or click and hold the time forward button: <insert icon>.
-
-* To reset time to **zero**: Type the '0' key or click on the time reset button: <insert icon>.
-
-* The current analysis time is **displayed** in the feedback pane at the bottom of the screen.
-
-* The analysis time step size can be controlled via the Time Step menu (there are combinations of material properties and time steps that intentionally lead to unstable results, so beware).
-
-* The display time step can be controlled via the Animation Speed menu. Internally, this command controls how many analysis time steps are computed between screen updates.
-
-Dr. Layer's tool palette is illustrated below (Windows version: the Mac version is similar but grouped a bit differently):
+.. figure:: ./images/sanger2024-ai.png
+    :scale: 100 %
+    :align: center
+    :figclass: align-center
 
-<insert tool palette image>
+    **(b)**
 
-* The **Arrow Tool** is used to select and manipulate objects.
+.. figure:: ./images/sanger2024-krig.png
+    :scale: 100 %
+    :align: center
+    :figclass: align-center
 
-* The **Panner** and **Camera Orbit Tools** are used to change the viewing point and camera orientation via clicking and dragging.
+    **(c)**
 
-* The **Plot Box Tool** is used to create one of the various types of plot boxes: 
+    **Fig 3.** Comparison between **(a)** Rashidian & Baise (2020), and this model **(b)** before and **(c)** after regression kriging for the Feb. 2011 M6.1 Christchurch event.
 
-    * **Displacement Time History plots** are created by clicking on the relevant layer. The top node in the layer is used as the plotting target.
 
-    * **Fast Fourier Transform (FFT) plots** of a displacement history can be created by clicking on the time history plot.
+SimCenter Tool Used
+-------------------
 
-    * **Stress-strain plots** can be created by control-clicking (i.e., holding down the control key while clicking) on the desired layer.
+The presented problem can be solved using SimCenter's Regional Resilience Determination `R2D <https://simcenter.designsafe-ci.org/research-tools/r2dtool/>`_ Tool. A substantially complete description of the tool is provided in the `R2D Documentation <https://nheri-simcenter.github.io/R2D-Documentation/common/user_manual/about/R2D/about.html>`_. 
 
+The :cite:`Zhu2017` model is implemented in the R2D tool (version 4.2.0), whereas the :cite:`Sanger2024` model is not yet implemented in the R2D tool. In this project, the :cite:`Sanger2024` model was implemented in the R2D tool using Python applications file. 
 
- These controls are self-explanatory in regards to their functions. Note the following, however:
 
-.. note::
-    The scaling buttons will continue to scale as long as they are held down. It is not necessary to click multiple times to get this effect.
+Example Application
+-------------------
 
 
 Remarks
@@ -146,7 +118,6 @@ Remarks
 
 * Plot boxes can be added or removed at any time, but they only accumulate data beginning from the time they are installed, with the exception of FFT plots, which always plot the according to the data accumulated in the target time history. FFT plots can use up to the first 1024 points in a time history.
 
-
 .. warning:: 
     Plotting FFT's will slow down the animation speed significantly, especially as the length of the time histories increase.
 

source/references.bib

@@ -11,11 +11,28 @@ @book{Kramer1996
 
 @article{Zhu2017,
   title={An updated geospatial liquefaction model for global application},
-  author={Zhu, Jing and Baise, Laurie G and Thompson, Eric M},
+  author={Zhu, J. and Baise, L. G. and Thompson, E. M.},
   journal={Bulletin of the Seismological Society of America},
   volume={107},
   number={3},
   pages={1365--1385},
   year={2017},
   publisher={Seismological Society of America}
 }
+
+@article{Sanger2024,
+  title={A global liquefaction model for rapid response and scenario modeling},
+  author={Sanger, M. D. and Geyin, M. and Maurer, B. W.},
+  journal={Manuscript in preparation},
+  year={2024},
+}
+
+@article{RB2020,
+  title={Regional efficacy of a global geospatial liquefaction model},
+  author={Rashidian, V. and Baise, L. G.},
+  journal={Engineering geology},
+  volume={272},
+  pages={105644},
+  year={2020},
+  publisher={Elsevier}
+}