Merge pull request #12 from silviamazzoni/main

My first pass in updating use-case documentation

README.md

@@ -35,7 +35,7 @@ DesignSafe ReadTheDocs Documentation with [MkDocs](https://mkdocs.readthedocs.io
     ```
     <sup>After the `poetry shell` command, you should be in a Poetry-managed environment. Your prompt might be prefixed with the name of the environment.</sup>
 5. Open the website _at the URL echoed by the program_, e.g.
-    http://127.0.0.1:8000/user-guide/
+    [link](http://127.0.0.1:8000/user-guide/){:target="_blank"}
 
 ### B. Via Docker
 

user-guide/docs/usecases/arduino/usecase.md

@@ -1,45 +1,68 @@
-# From constitutive parameter calibration to site response analysis
-
-## A collection of educational notebooks to introduce model parameter calibration and site response analysis using OpenSees in DesignSafe-CI
-
-**Pedro Arduino - University of Washington** <br/>
-**Sang-Ri Yi - SimCenter, UC Berkeley** <br/>
+## OpenSees Model Calibration
+
+<span style="font-size:1.5em;">
+**From constitutive parameter calibration to site response analysis**
+</span>
+<br><br>
+<span style="font-size:1.25em;">
+***A collection of educational notebooks to introduce model-parameter calibration and site response analysis using OpenSees in DesignSafe-CI***
+</span>
+
+**Pedro Arduino - University of Washington**  <br>
+**Sang-Ri Yi - SimCenter, UC Berkeley**  <br>
 **Aakash Bangalore Satish - SimCenter, UC Berkeley**
 
-*key Words: quoFEM, OpenSees, Tapis, Python*
-
-## Resources
+*Key Words: quoFEM, OpenSees, Tapis, Python*
 
-The example makes use of the following DesignSafe resources:
-
-[DesignSafe - Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis)<br/>
-[SimCenter - quoFEM](https://simcenter.designsafe-ci.org/research-tools/quofem-application)<br/>
-[OPenSees - Simulation on DS](https://www.designsafe-ci.org/rw/workspace/#!/OpenSees::Simulation)<br/>
-
-and the following Jupyter notebooks are available to facilitate the analysis of each case. You can access and run them directly from the DesignSafe community folder.
+### Resources
+
+#### Jupyter Notebooks
+The following Jupyter notebooks are available to facilitate the analysis of each case. They are described in details in this section. You can access and run them directly on DesignSafe by clicking on the "Open in DesignSafe" button.
 
 | Site Response | Notebook |
 | :-------: | :---------:  |
-| FreeField Response | [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/freeFieldJupyterPM4Sand/freeFieldJupyterPM4Sand_Community.ipynb) |
+| FreeField Response | freeFieldJupyterPM4Sand_Community.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/freeFieldJupyterPM4Sand/freeFieldJupyterPM4Sand_Community.ipynb) |
 
 | quoFEM | Notebook |
 | :-------: | :---------:  |
-| Sensitivity analysis     | [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/GlobalSensitivity/quoFEM-Sensitivity.ipynb)|
-| Bayessian calibration     | [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/BayesianCalibration/quoFEM-Bayesian.ipynb)|
-| Forward propagation  | [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/ForwardPropagation/quoFEM-Propagation.ipynb)|
+| Sensitivity analysis     | quoFEM-Sensitivity.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/GlobalSensitivity/quoFEM-Sensitivity.ipynb)|
+| Bayessian calibration     | quoFEM-Bayesian.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/BayesianCalibration/quoFEM-Bayesian.ipynb)|
+| Forward propagation  | quoFEM-Propagation.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Jupyter%20Notebooks%20for%20Civil%20Engineering%20Courses/University_of_Washington/quoFEM_Example1/ForwardPropagation/quoFEM-Propagation.ipynb)|
+
+
+#### DesignSafe Resources
+The following DesignSafe resources were used in developing this use case.
+
+* [DesignSafe - Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis)<br/>
+* [SimCenter - quoFEM](https://simcenter.designsafe-ci.org/research-tools/quofem-application)<br/>
+* [Simulation on DesignSafe - OpenSees](https://www.designsafe-ci.org/rw/workspace/#!/OpenSees::Simulation)<br/>
+
+
+### Background
+
+#### Citation and Licensing
+* Please cite [Aakash B. Satish et al. (2022)](https://doi.org/10.1007/978-3-031-11898-2_152){:target="_blank"}  to acknowledge the use of resources from this use case.<br/>
 
-## Description
+* Please cite [Sang-Ri Yi et al. (2022)](https://doi.org/10.1007/978-3-031-30125-4_6){:target="_blank"}  to acknowledge the use of resources from this use case.<br/>
+
+* Please cite [Chen, L. et al. (2021)](https://peer.berkeley.edu/sites/default/files/2021_chen_final.pdf){:target="_blank"}  to acknowledge the use of resources from this use case.
+
+* Please cite [Rathje et al. (2017)](https://doi.org/10.1061/(ASCE)NH.1527-6996.0000246){:target="_blank"}  to acknowledge the use of DesignSafe resources.
+
+* This software is distributed under the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html){:target="_blank"} .
+
+### Description
 
 Seismic site response refers to the way the ground responds to seismic waves during an earthquake. This response can vary based on the soil and rock properties of the site, as well as the characteristics of the earthquake itself. 
 
 Site response analysis for liquefiable soils is fundamental in the estimation of demands on civil infrastructure including buildings and lifelines. For this purpose, current state of the art in numerical methods in geotechnical engineering require the use of advance constitutive models and fully couple nonlinear finite element (FEM) tools. Advanced constitutive models require calibration of material parameters based on experimental tests. These parameters include uncertainties that in turn propagate to uncertenties in the estimation of demands. The products included in this use-case provide simple examples showing how to achieve site response analysis including parameter identification and uncertainty quantification using SimCenter tools and the DesignSafe cyber infrastructure.
 
-<p align="center">
-<img src="../img/SRschematic2.PNG" alt="Propagation of vertical waves in site response analysis" width="600"/>
-</p>
-<p align="center"> <b>Fig.1 - Site response problem</b> </p>
 
-## Implementation
+
+![Propagation of vertical waves in site response analysis"](./img/SRschematic2.PNG "Fig.1 - Site response problem")
+<p style="text-align: center;"> Fig.1 - Site response problem </p>
+
+### Implementation
 
 This use-case introduces a suite of Jupyter Notebooks published in DesignSafe that navigate the process of  constitutive model parameter calibration and site response analysis for a simple liquefaction case. They also introduce methods useful when using DesignSafe infrastructure in TACC. All notebooks leverage existing SimCenter backend functionality (e.g. Dakota, OpenSees, etc) implemented in quoFEM and run locally and in TACC through DesignSafe. The following two pages address these aspects, including:
 
@@ -54,14 +77,3 @@ This use-case introduces a suite of Jupyter Notebooks published in DesignSafe th
     c. **Propagation of parameter undertainty in site response analysis notebook**: This notebook introduces methods to propagate material parameter uncertainties in site reponse analysis.
 
 
-## Citation and Licensing
-
-* Please cite [Aakash B. Satish et al. (2022)](https://doi.org/10.1007/978-3-031-11898-2_152){target=_blank} to acknowledge the use of resources from this use case.<br/>
-
-* Please cite [Sang-Ri Yi et al. (2022)](https://doi.org/10.1007/978-3-031-30125-4_6){target=_blank} to acknowledge the use of resources from this use case.<br/>
-
-* Please cite [Chen, L. et al. (2021)](https://peer.berkeley.edu/sites/default/files/2021_chen_final.pdf){target=_blank} to acknowledge the use of resources from this use case.
-
-* Please cite [Rathje et al. (2017)](https://doi.org/10.1061/(ASCE)NH.1527-6996.0000246){target=_blank} to acknowledge the use of DesignSafe resources.
-
-* This software is distributed under the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html){target=_blank}.

user-guide/docs/usecases/dataanalyticsusecases.md

@@ -1,5 +1,7 @@
 # Data Analytics
 
+---
+
 <!-- ## Multi-Data Set Image Analysis in Taggit -->
 
 {% include-markdown 'haan/usecase-3.md' %}

user-guide/docs/usecases/dawson/usecase.md

@@ -1,14 +1,30 @@
 ## Large-Scale Storm Surge
 
-### ADCIRC Use Case - Using Tapis and Pylauncher for Ensemble Modeling in DesignSafe 
+<span style="font-size:1.5em;">
+**ADCIRC Use Case - Using Tapis and Pylauncher for Ensemble Modeling in DesignSafe**
+</span>
 
-**Clint Dawson, University of Texas at Austin**  
-**Carlos del-Castillo-Negrete, University of Texas at Austin**  
+**Clint Dawson, University of Texas at Austin**  <br>
+**Carlos del-Castillo-Negrete, University of Texas at Austin**   <br>
 **Benjamin Pachev, University of Texas at Austin**  
 
-The following use case presents an example of how to leverage the Tapis API to run an ensemble of HPC simulations. The specific workflow to be presented consists of running ADCIRC, a storm-surge modeling application available on DesignSafe, using the parametric job launcher pylauncher. All code and examples presented are meant to be be executed from a Jupyter Notebook on the DesignSafe platform and using a DesignSafe account to make Tapis API calls. Accompanying jupyter notebooks for this use case can be found in the ADCIRC folder in [Community Data](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC){target=_blank}.
+The following use case presents an example of how to leverage the Tapis API to run an ensemble of HPC simulations. The specific workflow to be presented consists of running ADCIRC, a storm-surge modeling application available on DesignSafe, using the parametric job launcher pylauncher. All code and examples presented are meant to be be executed from a Jupyter Notebook on the DesignSafe platform and using a DesignSafe account to make Tapis API calls. 
 
-Learn more: [Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis){target=_blank}.
+
+### Resources
+
+#### Jupyter Notebooks
+Accompanying jupyter notebooks for this use case can be found in the ADCIRC folder in [Community Data](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC){target=_blank}. You may access these notebooksdirectly:
+
+| Scope | Notebook |
+| :-------: | :---------:  |
+| Create an ADCIRC DataSet | Creating an ADCIRC DataSet.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/ADCIRC/Creating%20an%20ADCIRC%20Dataset.ipynb) |
+| Create an Ensemble Simulations | ADCIRC Ensemble Simulations.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/ADCIRC/ADCIRC%20Ensemble%20Simulations.ipynb) |
+
+#### DesignSafe Resources
+The following DesignSafe resources were used in developing this use case.
+
+* [Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis){target=_blank}.
 
 #### Background 
 

user-guide/docs/usecases/dawson/usecase2.md

@@ -1,9 +1,11 @@
 ## ADCIRC Datasets
 
+<span style="font-size:1.5em;">
 **ADCIRC Use Case - Creating an ADCIRC DataSet on DesignSafe**   
+</span>
 
-**Clint Dawson, University of Texas at Austin**
-**Carlos del-Castillo-Negrete, University of Texas at Austin**
+**Clint Dawson, University of Texas at Austin** <br>
+**Carlos del-Castillo-Negrete, University of Texas at Austin**<br>
 **Benjamin Pachev, University of Texas at Austin**
 
 ### Overview
@@ -29,7 +31,20 @@ To see a couple of Example data-sets, and associated published research using th
 
 An accompanying jupyter notebook for this use case can be found in the ADCIRC folder in [Community Data](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC) under the name `Creating an ADCIRC DataSet.ipynb`.
 
-Learn more: [Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis).
+
+### Resources
+
+#### Jupyter Notebooks
+The following Jupyter notebooks are available to facilitate the analysis of each case. They are described in details in this section. You can access and run them directly on DesignSafe by clicking on the "Open in DesignSafe" button.
+
+| Scope | Notebook |
+| :-------: | :---------:  |
+| Create an ADCIRC DataSet | Creating an ADCIRC DataSet.ipynb <br> [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/ADCIRC/Creating%20an%20ADCIRC%20Dataset.ipynb) |
+
+#### DesignSafe Resources
+The following DesignSafe resources were leveraged in developing this use case.
+
+* [Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis){target=_blank}.
 
 ### Background
 
@@ -89,7 +104,7 @@ For example the file may look like:
 
 ### Example Notebook: Creating ADCIRC DataSet
 
-The example within this use case comprises of 4 main steps to create a data-set starting from a set of ADCIRC control input files. The notebook can be found at in the [ADCIRC Use Case’s](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC) folder with the name `Creating an ADCIRC DataSet.ipynb` . Note that the notebook should be copied to the users `~/MyData` directory before being able to use it (these steps are covered in the notebook). 
+The example within this use case comprises of 4 main steps to create a data-set starting from a set of ADCIRC control input files. The notebook can be found at in the [ADCIRC Use Case’s](https://www.designsafe-ci.org/data/browser/public/designsafe.storage.community/Use%20Case%20Products/ADCIRC) folder with the name `Creating an ADCIRC DataSet.ipynb` . Note that the notebook should be copied to the users `~/MyData` directory before being able to use it (these steps are covered in the notebook). [![Open In DesignSafe](https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg)](https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/ADCIRC/Creating%20an%20ADCIRC%20Dataset.ipynb)
 
 The notebook covers the first two steps of this use case, namely identifying storm surge events and creating base input data sets to run using ADCIRC. We briefly overview the notebook’s results below.