diff --git a/docs/README.md b/docs/README.md index 8b2bfaf034f9a1c144480f7b7e71414dfc140c29..6a952c9a80f9eb8e65ade42981d5639c794a3679 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,7 @@ use *nshmp-haz* as well as underlying model implementation details. * [USGS Models](./pages/USGS-Models.md) * [Model Editions](./pages/Model-Editions.md) * [Logic Trees & Uncertainty](./pages/Logic-Trees-&-Uncertainty.md) + * [Code Versions](./pages/Code-Versions.md) ## Related Information diff --git a/docs/pages/Code-Versions.md b/docs/pages/Code-Versions.md new file mode 100644 index 0000000000000000000000000000000000000000..801a9b66faf3a8eef92d1605d50b02a7a16b6d39 --- /dev/null +++ b/docs/pages/Code-Versions.md @@ -0,0 +1,54 @@ +# Code Versions + +The static datasets of USGS NSHMs prior to 2014 were computed using Fortran (see +[_nshmp-haz-fortran_](https://github.com/usgs/nshmp-haz-fortran])). The static datasets for the +2014 Conterminous U.S. NSHM were computed using the Fortran codes and +[OpenSHA](https://opensha.org/) (for the California portion of the model). The dynamic versions +of the 2008 and 2014 Conterminous U.S. models were then implemented in the 1st version of +[_nshmp-haz_](https://github.com/usgs/nshmp-haz) (on GitHub). This updated Java codebase uses XML +source models and supports the web services behind the dynamic calculations of the [Unified Hazard +Hazard Tool](https://earthquake.usgs.gov/hazards/interactive/) (UHT). + +The 2nd version of _nshmp-haz_ (this repository) supercedes prior codebases. The development of this +version involved a significant refactoring of both the computational code and source model format. +The source models are now defined using JSON, GeoJSON, and CSV files to better reflect the +underlying logic trees and support uncertainty analysis. + +## Transitioning from _nshmp-haz_ v1 to v2 + +NSHMs are very detailed and migrating from one format to another is not trivial and prone to error. +Moreover, approximations (e.g. using 3.1415 for Pi rather than the the value built into most +languages) can yield different results. When multiple such small changes exist, deciphering what +is giving rise to differences in results can be challenging. + +To document the transition from _nshmp-haz_ v1 to v2, we here attach comparison maps at four return +periods (475, 975, 2475, and 10,000 year) for the 2018 Conterminous U.S. model. Maps are included +for PGA and 3 spectral periods ( 0.2 s, 1 s, and 5 s). There are no differences in the Central & +Eastern U.S. and differences in the WUS are <<1%. The difference in hazard in the vicinity of +Salt Lake City arises from the cluster models in _nshmp-haz_ v1 not being able to consider the +additional epistemic uncertainty added to the the NGA-West2 ground motion models. + +We continue to investigate the cause of other differences but they are small enough that we are +comfortable moving forward deploying _nshmp-haz_ v2 codes and models to our public web services and +applications. This repository includes end-to-end tests for supported NSHMs that may be run +on demand. + +[Download v1 to v2 difference and ratio maps](https://code.usgs.gov/ghsc/users/pmpowers/nshmp-haz/-/raw/code-version-doc-506/docs/pages/images/comp_JSON_vs_XML_0p2-grid-20220216-BC.pdf?inline=false) + +## Example map: 0.2 s, 2475-yr + + + +--- + +## Related Pages + +* [USGS Models](./USGS-Models.md#usgs-models) + * [Model Editions](./Model-Editions.md#model-editions) + * [Logic Trees & Uncertainty](./Logic-Trees-&-Uncertainty.md#logic-trees-&-uncertainty) + * [Code Versions](./Code-Versions.md#code-versions) +* [**Documentation Index**](../README.md) + +--- + [U.S. Geological Survey](https://www.usgs.gov) +National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/)) diff --git a/docs/pages/Logic-Trees-&-Uncertainty.md b/docs/pages/Logic-Trees-&-Uncertainty.md index 87a4e0c86136a6f1c633d1f4350ec6e8bf9a0a94..313fb029db6a4a395abeecf9ac0f10d01a28b1d1 100644 --- a/docs/pages/Logic-Trees-&-Uncertainty.md +++ b/docs/pages/Logic-Trees-&-Uncertainty.md @@ -114,6 +114,7 @@ alternative models. * [USGS Models](./USGS-Models.md#usgs-models) * [Model Editions](./Model-Editions.md#model-editions) * [Logic Trees & Uncertainty](./Logic-Trees-&-Uncertainty.md#logic-trees-&-uncertainty) + * [Code Versions](./Code-Versions.md#code-versions) * [**Documentation Index**](../README.md) --- diff --git a/docs/pages/Model-Editions.md b/docs/pages/Model-Editions.md index 0509a8bc7aea43f5cee1712af7f8d5b425c5dc9d..b875007e6755685aac757fc9e3d804c765357083 100644 --- a/docs/pages/Model-Editions.md +++ b/docs/pages/Model-Editions.md @@ -24,26 +24,26 @@ version numbers. Links to documentation and data for each of the models below ar page. Changes between editions in model regions are documented in the release notes of the individual model repositories. -Region | Year | Version | Static | Dynamic | Notes | --------|:----:|:-------:|:------:|:-------:|-------| -Conterminous U.S. | 2018 | [v5.0.0](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | -Conterminous U.S. | 2014 | [v4.2.0](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | -Conterminous U.S. | 2014 | [v4.1.4](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | -Conterminous U.S. | 2014 | [v4.0.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2014r1) |:small_blue_diamond:| | ASCE7-16 | -Conterminous U.S. | 2008 | v3.3.3 | |:small_blue_diamond:| | -Conterminous U.S. | 2008 | [v3.2.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2008r3) |:small_blue_diamond:| | | -Conterminous U.S. | 2008 | v3.1.0 |:small_blue_diamond:| | ASCE7-10 | -Conterminous U.S. | 2008 | v3.0.0 | | | | -Conterminous U.S. | 2002 | v2.0.0 | | | | -Conterminous U.S. | 1996 | v1.0.0 | | | | -Alaska | 2007 | v2.1.0 | |:small_blue_diamond:| | -Alaska | 2007 | v2.0.0 |:small_blue_diamond:| | ASCE7-10 | -Alaska | 1999 | v1.0.0 | | | | -American Samoa | 2012 | v1.0.0 | | | | -Guam | 2012 | v1.0.0 | | | | -Hawaii | 2018 | v2.0.0 | | TBD | | -Hawaii | 1998 | v1.1.0 | | TBD | | -Hawaii | 1998 | v1.0.0 |:small_blue_diamond:| | ASCE7-10 | +Region | Year | Version | Static | Dynamic | Notes | +------------------|:----:|:-------:|:------:|:-------:|-------| +Conterminous U.S. | 2018 | [5.0.0](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | +Conterminous U.S. | 2014 | [4.2.0](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | +Conterminous U.S. | 2014 | [4.1.4](https://code.usgs.gov/ghsc/nshmp/nshms/nshm-conus)<sup>†</sup> | |:small_blue_diamond:| | +Conterminous U.S. | 2014 | [4.0.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2014r1) |:small_blue_diamond:| | ASCE7-16 | +Conterminous U.S. | 2008 | 3.3.3 | |:small_blue_diamond:| | +Conterminous U.S. | 2008 | [3.2.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2008r3) |:small_blue_diamond:| | | +Conterminous U.S. | 2008 | 3.1.0 |:small_blue_diamond:| | ASCE7-10 | +Conterminous U.S. | 2008 | 3.0.0 | | | | +Conterminous U.S. | 2002 | 2.0.0 | | | | +Conterminous U.S. | 1996 | 1.0.0 | | | | +Alaska | 2007 | 2.1.0 | |:small_blue_diamond:| | +Alaska | 2007 | 2.0.0 |:small_blue_diamond:| | ASCE7-10 | +Alaska | 1999 | 1.0.0 | | | | +American Samoa | 2012 | 1.0.0 | | | | +Guam | 2012 | 1.0.0 | | | | +Hawaii | 2018 | 2.0.0 | | TBD | | +Hawaii | 1998 | 1.1.0 | | TBD | | +Hawaii | 1998 | 1.0.0 |:small_blue_diamond:| | ASCE7-10 | Puerto Rico & <br/> U.S. Virgin Islands | 2003 | v1.0.0 | | | | <sup>†</sup> __Note on the 2014 conterminous U.S. NSHM:__ Initial publication of the @@ -98,6 +98,7 @@ one of the dynamic editions is likely better. * [USGS Models](./USGS-Models.md#usgs-models) * [Model Editions](./Model-Editions.md#model-editions) * [Logic Trees & Uncertainty](./Logic-Trees-&-Uncertainty.md#logic-trees-&-uncertainty) + * [Code Versions](./Code-Versions.md#code-versions) * [**Documentation Index**](../README.md) --- diff --git a/docs/pages/USGS-Models.md b/docs/pages/USGS-Models.md index 087c0af1389b34de60792bdaebc3b7396b8cda29..63f3ce6a0cbbb8efcac07365b404d91b1bbb924d 100644 --- a/docs/pages/USGS-Models.md +++ b/docs/pages/USGS-Models.md @@ -32,6 +32,7 @@ Each model region has a dedicated repository with version tags marking different * [USGS Models](./USGS-Models.md#usgs-models) * [Model Editions](./Model-Editions.md#model-editions) * [Logic Trees & Uncertainty](./Logic-Trees-&-Uncertainty.md#logic-trees-&-uncertainty) + * [Code Versions](./Code-Versions.md#code-versions) * [**Documentation Index**](../README.md) --- diff --git a/docs/pages/images/JSON_vs_XML-SA0P2-2475.jpg b/docs/pages/images/JSON_vs_XML-SA0P2-2475.jpg new file mode 100644 index 0000000000000000000000000000000000000000..ca8058979292940704d68964ca215fc9347ec40b Binary files /dev/null and b/docs/pages/images/JSON_vs_XML-SA0P2-2475.jpg differ diff --git a/docs/pages/images/comp_JSON_vs_XML_0p2-grid-20220216-BC.pdf b/docs/pages/images/comp_JSON_vs_XML_0p2-grid-20220216-BC.pdf new file mode 100644 index 0000000000000000000000000000000000000000..ad3bce8c30c86f53ce637f925e44ed243dc40c96 Binary files /dev/null and b/docs/pages/images/comp_JSON_vs_XML_0p2-grid-20220216-BC.pdf differ diff --git a/etc/examples/README.md b/etc/examples/README.md index 343bc5b7fc525aa731e601cd2aebeeabc27459c5..75b377a93b08ca4cdd70acdb7520248aadbc5e9c 100644 --- a/etc/examples/README.md +++ b/etc/examples/README.md @@ -1,6 +1,6 @@ # Examples -These examples are designed to be executed locally while following the READMEs on GitLub. +These examples are designed to be executed locally while following the READMEs on GitLab. All examples avoid a lengthy call to Java and the `HazardCalc` program by using the following system alias: