diff --git a/doc/Acknowledging.md b/doc/Acknowledging.md index 5d22f1c1..cba87729 100644 --- a/doc/Acknowledging.md +++ b/doc/Acknowledging.md @@ -4,7 +4,7 @@ The primary reference for the Broadband Platform software system (v15.3.0 and la * Maechling, P. J., F. Silva, S. Callaghan, and T. H. Jordan (2015). SCEC Broadband Platform: System Architecture and Software Implementation, Seismol. Res. Lett., 86, no. 1, doi: 10.1785/0220140125. -The primary reference that describes the validation process developed by the Broadband Platform group to establish that the BBP platform software produces results suitable for use in engineering applications is: +The primary reference that describes the validation process developed by the Broadband Platform group to establish that the BBP platform software produces results are suitable for use in engineering applications is: * Goulet, C.A., Abrahamson, N.A., Somerville, P.G. and K, E. Wooddell (2015) The SCEC Broadband Platform Validation Exercise: Methodology for Code Validation in the Context of Seismic-Hazard Analyses, Seismol. Res. Lett., 86, no. 1, doi: 10.1785/0220140104 @@ -12,7 +12,7 @@ The primary reference that describes the results of the validation process in 20 * Dreger, D. S., Beroza, G.C., Day, S. M., Goulet, C. A., Jordan, T. H., Spudich, P. A., and Stewart, J. P. (2015). Validation of the SCEC Broadband Platform V14.3 Simulation Methods Using Pseudospectral Acceleration Data, Seismol. Res. Lett., 86, no. 1, doi:10.1785/0220140118. -References for specific computational methods included in the Broadband Platform (v15.3.0 and later, including v16.5.0) and for the validation procedures developed by the Broadband Platform include: +References for specific computational methods included in the Broadband Platform (v15.3.0 and later, including v16.5.0, v17.3.0, and v19.4.0) and for the validation procedures developed by the Broadband Platform include: * Anderson, J. G (2015) The Composite Source Model for Broadband Simulations of Strong Ground Motions Seismological Research Letters, January/February 2015, v. 86, p. 68-74, First published on December 17, 2014, doi:10.1785/0220140098 * Atkinson, G. M., and Assatourians, K. (2015) Implementation and Validation of EXSIM (A Stochastic Finite‐Fault Ground‐Motion Simulation Algorithm) on the SCEC Broadband Platform Seismological Research Letters, January/February 2015, v. 86, p. 48-60, First published on December 17, 2014, doi:10.1785/0220140097 diff --git a/doc/FAQ.md b/doc/FAQ.md index 0a02caed..84240f63 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -4,17 +4,17 @@ * The most recent version of the Broadband Platform software is posted GitHub's releases page. We expect to make new releases of the Broadband Platform every 6-12 months. * Which version of the Broadband Platform should I use? - * Several previous versions of the broadband platform have been released by SCEC. New versions of the platform incorporate software updates, improvements, and bug fixes. For this reason, we recommend all new users should use the most recent version of the platform, as posted on the Broadband Platform wiki page. We recommend users migrate their work to the most recent version of the broadband platform at the first opportunity. Previous versions of the platform are still available primarily to support reproducibility of earlier results. + * Several previous versions of the Broadband Platform have been released by SCEC. New versions of the Platform incorporate software updates, improvements, and bug fixes. For this reason, we recommend all new users should use the most recent version of the Platform, as posted on the Broadband Platform wiki page. We recommend users migrate their work to the most recent version of the Broadband Platform at the first opportunity. Previous versions of the Platform are still available primarily to support reproducibility of earlier results. * Is the Broadband Platform compatible with Python 3? - * The current version of the Broadband Platform is not compatible with Python 3. We expect to have the Broadband Platform ported to Python 3 as part of our next release. For now, users will need to run the Broadband Platform using the latest Python 2.7 release. + * The Broadband Platform was ported to Python 3 as of version 19.8. All Broadband Platform versions after 19.8 require Python 3 to run. * How can I simulate earthquakes in California, Japan and Eastern North America? - * The newest Broadband Platform distribution supports simulations for several 1D velocity models. These 1D velocity models were defined to represent structure in parts of California including Los Angeles Basin, Mojave Desert, Central California Coast, Eastern North America, including Virginia and Eastern Canada, and Western and Central Japan. Broadband Platform users can select a region, and simulate earthquakes in that region for one or more of the ground motion modeling software installed in the platform. + * The newest Broadband Platform distribution supports simulations for several 1D velocity models. These 1D velocity models were defined to represent structure in parts of California including Los Angeles Basin, Mojave Desert, Central California Coast, Southern Walker Lane (Southern Sierra Nevada region), Eastern North America, including Virginia and Eastern Canada, and Western and Central Japan. Broadband Platform users can select a region, and simulate earthquakes in that region for one or more of the ground motion modeling software installed in the platform. * What region should I use for an earthquake in California? - * The Broadband Platform currently has 4 simulation regions for California: LA Basin, Mojave, - Central California, and Northern California. Please take a look at this [map](pdfs/california_gfs_19_4.pdf) for a suggestion of what region to use for simulations in California. Please note that these are only approximate and somewhat subjective, but basically, for ruptures located in the Southern California, users should use the LA Basin region. The Mojave region should be used for faults in most of the inland part of Southern California, the Central California region should be used for the central coast region of California, and the Northern California region should be used for ruptures located in the remainder of the State. + * The Broadband Platform currently has 5 simulation regions for California: LA Basin, Mojave, + Central California, Southern Sierra Nevada, and Northern California. Please take a look at this [map](pdfs/california_gfs_22_4.pdf) for a suggestion of what region to use for simulations in California. Please note that these are only approximate and somewhat subjective, but basically, for ruptures located in the Southern California, users should use the LA Basin region. The Mojave region should be used for faults in most of the inland part of Southern California, the Central California region should be used for the central coast region of California, the Southern Sierra Nevada region should be used for inland portion of Central and Northern California, and the Northern California region should be used for ruptures located in the remainder of the State. * How can I simulate earthquakes outside California, Eastern North America, and Japan? * Simulating earthquakes outside one of the currently supported regions requires creating a new 1D velocity profile and setting up a new simulation region. In addition to the 1D velocity profile for the region, the Broadband Platform requires the calculation of Greens' Functions and the configuration of several region-specific parameters so it is not as simple as just creating a new 1D velocity model and supplying that file to the BBP. At this time, setting up a new velocity model/Green's Functions/region parameters requires help from several of the science teams. Also the Broadband platform does not currently include software to generate new Greens functions needed for most simulation methods (EXSIM is an exception to this rule). In future releases of the Broadband Platform, it may be possible for the user to define a 1D velocity profile, generate Greens Functions for that profile, and then simulate earthquakes using those Greens Functions. @@ -23,15 +23,15 @@ * The Broadband Platform was designed to generate reproducible results. Therefore, given the same inputs, we expect it to produce the exact outputs again and again. In order to generate different simulation variations (or realizations), users can run the Broadband Platform multiple times, but providing a different SEED value each time the BBP is run. The SEED value is included in the simple source description (SRC) file. So, to run 10 different simulation variations, users will need to create 10 copies of the SRC file, each with a different value for the SEED parameter. This seed will be used to initialize the random number generators in several of the BBP modules, resulting in different parameters to be used. For example, in the GP rupture generator, different SEED values will result in different slip distributions. Similarly, other modules use the SEED to randomize their own parameters. * I try to run the tests of UnitTests.py. The result tells me that ImportError: No module named scipy. I wonder what wrong it is. - * The error you are seeing relates to the python software that you are using. The Broadband Platform using standard Python libraries. It also requires several "optional" Python libraries that must be added to most Python installations. The error you are getting indicates that you need to install one (or more) additional Python libraries. These additional libraries are free, but how you install them will depend on the system on which you are installing the broadband platform. + * The error you are seeing relates to the python software that you are using. The Broadband Platform uses standard Python libraries. It also requires several "optional" Python libraries that must be added to most Python installations. The error you are getting indicates that you need to install one (or more) additional Python libraries. These additional libraries are free, but how you install them will depend on the system on which you are installing the broadband platform. Users can install the necessary additional Python libraries onto their computer. Then the Broadband Platform should run. How to install the needed libraries, such as the SciPy library mentioned in your error message will depend on the Python software you are using. One option that we recommend is using the open source [Anaconda](https://www.anaconda.com) Python distribution. It includes most of the required python libraries in one simple installation. - The BBP v19.4.0 requires Python v2.7+ and several optional Python libraries. It is possible to collect all necessary Python libraries, but we recommend using a Python distribution that includes nearly all the required libraries. We recommend use of the [Anaconda Python distribution (free)](https://www.anaconda.com). Go to the Anaconda downloads page, and download the Python 2.7 command line distribution tool (free). Once downloaded, the Anaconda Python distribution can be installed by running the downloaded script file. + The BBP v22.4.0 requires Python v3.6+ and several optional Python libraries. It is possible to collect all necessary Python libraries, but we recommend using a Python distribution that includes nearly all the required libraries. We recommend use of the [Anaconda Python distribution (free)](https://www.anaconda.com). Go to the Anaconda downloads page, and download the Python 3.6+ command line distribution tool (free). Once downloaded, the Anaconda Python distribution can be installed by running the downloaded script file. - It will ask you to agree to the license, and then install a current version of Python 2.7 and most of the Python libraries required by the BBP v19.4.0. Anaconda Python can be installed in your user directory and does not require administrator privileges. At the end of the installation process, the installation tool should update your shell initialization files to put the Anaconda Python installation into your default path. + It will ask you to agree to the license, and then install a current version of Python 3.6+ and most of the Python libraries required by the BBP v22.4.0. Anaconda Python can be installed in your user directory and does not require administrator privileges. At the end of the installation process, the installation tool should update your shell initialization files to put the Anaconda Python installation into your default path. Update the PyProj library in Anaconda Python @@ -49,7 +49,7 @@ $ pip install scipy ``` - If you use this approach, you may find that you need to add other Python modules (in addition to scipy) such as matplotlib, pyproj, and basemap. However, once you add all the required Python modules, the Broadband Platform software should run. + If you use this approach, you may find that you need to add other Python modules (in addition to scipy) such as matplotlib, pyproj, numba, and basemap. However, once you add all the required Python modules, the Broadband Platform software should run. * When I run the UnitTests.py, I get a few warnings. I wonder if I can ignore these warnings, what do I do next? * When running BBP's unit tests, you will sometime see warning messages like these: diff --git a/doc/Home.md b/doc/Home.md index 0c62ea74..1802b101 100644 --- a/doc/Home.md +++ b/doc/Home.md @@ -1,7 +1,12 @@ The Southern California Earthquake Center (SCEC) Broadband Platform (BBP) is a software system that can generate 0-20+ Hz seismograms for historical and scenario earthquakes in California, Eastern North America, and Japan using several alternative computational methods. ## Latest Release -The most recent version of the SCEC Broadband Platform is version 19.4 which was released in May 2019. The BBP 19.4 software can be downloaded from SCEC's [Broadband Platform GitHub repository.](https://github.com/SCECcode/bbp) We recommend that all new users work with BBP 19.4 because the version adds new capabilities and provides improvements to the methods provided in earlier releases of the Broadband Platform. Existing BBP users should review the [Broadband Platform 19.4 release notes](./Release-Notes.md) and should upgrade to this new version if the improvements included in it are important to their specific use of the platform. Previous versions of the Broadband Platform are available for users that want to reproduce results produced with earlier versions of the Platform. Please review the [BBP installation instructions](./Installation.md) for details on how to download and install the BBP 19.4 on your local computer. +The most recent version of the SCEC Broadband Platform is version 22.4 which was released in August 2022. The BBP 22.4 software can be downloaded from: + +* [Broadband Platform GitHub repository](https://github.com/SCECcode/bbp) (Released August 2022) +* [Broadband Platform Github Wiki Documentation](https://github.com/SCECcode/bbp/wiki) + +We recommend that all new users work with BBP 22.4 because the version adds new capabilities and provides improvements to the methods provided in earlier releases of the Broadband Platform. Existing BBP users should review the [Broadband Platform 22.4 release notes](./Release-Notes) and should upgrade to this new version if the improvements included in it are important to their specific use of the platform. Previous versions of the Broadband Platform are available for users that want to reproduce results produced with earlier versions of the Platform. Please review the [BBP installation instructions](./Installation) for details on how to download and install the BBP 22.4 on your local computer. ## Overview The goal of the SCEC Broadband Simulation Platform is to generate broadband (0-20+ Hz) ground motions for earthquakes. The SCEC Broadband Platform is a collaborative software development project involving SCEC researchers, research engineers, graduate students, and the SCEC/CME software development group. SCEC scientific groups have contributed modules to the Broadband Platform including kinematic rupture generation, low- and high-frequency seismogram synthesis using 3D wave propagation through 1D layered velocity structures, non-linear site effects, ground motion intensity measure calculations, and visualization. These complex scientific codes have been integrated into a system that supports easy on-demand computation of broadband seismograms, providing user-defined, repeatable calculation of ground-motion seismograms, using alternative simulation methods, and software utilities to generate tables, plots, and maps. The SCEC Broadband Platform is designed to be used by both scientific and engineering researchers with some experience interpreting ground motion simulations. @@ -10,14 +15,14 @@ Users may calculate broadband seismograms for both historical earthquakes (valid The SCEC BBP software can be compiled and run on recent Linux systems with GNU compilers. The Broadband Platform continues to evolve, and new versions of the BBP are released periodically on GitHub. The latest release includes seven simulation methods, eight simulation regions covering California, Japan, Eastern North America, and the ability to compare simulation results against empirical ground motion models. The newest features include the ability to simulate multi-segment ruptures using several simulation methods. And, in addition to a new simulation method, it now includes improvements to several existing ground motion simulation methods and revised Green’s functions for all simulation regions. In this release, the site response module is integrated with all simulation methods and can also be used for comparing simulated data against historical earthquakes -The Broadband Platform is open-source software that is made available under the terms of the Apache License, Version 2.0. A copy of the License is provided by the Apache Software Foundation (http://www.apache.org/licenses/LICENSE-2.0) and can also be found with the software in the 'LICENSE' file. +The SCEC-developed portions of the Broadband platform software is distributed under the terms of the BSD 3-Clause open-source license. Please see the LICENSE.txt file for more information. Individual models codes may be offered under their own open-source software licenses, please look for a LICENSE.txt file under specific sub folders in the 'src' directory for module-specific license information. ### Preferred Reference for the Broadband Platform Software Please support the Broadband Platform project by acknowledging the use of this software. Acknowledgements and citations help us obtain additional resources for continued development of the platform. The primary reference for the Broadband Platform software system (v15.3.0 and later) is: * Maechling, P. J., F. Silva, S. Callaghan, and T. H. Jordan (2015). SCEC Broadband Platform: System Architecture and Software Implementation, Seismol. Res. Lett., 86, no. 1, doi: 10.1785/0220140125. -Additional information describing how to cite specific methods implemented in the Broadband Platform is provided in more detail on the [acknowledgement page](./Acknowledging.md) +Additional information describing how to cite specific methods implemented in the Broadband Platform is provided in more detail on the [acknowledgement page](./Acknowledging) ### Broadband Platform Diagram diff --git a/doc/Installation.md b/doc/Installation.md index af0639ef..562b396e 100644 --- a/doc/Installation.md +++ b/doc/Installation.md @@ -4,15 +4,16 @@ Installing the Broadband Platform involves obtaining a copy of the code and buil The Broadband Platform has the following software dependencies in order to compile and run: -* Python v2.7.10+ with - * Matplotlib 1.4.3+ - * NumPy 1.14.2+ - * SciPy 1.0.0+ - * Pyproj 1.9.2+ -* GNU compilers (gcc, gfortran) 5.1.1+ - * FFTW library 3.3.4+ +* Python v3.6.7+ with + * Matplotlib 3.3.0+ + * NumPy 1.18.5+ + * SciPy 1.4.1+ + * Pyproj 2.6.1+ + * Numba 0.55.2+ +* GNU compilers (gcc, gfortran) 8.3+ + * FFTW library 3.3.8 -Please make sure they are installed in your computer before you continue with the BBP installation process. Depending on the specific NumPy, SciPy, and Matplotlib versions users installed in their systems, they may experience certain "Future Warning" messages while running the BBP. In this case, upgrading NumPy, SciPy, and/or Matplotlib will usually make the warning messages disappear. We used the package versions listed above to run the Unit and Acceptance tests. Please note that, at this time, the Broadband Platform is not compatible with Python 3. We expect to migrate the BBP to Python 3 in our next release. +Please make sure they are installed in your computer before you continue with the BBP installation process. Depending on the specific NumPy, SciPy, and Matplotlib versions users installed in their systems, they may experience certain "Future Warning" messages while running the BBP. In this case, upgrading NumPy, SciPy, and/or Matplotlib will usually make the warning messages disappear. We used the package versions listed above to run the Unit and Acceptance tests. ### Easy Installation @@ -38,7 +39,7 @@ As mentioned above, one option to obtain the Broadband Platform source distribut * Uncompress the downloaded file ``` - $ tar -xzf bbp-19.4.0.tar.gz + $ tar -xzf bbp-22.4.0.tar.gz ``` * Delete the tar.gz file as it will not be needed anymore (optional) @@ -48,7 +49,7 @@ As mentioned above, one option to obtain the Broadband Platform source distribut Another option is for users to clone the Broadband repository from GitHub using the following command: ``` - $ git clone https://github.com/SCECcode/bbp.git bbp-19.4.0 + $ git clone https://github.com/SCECcode/bbp.git bbp-22.4.0 ``` Either way, after one of the steps above users should have the Broadband Platform source distribution downloaded into their computers. Then, the next steps are: @@ -56,8 +57,8 @@ Either way, after one of the steps above users should have the Broadband Platfor * Run the easy installation script located in the setup sub-directory. ``` - $ cd bbp-19.4.0/setup - $ ./easy_install_bbp_19.4.0.sh + $ cd bbp-22.4.0/setup + $ ./easy_install_bbp_22.4.0.sh ``` The easy installation script will create a number of other directories inside your top-level bbp directory (/home/sarah/bbp). It will compile the codes in the BBP source distribution, and it will then ask the user which BBP packages should be installed. Each package contains a region (e.g. LA Basin, Northern California, etc). The user should select 1 (Yes) to install the package, or 2 (No) to skip it. Please note that the LA Basin region is required for running the Unit and Acceptance tests provided with the Broadband Platform. @@ -78,4 +79,24 @@ export PATH=/home/sarah/bbp/bbp-19.4.0/bbp/comps:/home/sarah/bbp/bbp-19.4.0/bbp/ ulimit -s unlimited ``` -After installing the Broadband Platform on their systems, users should confirm the code is built correctly by [running Unit and Acceptance Tests](./Running-Tests.md) before starting to use the code for research purposes. +After installing the Broadband Platform on their systems, users should confirm the code is built correctly by [running Unit and Acceptance Tests](./Running-Tests) before starting to use the code for research purposes. + + +### Using a User Response File +If you are performing repeated installations, you may want to put the required inputs into a file and run the installation as a script, something like the following: + +Create install_inputs.txt containing these lines: +1 +1 +1 +1 +1 +1 +1 + + +Then, in bbp setup directory: (e.g. /home/scec-00/maechlin/bbp/bbp/setup) + +./easy_install_bbp_22.4.0.sh < install_all_inputs.txt &> install_results.log & + +This will run the installation in the background without any users interactions, and will write stdout and error messages to the install_results.log file. diff --git a/doc/Methods-and-Modules.md b/doc/Methods-and-Modules.md index 976f882e..b0c3a1c5 100644 --- a/doc/Methods-and-Modules.md +++ b/doc/Methods-and-Modules.md @@ -8,33 +8,32 @@ All simulations must include some description of the source and a process by whi * Rupture generation (RG): GP, UCSB, EXSIM, SONG, Irikura Recipe * Low-frequency (LF): GP, UCSB, EXSIM -* High-frequency (HF): GP, UCSB, SDSU, EXSIM, Irikura Recipe -* Site response (SR): GP +* High-frequency (HF): GP, UCSB, SDSU, EXSIM, Irikura Recipe Method 2 +* Site response (SR): GP, PySeismoSoil ### Methods The BBP was originally designed to provide users with a wide flexibility on possible module (section above) combinations. However, the BBP evolved into suites of preferred module combinations, which we refer to as "methods". Currently, BBP users can compute simulations from any of 7 distinct methods (listed below with their associated modules). A brief summary of each method is provided in the PDFs linked below, which includes references pointing to more detailed publications: -* [Graves & Pitarka (GP): uses RG, LF, and HF from GP](pdfs/BBP-GP-2019-04-02.pdf) -* [SDSU: uses RG and LF from GP and HF from SDSU](pdfs/BBP-SDSU_2019-04-02.pdf) -* [UCSB: uses RG, LF, and HF from UCSB](pdfs/BBP-UCSB-2019-04-09.pdf) -* [EXSIM: uses RG, LF, and HF form EXSIM](pdfs/BBP-ExSIM-2019-04-09.pdf) -* [SONG: used RG from SONG; LF and HF from GP](pdfs/BBP-Song-2019-04-03.pdf) -* [Irikura Recipe Method 1: uses the RG from the Irikura Recipe; LF and HF from GP](pdfs/BBP-Irikura_Recipe_Method_1-2019-04-03.pdf) -* [Irikura Recipe Method 2: uses the RG and HF from the Irikura Recipe; LF from GP](pdfs/BBP-Irikura_Recipe_Method_2-2019-04-11.pdf) +* [Graves & Pitarka (GP): uses RG, LF, and HF from GP](pdfs/GP_method-20220216.pdf) +* [SDSU: uses RG and LF from GP and HF from SDSU](pdfs/SDSU_release_2022.pdf) +* [UCSB: uses RG, LF, and HF from UCSB](pdfs/UCSB_21.3_c.pdf) +* [EXSIM: uses RG, LF, and HF form EXSIM](pdfs/EXSIM_20220309_V2.pdf) +* [SONG: used RG from SONG; LF and HF from GP](pdfs/BBB-Song-2022-03-02.pdf) +* [Irikura Recipe Method 1: uses the RG from the Irikura Recipe; LF and HF from GP](pdfs/Irikura_Recipe_Method_1.2022.pdf) +* [Irikura Recipe Method 2: uses the RG and HF from the Irikura Recipe; LF from GP](pdfs/Irikura2_2022v4.pdf) * Composite Source Model (CSM - Under development) -There is currently one site response module (GP) and it is used for all the methods above, whenever site response is selected by the user. +There are currently two site response modules, GP and PySeismoSoil, which can be used by any of the simulation methods above, whenever site response is selected by the user. #### Post-processing Modules -A spectral response post-processing module is automatically run after the seismogram synthesis and the optional site response module are completed. For validation simulations, where simulated seismograms are compared against recorded data, users may select an optional goodness-of-fit (GoF) utility module to run at the conclusion of the simulation. The Broadband Platform currently supports both the GP and SDSU GoF modules and the users can select to run one, or both (or none) of these modules. Additionally, in validation simulations, users may also select to calculate the following optional metrics: +A spectral response post-processing module is automatically run after the seismogram synthesis and the optional site response module are completed. For validation simulations, where simulated seismograms are compared against recorded data, users may select an optional goodness-of-fit (GoF) utility module to run at the conclusion of the simulation. The Broadband Platform currently supports the GP, FAS, and SDSU GoF modules and the users can select to run one, two, all (or none) of these modules. Additionally, in validation simulations, users may also select to calculate the following optional metrics: * RZZ2015 Metrics -* Fourier Amplitude Spectrum (FAS) * Afshari and Stewart 2016 GMPE * RotD100 * Anderson GoF 2004 ### Software License -The Broadband Platform is open-source software that is made available under the terms of the Apache License, Version 2.0. A copy of the License is provided by the Apache Software Foundation (http://www.apache.org/licenses/LICENSE-2.0) and can also be found with the software in the 'LICENSE' file. +The SCEC-developed portions of the Broadband platform software is distributed under the terms of the BSD 3-Clause open-source license. Please see the LICENSE.txt file for more information. Individual models codes may be offered under their own open-source software licenses, please look for a LICENSE.txt file under specific sub folders in the 'src' directory for module-specific license information. diff --git a/doc/Release-Notes.md b/doc/Release-Notes.md index 3075f733..a99fb055 100644 --- a/doc/Release-Notes.md +++ b/doc/Release-Notes.md @@ -1,3 +1,25 @@ +### Broadband Platform 22.4.0 + +This is a full release of the Broadband Platform, and includes several major updates and bug fixes. Below is a summary of the improvements and changes included in this release of the Broadband Platform. + +#### Method updates + +* Included multi-segment rupture support for GP, SDSU, Irikura 1, Irikura 2, and Song simulation methods. Currently provided multi-segment validation events are Landers, Ridgecrest 19C, and San Simeon. + +* Updated GP low-frequency module (jbsim) to perform time-shifting in the time domain instead of frequency domain. This avoids calculating numerous FFTs and results in a significant processing speedup of 10x, and benefits all simulation modules that use the GP low-frequency code. + +* Modified UCSB simulation method to include support for double corner frequency (DCF) + +#### Other improvements + +* Included FAS validation module that produces FAS Goodness-of-Fitness plots, for a better seismological interpretation of the results. This is in addition to the PSA validation that is the main metric for design in engineering. + +* Updated the GP rupture generator to genslip-5.5.2 and the high-frequency code to hb_high_6.0.5. + +* Added Green's Functions and validation events for the Southern Walker Lane region (Southern Sierra Nevada) of California. Validation events include the 2019 Ridgecrest sequence. + +* Expanded the GP GoF module to include a Vs30 GoF plot (similar to the distance and map GoF plots) that can be used to show GoF bias related to stations' Vs30s. + ### Broadband Platform 19.4.0 This full release of the Broadband Platform includes several new features and bug fixes. Below is a summary of the improvements and modifications included in this release of the Broadband Platform. diff --git a/doc/Running-Simulations.md b/doc/Running-Simulations.md index f515f0f9..a2771e48 100644 --- a/doc/Running-Simulations.md +++ b/doc/Running-Simulations.md @@ -10,9 +10,9 @@ The platform can be run in multiple modes. The default is interactive mode, in w For a large number of runs, or if the user is repeating a specific run, this can be tedious. The platform provides two other ways to describe a run, with an option file or an XML description. -An option file provides responses to all the questions that the platform poses. The format is described in [File Formats](./File-Format-Guide.md), but it's basically a text file, 1 entry per line, with support for comments. It can be fed to the platform using the -o option. +An option file provides responses to all the questions that the platform poses. The format is described in [File Formats](./File-Format-Guide), but it's basically a text file, 1 entry per line, with support for comments. It can be fed to the platform using the -o option. -The platform will also accept XML files containing a full description of a run. The schema for these files is given in [File Formats](./File-Format-Guide.md). These files are also produced by the platform after every simulation, and placed in xml/.xml. So if you want to rerun a simulation, you can point the platform to the XML file from that simulation using the '-x' option. Note that a new simulation ID will be assigned to the run, so there is no risk of overwriting previous simulation results. +The platform will also accept XML files containing a full description of a run. The schema for these files is given in [File Formats](./File-Format-Guide). These files are also produced by the platform after every simulation, and placed in xml/.xml. So if you want to rerun a simulation, you can point the platform to the XML file from that simulation using the '-x' option. Note that a new simulation ID will be assigned to the run, so there is no risk of overwriting previous simulation results. ### Available Options @@ -42,7 +42,7 @@ To run a validation simulation, go to the data/run directory and run run_bbp.py. ``` $ run_bbp.py - Welcome to the SCEC Broadband Platform version 19.4.0. + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -63,15 +63,15 @@ To run a validation simulation, go to the data/run directory and run run_bbp.py. ... ``` -No input files are required by the user. However, you may wish to customize the validation simulation by selecting an alternate source description (src file) or a reduced station list to speed up the computations. You can put your own source description and/or station list into the run directory (the format is described in [File Formats](./File-Format-Guide.md)) or you can tell the platform where each file is located by using an absolute path. Note that any stations which do not have observed seismograms will not be included in the automatically generated goodness-of-fit comparison. To supply alternative source description and/or station list files, please run the Broadband Platform in 'expert' mode using the '--expert' command-line flag. +No input files are required by the user. However, you may wish to customize the validation simulation by selecting an alternate source description (src file) or a reduced station list to speed up the computations. You can put your own source description and/or station list into the run directory (the format is described in [File Formats](./File-Format-Guide)) or you can tell the platform where each file is located by using an absolute path. Note that any stations which do not have observed seismograms will not be included in the automatically generated goodness-of-fit comparison. To supply alternative source description and/or station list files, please run the Broadband Platform in 'expert' mode using the '--expert' command-line flag. ### User-defined Simulations -To run a user-defined simulation, two input files are required, a source description (src file) and a station list (stl file). A simple source description (src file) is always required, but, for certain methods, a source description in SRF format (the format is described in [File Formats](./File-Format-Guide.md) can be supplied as well and will be used for the seismogram computation modules in the Broadband Platform. To run a user-defined simulation, run run_bbp.py: +To run a user-defined simulation, two input files are required, a source description (src file) and a station list (stl file). A simple source description (src file) is always required, but, for certain methods, a source description in SRF format (the format is described in [File Formats](./File-Format-Guide) can be supplied as well and will be used for the seismogram computation modules in the Broadband Platform. To run a user-defined simulation, run run_bbp.py: ``` $ run_bbp.py - Welcome to the SCEC Broadband Platform version 19.4.0. + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -135,7 +135,7 @@ To help visualize the stations in relationship to the fault, the platform produc When running the Broadband Platform, you have the option to generate plots of velocity and acceleration seismograms for each station. Plots of these files can be found in `outdata//.__seis.png`. -The raw seismogram data is available in `outdata//..vel.bbp` (velocity) and `outdata/..acc.bbp` (acceleration). Its format is described in [File Formats](./File-Format-Guide.md). +The raw seismogram data is available in `outdata//..vel.bbp` (velocity) and `outdata/..acc.bbp` (acceleration). Its format is described in [File Formats](./File-Format-Guide). #### Response Spectra @@ -145,7 +145,7 @@ The RotD50 code, run during each simulation, calculates the response spectra for outdata//..rd50 ``` -in the format described in [File Formats](./File-Format-Guide.md). +in the format described in [File Formats](./File-Format-Guide). #### Goodness-of-fit @@ -171,7 +171,7 @@ You don't need to move any files for this example. Notice that we will be using ``` $ run_bbp.py - Welcome to the SCEC Broadband Platform version 19.4.0 + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -206,14 +206,14 @@ You don't need to move any files for this example. Notice that we will be using ================================================================================ SRC file: /home/sarah/bbp/bbp_val/Northridge/common/nr_v14_02_1.src ================================================================================ - STL file: /home/sarah/bbp/bbp_val/Northridge/common/nr_v19_02_1.stl + STL file: /home/sarah/bbp/bbp_val/Northridge/common/nr_v19_06_2.stl -------------------------------------ExSIM-------------------------------------- ==> Running ExSIM... ... ``` -This simulation should take about 30 minutes (as opposed to about 12+ hours if using some of the other methods). Once it completes, the platform will tell you: +This simulation will take about 90 minutes to complete, or possibly more depending on how fast the computer is. Some of the other methods can take longer (and some up to about 12+ hours). Once the simulation completes, the platform will tell you: ``` You can find results in $BBP_DATA_DIR/outdata/ @@ -233,7 +233,7 @@ In that directory you will find: #### Sample Northridge Validation simulation, custom station list -Validation runs can take a long time. The time needed to generate each low-frequency seismogram will generally increase with the magnitude of the event, taking more than 1 hour per station for earthquakes with Mw > 7.2. Sometimes you might want to run with a reduced station list so the simulation will run faster. +Validation runs can take a long time. The time needed to generate each seismogram will generally increase with the magnitude of the event, potentially taking more than 1 hour per station for earthquakes with Mw > 7.2 for some of the simulation methods. Some of the post-processing modules, especially the FAS module, will also take a while to process each of the stations on the station list. Sometimes you might want to run with a reduced station list so the simulation will run faster. Copy the station list from `$BBP_DIR/../doc/examples/northridge_3_stations` into the run directory, which should be `$BBP_DATA_DIR/run`. Take a look at the format of the station file: @@ -250,7 +250,7 @@ Now, run the platform using a different station list. To do this, you will need ``` $ run_bbp.py --expert - Welcome to the SCEC Broadband Platform version 19.4.0. + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -291,7 +291,7 @@ Now, run the platform using a different station list. To do this, you will need Do you want to provide a custom source file (y/n)? n ================================================================================ - SRC file: /home/sarah/bbp/bbp_val/NR/common/nr_v14_02_1.src + SRC file: /home/sarah/bbp/bbp_val/NR/gp/nr_v20_07_1.src ================================================================================ When starting a simulation from a source description (SRC) file, the Broadband @@ -334,6 +334,11 @@ You will see a list of station list files that you have in your run directory. F the Vs30 values for each station location. Do you want to run the site response module (y/n)? y + + Please select a site response module to use in this Broadband simulation: + (1) GP (Graves & Pitarka) + (2) PySeismoSoil + ? 1 ================================================================================ Do you want to generate velocity seismograms' plots (y/n)? y ================================================================================ @@ -368,9 +373,10 @@ You will see a list of station list files that you have in your run directory. F Choose a Goodness of Fit (GOF) Module: (1) GP - (2) SDSU - (3) Both - ? 1 + (2) FAS + (3) GP and SDSU + (4) GP and FAS + ? 4 ================================================================================ Additional Metrics @@ -381,15 +387,15 @@ You will see a list of station list files that you have in your run directory. F Do you want to calculate additional metrics (y/n)? n ``` -Again, when the run completes, in about 30-45 minutes, you can find results in the output directory. You'll notice far fewer files, as only 3 stations were used instead of 40. The goodness-of-fit plots won't look very good - more stations are really needed to get an accurate plot. In the `$BBP_DIR/../doc/examples/northridge_3_stations/results` directory you will find pre-calculated results for a few of the methods (GP and UCSB). You should obtain results equivalent to those. +Again, when the run completes, in about 10-20 minutes, you can find results in the output directory. You'll notice far fewer files, as only 3 stations were used instead of 40. The goodness-of-fit plots won't look very good - more stations are really needed to get an accurate plot. In the `$BBP_DIR/../doc/examples/northridge_3_stations/results` directory you will find pre-calculated results for a few of the methods (GP and UCSB). You should obtain results equivalent to those. #### Sample User-defined Southern California simulation with source description -Next let's try running a user-defined event. Copy the files `$BBP_DIR/../doc/examples/scenario_1_station/nr_one_stat.stl` and `$BBP_DIR/../doc/examples/scenario_1_station/user_eq.src` to the `$BBP_DATA_DIR/run` directory. user_eq.src is a simple source description. Its format is outlined in [File Formats](./File-Format-Guide.md). +Next let's try running a user-defined event. Copy the files `$BBP_DIR/../doc/examples/scenario_1_station/nr_one_stat.stl` and `$BBP_DIR/../doc/examples/scenario_1_station/user_eq.src` to the `$BBP_DATA_DIR/run` directory. user_eq.src is a simple source description. Its format is outlined in [File Formats](./File-Format-Guide). ``` $ run_bbp.py - Welcome to the SCEC Broadband Platform version 19.4.0. + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -463,7 +469,7 @@ Since we are running a Southern California event, we select the LABasin velocity ... ``` -Since this run only includes one station, it will run in about 5-10 minutes. In the output directory you'll notice there are no goodness-of-fit or files, since this is not a validation simulation. However, there is a map file (station_map.png), showing the fault plane and the station, and a plot of the rupture slip (user_eq.png). The SRF generated by the rupture generator is in user_eq.srf; this file could be used in future runs. The filenames of the rupture slip plot and SRF are taken from the rupture description filename. +Since this run only includes one station, it will run in about 2-10 minutes. In the output directory you'll notice there are no goodness-of-fit or files, since this is not a validation simulation. However, there is a map file (station_map.png), showing the fault plane and the station, and a plot of the rupture slip (user_eq.png). The SRF generated by the rupture generator is in user_eq.srf; this file could be used in future runs. The filenames of the rupture slip plot and SRF are taken from the rupture description filename. #### Custom Southern California validation event with user-provided source description @@ -473,7 +479,7 @@ First, we will run the standard Chino Hills validation event, for which we do no ``` $ run_bbp.py - Welcome to the SCEC Broadband Platform version 19.4.0 + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -508,13 +514,13 @@ First, we will run the standard Chino Hills validation event, for which we do no ================================================================================ SRC file: /home/sarah/bbp/bbp_val/ChinoHills/common/ch_v14_2_2.src ================================================================================ - STL file: /home/sarah/bbp/bbp_val/ChinoHills/common/ch_v19_02_1.stl + STL file: /home/sarah/bbp/bbp_val/ChinoHills/common/ch_v19_06_2.stl --------------------------GP Rupture Generator GenSlip-------------------------- ... ``` -This simulation should take about 60-90 minutes, once it completes, the platform will tell you: +This simulation should take about 3-4 hourds, once it completes, the platform will tell you: ``` You can find results in $BBP_DATA_DIR/outdata/ @@ -522,7 +528,7 @@ This simulation should take about 60-90 minutes, once it completes, the platform We will now inspect the results. The html file is helpful to display all the results in an organized way. There should be a goodness-of-fit plot, a station map plot, and a rupture plot showing the slip distribution, followed by per-station results with acceleration and velocity seismograms and other comparison plots. Please take a look at the goodness-of-fit plot. It should be similar to the one available in the `$BBP_DIR/../doc/examples/chino_hills_larger_mag/results` directory for the default 5.39 magnitude used in Chino Hills, and also shown below: -![Goodness-of-Fit Plot for Mag 5.39 Chino Hills event](images/gof-CHINOH-6917077_r0-180-rd50.png) +![Goodness-of-Fit Plot for Mag 5.39 Chino Hills event](images/gof-CHINOH-1127156_r0-180-rd50.png) As an exercise (and for no scientific purpose whatsoever), we will modify the magnitude used for Chino Hills and see what happens to the results. We will increase the magnitude from 5.39 to 5.60. There is already a simple source description file with this modification in the `$BBP_DIR/../doc/examples/chino_hills_larger_mag` directory: @@ -558,7 +564,7 @@ Please note the modification at the top, where magnitude was increased from 5.39 ``` $ run_bbp.py --expert - Welcome to the SCEC Broadband Platform version 19.4.0. + Welcome to the SCEC Broadband Platform version 22.4.0. ================================================================================ Please select the Broadband Platform mode of operation: @@ -635,7 +641,7 @@ This is the only customization we want to make to this simulation, so just finis (2) provide a custom list with a subset of the stations ? 1 ================================================================================ - STL file: /home/sarah/bbp/bbp_val/ChinoHills/common/ch_v19_02_1.stl + STL file: /home/sarah/bbp/bbp_val/ChinoHills/common/ch_v19_06_2.stl ================================================================================ Site Response @@ -645,6 +651,11 @@ This is the only customization we want to make to this simulation, so just finis for each station location. Do you want to run the site response module (y/n)? y + + Please select a site response module to use in this Broadband simulation: + (1) GP (Graves & Pitarka) + (2) PySeismoSoil + ? 1 ================================================================================ Do you want to generate velocity seismograms' plots (y/n)? y ================================================================================ @@ -671,8 +682,9 @@ This is the only customization we want to make to this simulation, so just finis Choose a Goodness of Fit (GOF) Module: (1) GP - (2) SDSU - (3) Both + (2) FAS + (3) GP and SDSU + (4) GP and FAS ? 1 ================================================================================ @@ -686,7 +698,7 @@ This is the only customization we want to make to this simulation, so just finis --------------------------GP Rupture Generator GenSlip-------------------------- ``` -This simulation should again take about 60-90 minutes, once it completes, the platform will tell you: +Note that because we selected only the GP GoF module, this simulation will run much faster, it should take about 15-30 minutes to complete. Once the Platform finishes, it will tell you: ``` You can find results in $BBP_DATA_DIR/outdata/ @@ -694,6 +706,6 @@ This simulation should again take about 60-90 minutes, once it completes, the pl Now that the simulation is finishes, we can go to the 'outdata' directory printed at the end of the run and look at the results. As before, we can open the html file for a more organized display of the results. Open the goodness of fit plot for this second simulation and compare it against the one we obtained before using the unmodified source description file. The new goodness of fit plot should be similar to the one available in the `$BBP_DIR/../doc/examples/chino_hills_larger_mag/results` directory for the modified Chino Hills event with magnitude 5.60, also shown below: -![Goodness-of-Fit Plot for Mag 5.60 Chino Hills event](images/gof-CHINOH-6916980_r0-180-rd50.png) +![Goodness-of-Fit Plot for Mag 5.60 Chino Hills event](images/gof-CHINOH-1147143_r0-180-rd50.png) When comparing the results for the 5.39 and 5.60 magnitudes against each other we can see the the changes to the goodness of fit plot. The red line appears lower for the higher magnitude simulation as a result of the higher ground motion intensity. diff --git a/doc/Running-Tests.md b/doc/Running-Tests.md index fbd99ddf..611795b9 100644 --- a/doc/Running-Tests.md +++ b/doc/Running-Tests.md @@ -7,7 +7,7 @@ Unit tests are designed to test each module separately, using a set of input fil In order to run the unit tests, users should go to the tests directory and type: ``` - $ cd /home/sarah/bbp/19.4.0/bbp/tests + $ cd /home/sarah/bbp/22.4.0/bbp/tests ``` We recommend you run the Unit and Acceptance tests in the background using a command like: @@ -49,12 +49,16 @@ Once the unit tests all pass, proceed to the acceptance tests. If there are any test_bbp2peer (test_bbp_format.TestBBPFormat) ... ok test_exsim2bbp (test_bbp_format.TestBBPFormat) ... ok test_peer2bbp (test_bbp_format.TestBBPFormat) ... ok + test_pynga_ngae (test_pynga.TestPyNGA) ... ok + test_pynga_ngaw1 (test_pynga.TestPyNGA) ... ok + test_pynga_ngaw2 (test_pynga.TestPyNGA) ... ok test_vm2ucsb (test_vm2vm.TestVm2vm) ... ok test_vm2ucsb_nga (test_vm2vm.TestVm2vm) ... ok test_vm2vm (test_vm2vm.TestVm2vm) ... ok test_vm2vm_nga (test_vm2vm.TestVm2vm) ... ok test_xy2ll (test_cc.TestCC) ... ok test_genslip (test_genslip.TestGenslip) ... ok + test_genslip_fftw (test_genslip.TestGenslip) ... ok test_jbsim (test_jbsim.TestJbsim) ... ok test_hfsims (test_hfsims.TestHfsims) ... ok test_wcc_siteamp (test_wcc_siteamp.TestWccSiteamp) ... ok @@ -71,15 +75,18 @@ Once the unit tests all pass, proceed to the acceptance tests. If there are any test_rotd50 (test_rotd50.TestRotD50) ... ok test_rotd100 (test_rotd100.TestRotD100) ... ok test_gof (test_gp_gof.TestGPGof) ... ok + test_fas (test_fas.TestFAS) ... ok + test_fas_gof (test_fas_gof.TestFASGof) ... ok test_mogof_stat (test_sdsu_mogof.TestSDSUMOGof) ... ok test_anderson_gof (test_anderson_gof.TestAndersonGof) ... ok test_rzz2015 (test_rzz2015.TestRZZ2015) ... ok test_as16 (test_as16.TestAS16) ... ok + test_as16_testcases (test_as16.TestAS16) ... ok ----------------------------------------------------------------------- -Ran 36 tests in 1455.138s + ---------------------------------------------------------------------- + Ran 43 tests in 930.941s -OK + OK ``` ### Running Acceptance Tests @@ -87,7 +94,7 @@ OK Make sure the unit tests pass before moving on to the acceptance tests. To run the acceptance tests, users should: ``` - $ cd /home/sarah/bbp/19.4.0/bbp/tests + $ cd /home/sarah/bbp/22.4.0/bbp/tests ``` To run the acceptance tests in a terminal background process, on a Linux computer, the following command will run the tests as a background process, and redirect stderr and stdout to a "accept_tests.log" file. @@ -128,8 +135,7 @@ Here is an example output from the tests.log file created by running this comman test_valid-northridge-UCSB (__main__.BBPAcceptanceTests) ... ok ---------------------------------------------------------------------- - Ran 14 tests in 25981.848s - + Ran 14 tests in 9199.326s OK ``` diff --git a/doc/Utilities.md b/doc/Utilities.md index 7839cf31..36406a43 100644 --- a/doc/Utilities.md +++ b/doc/Utilities.md @@ -4,7 +4,7 @@ This page contains a brief description of the utilities included in the Broadban ### Plotting velocity models -The 'plot_velocity_model.py' tool included in the 'utils/misc' directory can be used to create 1D velocity profile plots of the velocity models included with the Broadband Platform. It uses as input a velocity model profile in the format specified in the [File Formats](./File-Format-Guide.md). In addition to the output plot file (in PNG format), users can also specify a title for the plot. For example: +The 'plot_velocity_model.py' tool included in the 'utils/misc' directory can be used to create 1D velocity profile plots of the velocity models included with the Broadband Platform. It uses as input a velocity model profile in the format specified in the [File Formats](./File-Format-Guide). In addition to the output plot file (in PNG format), users can also specify a title for the plot. For example: ``` $ plot_velocity_model.py -v nr02-vs500.fk1d -o labasin500.png -t "LA Basin 500" @@ -12,9 +12,9 @@ The 'plot_velocity_model.py' tool included in the 'utils/misc' directory can be ### Multi-segment scripts -The Broadband Platform includes 4 methods that are able to run simulations containing a rupture composed of multiple planes or segments. The SONG and Irikura Recipe Method 1 methods are able to read multiple simple source description (SRC) files, each containing information about one rupture segment, and create a multi-segment, version 2.0 SRF file that can be used by other modules in the Broadband Platform to compute synthetic seismograms. When running a multi-segment validation event with these two methods, users do not need to do anything different than what they do for single segment events. +The Broadband Platform includes 5 methods that are able to run simulations containing a rupture composed of multiple planes or segments. The GP, SDSU, SONG, Irikura Recipe Method 1, and Irikura Recipe Method 2 methods are able to read multiple simple source description (SRC) files, each containing information about one rupture segment, and create a multi-segment, version 2.0 SRF file that can be used by other modules in the Broadband Platform to compute synthetic seismograms. When running a multi-segment validation event with these methods, users do not need to do anything different than what they do for single segment events. -The GP and SDSU methods are also able to calculate ground motions for multi-segment ruptures. However, at this time, this is done one segment at a time. Users will need to run each segment separately and then merge the results of all segments into a multi-segment simulation. This is done with two merge scripts available in 'utils/misc', merge_multisegment_validation.py and merge_multisegment_scenario.py. +It is also possible to calculate ground motions from a multi-segment rupture one segment at a time. This can be used to calculate the contribution of each segment to the overall ground motions, or during the development and debugging of simulation methods. In order to do this, users will need to run each segment separately and then merge the results of all segments into a multi-segment simulation. This is done with two merge scripts available in 'utils/misc', merge_multisegment_validation.py and merge_multisegment_scenario.py. Users can use the '--help' flag to see the command-line options in more detail but, basically, users will need to provide a list of the simulation IDs of each of the individual segments so the script will read the data and combine the results. For example, in the 1992 Landers earthquake model with 3 separate segments, users will first need to run the Broadband Platform 3 times (once for each of the segments). With multi-segment validation packages the Platform will ask the user which segment the user wants to use. Then, results can be merged with the following command: @@ -24,25 +24,25 @@ Users can use the '--help' flag to see the command-line options in more detail b In the example above, we assume that Landers segments 1, 2, and 3 were calculated and their simulation ids are 101, 102, and 103, respectively. The merge tool will combine the simulations under simulation id 104. -### Cluter scripts +### Cluster scripts -The 'bbp_hpcc_validation.py' and 'bbp_hpcc_scenario.py' tools, available in 'utils/batch' are used to run Broadband Platform validation and scenario simulations on the USC's HPC cluster. The scripts are specific to the USC cluster and use the Slurm job scheduler and file systems specific to it. It is our hope that users can adapt these scripts without too much effort to work on other computing environments. +The 'bbp_discovery_validation.py' and 'bbp_discovery_scenario.py' tools, available in 'utils/batch' are used to run Broadband Platform validation and scenario simulations on the USC's CARC cluster. The scripts are specific to the USC cluster and use the Slurm job scheduler and file systems specific to it. It is our hope that users can adapt these scripts without too much effort to work on other computing environments. Each script includes several command-line options that allow users to customize their simulations but, basically, for validation simulations, users will need to specify a simulation method, the validation event, the number of realizations (or simulation variations) to run, whether to use the site response module or not, a simulation directory, certain randomization parameters, and an e-mail address so the user is notified when the job starts and finishes. For example: ``` - $ bbp_hpcc_validation.py -s -c gp -e tottori -n 50 --email --no-hypo-rand -d gp-tottori-50r + $ bbp_discovery_validation.py -s -c gp -e tottori -n 64 --email --no-hypo-rand -d gp-tottori-64r ``` -The above command creates 50 realizations for the Tottori event using the 'GP' simulation method. It includes the site response module in the simulations and disables the randomization of the hypocenter (each of the 50 simulations will still include a different slip distribution and random seed). The tool will create 50 realizations of the simulation in the 'gp-tottori-50r' folder and will print the Slurm command users need to type to submit the simulation to the cluster. +The above command creates 64 realizations for the Tottori event using the 'GP' simulation method. It includes the site response module in the simulations and disables the randomization of the hypocenter (each of the 50 simulations will still include a different slip distribution and random seed). The tool will create 50 realizations of the simulation in the 'gp-tottori-64r' folder and will print the Slurm command users need to type to submit the simulation to the cluster. For scenario simulations, instead of providing a validation event users provide a source description file, a station list, and a simulation region. For example: ``` - $ bbp_hpcc_scenario.py -c exsim -n 50 -v LABasin500 --src --stl --email --hypo-rand -d exsim-my-rup-50r + $ bbp_discovery_scenario.py -c exsim -n 64 -v LABasin500 --src --stl --email --hypo-rand -d exsim-my-rup-64r ``` -Similarly, the tool will generate 50 realizations for the source description and station list specified in the command-line flags in the 'exsim-my-rup-50r' and will print the Slurm command users need to type to submit the simulation to the cluster. +Similarly, the tool will generate 64 realizations for the source description and station list specified in the command-line flags in the 'exsim-my-rup-64r' and will print the Slurm command users need to type to submit the simulation to the cluster. Each script includes several options that allow users to customize the simulation, please use the '--help' flag for a complete list of the available options. @@ -51,7 +51,7 @@ Each script includes several options that allow users to customize the simulatio When used with a cluster validation simulation, the 'compare_bbp_runs.py' tool (available in 'utils/batch') can be used to compare the different realizations and rank them on how well each one matches the observed data. It takes only the top-level simulation directory (as specified with the '-d' in the cluster scripts above). For example: ``` - $ compare_bbp_runs.py gp-nr-50r + $ compare_bbp_runs.py gp-nr-64r Simulation Average Bias 10000022 0.077551 10000006 0.099381 @@ -65,41 +65,41 @@ When used with a cluster validation simulation, the 'compare_bbp_runs.py' tool ( 10000020 0.192202 ``` -In the output above, the 50 realizations in 'gp-nr-50r' are ranked from best to worst based on their Average Bias. In this case, the best realization is number 10000022 with a 0.077551 average bias and the worst is realization 10000020 with an average bias of 0.192202. +In the output above, the 64 realizations in 'gp-nr-64r' are ranked from best to worst based on their Average Bias. In this case, the best realization is number 10000022 with a 0.077551 average bias and the worst is realization 10000020 with an average bias of 0.192202. ### Multi-segment cluster runs Multi-segment simulations outside of the cluster environment were described above. For cluster simulations, the same validation and scenario cluster scripts used for single-segment cluster simulations can also be used to run multi-segment runs. Multi-segment simulations include multiple source description (SRC) files, one for each rupture segment. At this time on the Broadband Platform, there are two methodologies for calculating seismograms from multi-segment ruptures. -#### SONG and Irikura Recipe Method 1 +#### Computing ground motions for all segments together -The SONG and Irikura Recipe Method 1 methods compute a single version 2.0 extended rupture SRF file containing data from all SRC files. When simulations complete, they contain the final result of all segments combined, and nothing else is needed. For these two methods, please use the same cluster scripts listed above, without any changes to the usage. +The GP, SDSU, SONG, Irikura Recipe Method1, and Irikura Recipe Method 2 methods compute a single version 2.0 extended rupture SRF file containing data from all SRC files. When simulations complete, they contain the final result of all segments combined, and nothing else is needed. For these two methods, please use the same cluster scripts listed above, without any changes to the usage. -#### Other simulation methods +#### Calculating segments separately -Other simulation methods that support multi-segment simulations are the GP and SDSU methods. For these two methods however, each rupture segment needs to be calculated separately and all segments need to be merged later. For example, the multi-segment version of the 1992 Landers earthquake contains 3 segments. They can be calculated with the following commands: +For the methods above, it is also possible to compute the segments separately. In this case, each rupture segment needs to be calculated separately and all segments need to be merged later. For example, the multi-segment version of the 1992 Landers earthquake contains 3 segments. They can be calculated with the following commands: ``` - $ bbp_hpcc_validation.py -c gp -e "Landers Multi Segment" -n 50 --email --no-hypo-rand -d gp-landers1-50r -s --segment 1 + $ bbp_discovery_validation.py -c gp -e "Landers Multi Segment" -n 64 --email --no-hypo-rand -d gp-landers1-64r -s --segment 1 ``` ``` - $ bbp_hpcc_validation.py -c gp -e "Landers Multi Segment" -n 50 --email --no-hypo-rand -d gp-landers2-50r -s --segment 2 --variation 2 --first-seg gp-landers1-50r + $ bbp_discovery_validation.py -c gp -e "Landers Multi Segment" -n 64 --email --no-hypo-rand -d gp-landers2-64r -s --segment 2 --variation 2 --first-seg gp-landers1-64r ``` ``` - $ bbp_hpcc_validation.py -c gp -e "Landers Multi Segment" -n 50 --email --no-hypo-rand -d gp-landers3-50r -s --segment 3 --variation 3 --first-seg gp-landers1-50r + $ bbp_discovery_validation.py -c gp -e "Landers Multi Segment" -n 64 --email --no-hypo-rand -d gp-landers3-64r -s --segment 3 --variation 3 --first-seg gp-landers1-64r ``` -With each of the command above, the Broadband Platform will create 50 realizations for each of the 3 rupture segments in the 1992 Landers earthquake. Users will be prompted to type the 'sbtach' command to submit each of these simulations to the cluster. Please note that simulations for segments 2 and 3 use information in the segment 1 simulation (the random seed in the first segments' source description file) so that certain randomized simulation parameters (e.g. rupture velocity) remain consistent across all segments. +With each of the command above, the Broadband Platform will create 64 realizations for each of the 3 rupture segments in the 1992 Landers earthquake. Users will be prompted to type the 'sbtach' command to submit each of these simulations to the cluster. Please note that simulations for segments 2 and 3 use information in the segment 1 simulation (the random seed in the first segments' source description file) so that certain randomized simulation parameters (e.g. rupture velocity) remain consistent across all segments. After all simulation complete, users will need to merge the results for the three segments into a single Broadband Platform simulation, using the 'bbp_merge_multisegment_validation.py' tool available in the 'utils/batch' folder. For the Landers example above with the 3 segments, users can type: ``` - $ bbp_merge_multisegment_validation.py -d gp-landers-ms-50r -e "Landers Multi Segment" gp-landers1-50r gp-landers2-50r gp-landers3-50r + $ bbp_merge_multisegment_validation.py -d gp-landers-ms-64r -e "Landers Multi Segment" gp-landers1-64r gp-landers2-64r gp-landers3-64r ``` -For each of the 50 realizations, the command above will merge the synthetic seismograms and then compute the post-processing analysis steps. This process can take several hours. +For each of the 64 realizations, the command above will merge the synthetic seismograms and then compute the post-processing analysis steps. This process can take several hours. ### Convergence @@ -108,3 +108,200 @@ The 'bbp_converge.py' tool included in the 'utils/batch' directory can be used w ``` $ bbp_converge.py --ns 1000 -i -o -c ``` + +### Importing Simulation Data + +The "import_bbp_simulation.py" tool included in the "utils/misc" folder can be used to import a set of simulation results calculated outside of the BBP into the Platform for post-processing. For example, users can compute simulation results using a method outside of the BBP and then run the standard BBP post-processing tools to compare their results against recorded data from one of the BBP validation events. For a list of validation events available on the Platform, please refer to folders inside the $BBP_VAL directory. + +The first step in running the Broadband Platform to process data calculated outside of the BBP is to import the simulated data and convert it to the format expected by the BBP. Users can use the "import_bbp_simulation.py" tool available in the "utils/misc" directory to perform some of these steps. The tool assumes the seismograms are already in BBP format but need to be renamed and copied into a simulation directory. + +The command-line options available for the "import_bbp_simulation.py" tool are: + +``` + $ import_bbp_simulation.py --help + usage: import_bbp_simulation.py [-h] --sim_id SIM_ID --src_file SRC_FILE + --station_list STATION_LIST --input_dir + INPUT_DIR [--prefix PREFIX] [--suffix SUFFIX] + + Create a BBP simulation from a set of seismograms. + + optional arguments: + -h, --help show this help message and exit + --sim_id SIM_ID simulation id + --src_file SRC_FILE, --src SRC_FILE + src file + --station_list STATION_LIST, --stl STATION_LIST + station list + --input_dir INPUT_DIR, -i INPUT_DIR + input directory + --prefix PREFIX, -p PREFIX + prefix for input files + --suffix SUFFIX, -s SUFFIX + suffix for input files +``` + +The tool assumes users have a folder containing velocity and acceleration files for a set of stations. It provides some flexibility on the naming but velocity and acceleration filenames will need to follow the format: + +``` + .vel.bbp and .acc.bbp +``` + +The prefix and suffix can be specified using command-line options and are optional. The station_names need to match the station names from the station list. The tool will parse the station list and look for both velocity and acceleration files for each station -- both are required. If users have simulated data for all stations for a validation event, they can simply use the station list file already available in the validation package. If data is available for only a subset of stations, users will first need to make a copy of the station list and edit it to delete stations not included in the simulation set. + +Once users have set up their station list (or confirmed that the station list from the validation event matches the data that is available), users can run the "import_bbp_simulation.py" tool. The tool will copy the input files and create a simulation folder for this simulation. + +As an example, assuming the Landers validation event, an input folder named "my_sims" and a "p-" prefix and a "-model1" suffix, users can run the tool with: + +``` + $ import_bbp_simulation.py --prefix "p-" --suffix="-model1" --input_dir my_sims + --src_file $BBP_VAL/Landers/common/landers_v14_02_1.src + --station_list $BBP_VAL/Landers/common/landers_v19_06_2.stl --sim_id 20200501 +``` + +Please note the equal and extra quotes for the suffix parameter as the name starts with a dash. Also, please make sure the BBP_DATA_DIR variable is set up before running the tool so that the files can be copied to the right place. The value provided for the sim_id needs to be unique (not one from a previously ran simulation). + +Once the simulation files are copied, users will need to run the BBP. This will be a two-step process. First, users will need to create an XML file for the simulation. Users can run the BBP with the following command-line options: + +``` + $ run_bbp.py -g --expert +``` + +The "-g" flag tells the BBP not to run the simulation itself, only generate the XML file. The "--expert" flag may be used to customize the simulation parameters (e.g. selecting a custom station file). Here's one example of running the Broadband Platform with the Landers validation event: + +``` + $ run_bbp.py --expert -g + Welcome to the SCEC Broadband Platform version 22.4.0. + ================================================================================ + + Please select the Broadband Platform mode of operation: + * Validation - Simulates a historical event + * Scenario - Runs a user-defined hypothetical event + + Do you want to perform a validation simulation (y/n)? y + ================================================================================ + + Please select a validation event from the list below: + + (1) Alum Rock + (2) Chino Hills + (3) Landers + (4) NR + (5) North Palm Springs + (6) Parkfield + (7) SanSimeon + (8) Whittier + ? 3 + ================================================================================ + + The Broadband Platform includes several scientific methods that can be used + to calculate synthetic seismograms. + + Choose a Method to use in this Broadband validation simulation: + (1) GP (Graves & Pitarka) + (2) UCSB + (3) SDSU + (4) EXSIM + (5) Song + (6) Irikura Recipe Method 1 (Irikura1) + (7) Irikura Recipe Method 2 (Irikura2) + ? 1 + ================================================================================ + + Each validation package includes a default source description (SRC) file for a + historical event. Would you like to provide a different file instead of the default + file provided? Answer 'no' here if you would like to use the standard source + file for this event. + + Do you want to provide a custom source file (y/n)? n + ================================================================================ + SRC file: /home/jane/bbp/bbp_val/Landers/common/landers_v14_02_1.src + ================================================================================ + + When starting a simulation from a source description (SRC) file, the Broadband + Platform workflow should include a rupture generator. Answer 'yes' here unless + providing a complex Standard Rupture Format (SRF) file. + + Do you want to run the rupture generator (y/n)? y + ================================================================================ + + Station Selection + ================= + Would you like to: + (1) generate seismograms for all stations in the validation package + OR + (2) provide a custom list with a subset of the stations + ? 1 + ================================================================================ + STL file: /home/jane/bbp/bbp_val/Landers/common/landers_v19_06_2.stl + ================================================================================ + + Site Response + ============= + Running a site response module is an optional step while running a Broadband + Platform simulation. It requires a station list file containing the Vs30 values + for each station location. + + Do you want to run the site response module (y/n)? y + + Please select a site response module to use in this Broadband simulation: + (1) GP (Graves & Pitarka) + (2) PySeismoSoil + ? 1 + ================================================================================ + Do you want to generate velocity seismograms' plots (y/n)? y + ================================================================================ + Do you want to generate acceleration seismograms' plots (y/n)? y + ================================================================================ + + The Broadband Platform can generate comparison plots of the validation data + against GMPEs to show how GMPEs match the recorded data for a certain event. + + Do you want to generate a GMPE comparison plot (y/n)? y + ================================================================================ + + Please select a GMPE set to use in the comparison (number of name are ok): + + (1) CENA GROUP 1 + (2) NGA-West1 + (3) NGA-West2 + ? 3 + ================================================================================ + + Goodness-of-Fit Plot + ==================== + Running a goodness-of-fit (GoF) module is an optional step while running a + Broadband Platform simulation. It creates a comparison plot showing how well the + calculated seismograms fit recorded data. + + Do you want to run a goodness-of-fit module (y/n)? y + ================================================================================ + + Users can optionally select a Goodness of Fit module to plot a comparison of + how well the simulated seismograms match the recorded data in a historical event. + + Choose a Goodness of Fit (GOF) Module: + (1) GP + (2) FAS + (3) GP and SDSU + (4) GP and FAS + ? 1 + ================================================================================ + + Additional Metrics + ================== + Calculating additional metrics is an optional step on the Broadband Platform. + It creates additional plots and data files that can be used to study the simulation. + + Do you want to calculate additional metrics (y/n)? n + XML file /home/jane/bbp/bbp_data/xml/9996390.xml generated, not running workflow. +``` + +Please note the xml file generated by the BBP (it is listed in the last line). A couple of things to note are that since the simulation data is already generated outside of the Platform, it does not matter what simulation method is selected (not what site response module is selected). If users created a custom station list, they should select the "custom" option after selecting to run the rupture generator and then provide the path for the station list created for this simulation. Finally, users should select the GP Goodness-of-Fit module and request velocity and acceleration plots. + +Once that step is completed, users will need to run the BBP a second time using the following options: + +``` + $ run_bbp.py -m -s -x -r plot_map +``` + +The "sim_id" should match the value specified by the user when running the "import_bbp_simulation.py" tool. The "xml_file" should be the xml file created by the BBP when it was called the first time (see above). It is important not to forget to specify the "-r plot_map" flag as this flag will tell the BBP to skip the seismogram generation steps and go directly to the post-processing stage. diff --git a/doc/images/gof-CHINOH-1127156_r0-180-rd50.png b/doc/images/gof-CHINOH-1127156_r0-180-rd50.png new file mode 100644 index 00000000..6d73e36b Binary files /dev/null and b/doc/images/gof-CHINOH-1127156_r0-180-rd50.png differ diff --git a/doc/images/gof-CHINOH-1147143_r0-180-rd50.png b/doc/images/gof-CHINOH-1147143_r0-180-rd50.png new file mode 100644 index 00000000..52126998 Binary files /dev/null and b/doc/images/gof-CHINOH-1147143_r0-180-rd50.png differ diff --git a/doc/images/gof-CHINOH-6916980_r0-180-rd50.png b/doc/images/gof-CHINOH-6916980_r0-180-rd50.png deleted file mode 100644 index 5b2a8158..00000000 Binary files a/doc/images/gof-CHINOH-6916980_r0-180-rd50.png and /dev/null differ diff --git a/doc/images/gof-CHINOH-6917077_r0-180-rd50.png b/doc/images/gof-CHINOH-6917077_r0-180-rd50.png deleted file mode 100644 index 5a0891bc..00000000 Binary files a/doc/images/gof-CHINOH-6917077_r0-180-rd50.png and /dev/null differ