sy - spell checkes

Author: yisangriB

Examples/Examples.json

@@ -26,7 +26,7 @@
       "inputFile": "eeuq-0005/src/input.json"
     },
     {
-      "name": "E6: Surrogate Model: PLoM",
+      "name": "E6: PLoM Surrogate Model",
       "description": "This example demonstrates using a novel method, Probabilistic Learning on Manifolds (PLoM), to develop surrogate models for structural responses under earthquake ground motion inputs.",
       "inputFile": "eeuq-0006/src/input.json"
     }
@@ -43,9 +43,15 @@
     }
     ,
     {
-      "name": "E9: Surrogate Model: GP",
+      "name": "E9: Training GP Surrogate Model",
       "description": "This example demonstrates to develop surrogate models for seismic structural responses.",
       "inputFile": "eeuq-0009/src/input.json"
     }
+    ,
+    {
+      "name": "E10: Prediction from GP Surrogate Model",
+      "description": "This example uses pre-trained GP to obtain statistic for seismic structural responses.",
+      "inputFile": "eeuq-0010/src/input.json"
+    }
   ]
 }

Examples/eeuq-0009/README.rst

@@ -9,7 +9,7 @@ Training a Surrogate Model (Gaussian Process)
 Training Gaussian Process Surrogate Model
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This example shows how to train a surrogate model that can be imported into EE-UQ and replace structural dynamic simulations. The training of a surrogate model requires some number of structural dynamic simulations for representative scenarios [i.e. training set]. In this example, these simulations are performed using recorded ground motions selected from the PEER NGA database. The ground motions are selected such that it covers a wide domain of intensity measure (IM) space, as uniform as possible. Three IMs are considered in the example: pseudo-spectral acceleration at period 0.5 sec (PSA), 5-75% duration (D5-75), and SaRatio following the work in [Zhong2023]_. We additionally consider the stiffness of the target structure (3 story building) as input of the surrogate model.
+This example shows how to train a surrogate model that can be imported into EE-UQ and replace structural dynamic simulations. The training of a surrogate model requires some number of structural dynamic simulations for representative scenarios [i.e. training set]. In this example, these simulations are performed using recorded ground motions selected from the PEER NGA database. The ground motions are selected such that it covers a wide domain of intensity measure (IM) space, as uniform as possible. Three IMs are considered in the example: pseudo-spectral acceleration at period 0.5 sec (PSA), 5-75% duration (D5-75), and SaRatio following the work in [Zhong2023]_. We additionally consider the stiffness of the target structure (3 story building) as input for the surrogate model.
 
       .. figure:: figures/EE09_main2.png
          :name: UQ inputs
@@ -40,11 +40,11 @@ Set Up GP Surrogate Modeling Options
    - **Number of Samples** : The number of samples should be the same as the ground motions to be selected in the EVT tab, i.e. 100. This number can be flexible when stochastic ground motion is used. Typically, as the number of samples increases, the accuracy of the surrogate model will increase but training time will also increase.
    - **Max Computation Time** : 60 mins (default)
    - **Target Accuracy** : 0.02. EE-UQ will give a warning when this accuracy target is not met
-   - **Random Seed** : 984. Arbitrarily selected seed for the random generator used in the Surrogate modeling algorithm
+   - **Random Seed** : 984. An arbitrarily selected seed for the random generator used in the Surrogate modeling algorithm
    - **Parallel Execution** : True. This will parallelize multiple dynamic simulations
    - **Advanced Options for Gaussian Process Model** : False. By default, EE-UQ takes **Martern 5/2**, **Log-space transform of QoI**, **Heteroskedastic nugget variance** options.
    - **Existing Data set** : False. This is useful when one hopes to resume the surrogate model training after one training round is finished, by performing more simulations
-   - **Intensity Measure Calculation**: Select the intensity measures (IMs) to be used as the augmented input of the surrogate model -Sa(T=0.5 sec), D5-75, and SaRatio(T=1.0 sec in range of 0.1-1.5 sec)
+   - **Intensity Measure Calculation**: Select the intensity measures (IMs) to be used as the augmented input of the surrogate model -Sa(T=0.5 sec), D5-75, and SaRatio(T=1.0 sec in the range of 0.1-1.5 sec)
 
 More information can be found in the :ref:`User Guide<lblSimSurrogate>`.
 
@@ -64,7 +64,7 @@ Define Target Structure
          GI tab - Specify 3 story building
 
 
-2. In **SIM tab**, the specifics of the target structural model is provided via **MDOF** building generator. One-story building is created having stiffness as an input parameter.
+2. In **SIM tab**, the specifics of the target structural model is provided via **MDOF** building generator. A three-story building is created having stiffness as an input parameter.
 
       .. figure:: figures/EE09_SIM.png
          :name: UQ inputs
@@ -77,7 +77,7 @@ Define Target Structure
 Select Ground Motions for the Training
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-3. In **EVT tab**, the option to retrieve ground motions from **PEER NGA records** is selected. To allow the surrogate models to cover a wide variation of ground motions (represented as "wide IM domain"), let us select **No Spectrum - Uniform IMs** for the analysis. Set the **Number of samples per bin** 1, and add three intensity measures that are specified in the UQ tab as the input of surrogate, i.e. "5-75% Significant Duration", "Pseudo Spectral Acceleration (with a natural period of 0.5 sec)", and "SaRatio (at 1.0 sec in range of 0.1-1.5 sec). Set the coverage ranges respectively to [2.5, 30], [0.1, 2.0], and [0.25, 1.2]. For the former two IMs, the number of bins is set as 5 and the SaRatio will have 4 bins. Therefore, the total number of bins (i.e. grid points in 3 dimensional space) is 100. 
+3. In **EVT tab**, the option to retrieve ground motions from **PEER NGA records** is selected. To allow the surrogate models to cover a wide variety of ground motions (represented as "wide IM domain"), let us select **No Spectrum - Uniform IMs** for the analysis. Set the **Number of samples per bin** 1, and add three intensity measures that are specified in the UQ tab as the input of surrogate, i.e. "5-75% Significant Duration", "Pseudo Spectral Acceleration (with a natural period of 0.5 sec)", and "SaRatio (at 1.0 sec in range of 0.1-1.5 sec). Set the coverage ranges respectively to [2.5, 30], [0.1, 2.0], and [0.25, 1.2]. For the former two IMs, the number of bins is set as 5, and the SaRatio will have 4 bins. Therefore, the total number of bins (i.e. grid points in 3-dimensional space) is 100. 
 
       .. figure:: figures/EE09_EVT1.png
          :name: UQ inputs
@@ -109,7 +109,7 @@ Select Ground Motions for the Training
 
     <a href="https://ngawest2.berkeley.edu/" target="_blank">PEER Ground Motion Database</a>
 
-* Press **Select Records** when ready, which will connect the PEER NGA West Ground Motion Database. You could use your account and password to login. If you don’t have the account, you can easily sign up at |PEER Ground Motion Database|. The list of selected ground motions and their scaling factors are displayed in the table. The coverage of IMs of the selected ground motions will be displayed in the right-hand side panel as below.
+* Press **Select Records** when ready, which will connect the PEER NGA West Ground Motion Database. You could use your account and password to log in. If you don’t have an account, you can easily sign up at |PEER Ground Motion Database|. The list of selected ground motions and their scaling factors are displayed in the table. The coverage of IMs of the selected ground motions will be displayed in the right-hand side panel as below.
 
       .. figure:: figures/EE09_EVT3.png
          :name: UQ inputs
@@ -119,9 +119,9 @@ Select Ground Motions for the Training
 
          EVT tab - Selected ground motions in IM space
 
-Note that *approximated* IM values are used for this ground motion selection. The approximated IMs are read from the flat file PEER provides, and geometric mean is used to average out the two horizontal directional components. Therefore the actual IM used as the surrogate input may not exactly match the IM value shown in the above figure. The yellow dots represent the selected 100 ground motion records having corresponding IMs, blue/red dots represent the center of each bin, i.e. anchor point. It is colored red when no matching ground motion is found to be close to the anchor point. This informs users how good the IM coverage is.
+Note that *approximated* IM values are used for this ground motion selection. The approximated IMs are read from the flat file PEER provides, and the geometric mean is used to average out the two horizontal directional components. Therefore the actual IM used as the surrogate input may not exactly match the IM value shown in the above figure. The yellow dots represent the selected 100 ground motion records having corresponding IMs, blue/red dots represent the center of each bin, i.e. anchor point. It is colored red when no matching ground motion is found to be close to the anchor point. This informs users how good the IM coverage is.
 
-.. warning::  Note that the surrogate modeling algorithms are stronger in "interpolation" rather than extrapolation. Therefore, when later using the pre-trained surrogate model to predict the response of the structure subjected to a new (untrained) IM values (e.g. :ref:`example 10<eeuq-0010>`), it is important to make sure the IMs of the new ground motions are well covered by the domain of the training samples, i.e. it should lie the area that is shown blue in the above figure. Otherwise, the prediction from the surrogate model is likely not reliable.
+.. warning::  Note that the surrogate modeling algorithms are stronger in "interpolation" rather than extrapolation. Therefore, when later using the pre-trained surrogate model to predict the response of the structure subjected to new (untrained) IM values (e.g. :ref:`example 10<eeuq-0010>`), it is important to make sure the IMs of the new ground motions are well covered by the domain of the training samples, i.e. it should lie the area that is shown blue in the above figure. Otherwise, the prediction from the surrogate model is likely not reliable.
 
 4. The **FEM tab** is kept as default.
 
@@ -173,7 +173,7 @@ Run the Analysis and Process Results
 
 
 
-8. Additionally the comparison between the original simulation samples and leave-one-out cross-validation (LOOCV) predictions from surrogate is provided as the scatter plot. When we have a large variance in the response observations, as in this example, the LOOCV mean is not expected to match exactly the data samples observed. Instead, they are expected to lie on a reasonable prediction bound. The below graph shows the inter-quartile prediction bounds, i.e. 25%-75%, which are expected to cover 50% of the sample observations. 
+8. Additionally the comparison between the original simulation samples and leave-one-out cross-validation (LOOCV) predictions from the surrogate is provided as the scatter plot. When we have a large variance in the response observations, as in this example, the LOOCV mean is not expected to match exactly the data samples observed. Instead, they are expected to lie on a reasonable prediction bound. The below graph shows the inter-quartile prediction bounds, i.e. 25%-75%, which are expected to cover 50% of the sample observations. 
 
       .. figure:: figures/EE09_RES2.png
          :name: UQ inputs
@@ -197,7 +197,7 @@ Please see the :ref:`User Guide <lblSimSurrogate>` for more details on the verif
 
       .. note::
 
-         The user can interact with the plot as following.
+         The user can interact with the plot as follows.
 
          - Windows: left-click sets the Y axis (ordinate).  right-click sets the X axis (abscissa).
          - MAC: fn-clink, option-click, and command-click all set the Y axis (ordinate).  ctrl-click sets the X axis (abscissa).
@@ -220,7 +220,7 @@ Please see the :ref:`User Guide <lblSimSurrogate>` for more details on the verif
 
          RES tab - Trained surrogate model
 
-   - **SimGPModel.json** : This file contains information required to quickly reconstruct the surrogate model and predict the response for different input realizations. This can be later imported in EEUQ.
+   - **SimGPModel.json** : This file contains information required to quickly reconstruct the surrogate model and predict the response for different input realizations. This can be later imported into EEUQ.
    - **tmplatedir_SIM** : This folder contains all the scripts and commands to run the original dynamic time history analysis. This folder can later be imported into EEUQ along with the surrogate model to alternate between original simulations and surrogate predictions or compare the surrogate predictions to the response of the original model. 
 
    The button "Save GP Info" will additionally allow users to save GP information, e.g. calibrated hyper-parameter values.