diff --git a/doc/adv-manual/Makefile b/doc/adv-manual/Makefile index fcfb16b6365f..0fb49aab64ee 100644 --- a/doc/adv-manual/Makefile +++ b/doc/adv-manual/Makefile @@ -2,7 +2,10 @@ # # You can set these variables from the command line. -SPHINXOPTS = +# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence +# of any warning or error. A bug in sphinx causes the build to produce an +# exit code == 0 if -W is not set, regardless from the presence of any error. +SPHINXOPTS = -W --keep-going SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build diff --git a/doc/adv-manual/conf.py b/doc/adv-manual/conf.py index 3ba67ce50038..73dbbeabf3c8 100644 --- a/doc/adv-manual/conf.py +++ b/doc/adv-manual/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# OpenQuake for Advanced Users documentation build configuration file, created by -# sphinx-quickstart on Fri Mar 2 07:29:39 2018. +# OpenQuake for Advanced Users documentation build configuration file, created +# by sphinx-quickstart on Fri Mar 2 07:29:39 2018. # # This file is execfile()d with the current directory set to its # containing dir. @@ -12,18 +12,18 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import shutil from openquake import engine # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -85,7 +85,6 @@ # Version Dropdown Config - rst_epilog = """ .. |VERSION| replace:: %s """ % release @@ -96,13 +95,13 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -110,27 +109,27 @@ # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +# keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -143,14 +142,19 @@ # html_theme = 'alabaster' html_theme = 'pydata_sphinx_theme' +json_url_path = "../../.ddown_adv.json" +if not os.path.exists(json_url_path): + shutil.copyfile("../samples/dot_ddown_adv.json.sample", + json_url_path) + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { "navbar_start": ["version-switcher"], "switcher": { - "json_url": "../../.ddown_adv.json", - "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2]) + "json_url": json_url_path, + "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2]) }, "icon_links": [ @@ -215,7 +219,7 @@ "type": "fontawesome", # Default is fontawesome } - ] + ] } # Add any paths that contain custom themes here, relative to this directory. diff --git a/doc/adv-manual/secondary_perils.rst b/doc/adv-manual/secondary_perils.rst.bak similarity index 100% rename from doc/adv-manual/secondary_perils.rst rename to doc/adv-manual/secondary_perils.rst.bak diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 6912a58a3e87..35db01f52feb 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -2,7 +2,10 @@ # # You can set these variables from the command line. -SPHINXOPTS = +# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence +# of any warning or error. A bug in sphinx causes the build to produce an +# exit code == 0 if -W is not set, regardless from the presence of any error. +SPHINXOPTS = -W --keep-going SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build diff --git a/doc/manual/conf.py b/doc/manual/conf.py index 79fb0219cb97..abdd48b8a6ad 100644 --- a/doc/manual/conf.py +++ b/doc/manual/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# OpenQuake for Advanced Users documentation build configuration file, created by -# sphinx-quickstart on Fri Mar 2 07:29:39 2018. +# OpenQuake for Advanced Users documentation build configuration file, created +# by sphinx-quickstart on Fri Mar 2 07:29:39 2018. # # This file is execfile()d with the current directory set to its # containing dir. @@ -12,18 +12,18 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys import os +import shutil from openquake import engine # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -95,7 +95,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -105,7 +105,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build','old'] +exclude_patterns = ['_build', 'old'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -167,11 +167,16 @@ #html_logo = '_static/oq_logo.png' html_logo = None +json_url_path = "../../.ddown_man.json" +if not os.path.exists(json_url_path): + shutil.copyfile("../samples/dot_ddown_man.json.sample", + json_url_path) + html_theme_options = { "navbar_start": ["version-switcher"], "switcher": { - "json_url": "../../.ddown_man.json", - "version_match": "development" if it_is_master == True else '.'.join(version.split('.')[0:2]) + "json_url": json_url_path, + "version_match": "development" if it_is_master is True else '.'.join(version.split('.')[0:2]) }, "icon_links": [ { @@ -235,7 +240,7 @@ "type": "fontawesome", # Default is fontawesome } - ] + ] } # The name of an image file (relative to this directory) to use as a favicon of @@ -316,17 +321,20 @@ # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -'pointsize': '12pt', + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '12pt', -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # Additional stuff for the LaTeX preamble. + # 'preamble': '', -# Latex figure (float) alignment -#'figure_align': 'htbp', + # Latex figure (float) alignment + # 'figure_align': 'htbp', + 'utf8extra': r""" +\DeclareUnicodeCharacter{22EE}{\ensuremath{\vdots}} +""", } # Grouping the document tree into LaTeX files. List of tuples diff --git a/doc/manual/hazard.rst b/doc/manual/hazard.rst index c8aed8adc234..58b09911f75a 100644 --- a/doc/manual/hazard.rst +++ b/doc/manual/hazard.rst @@ -1099,7 +1099,7 @@ Scenario based Seismic Hazard Analysis In case of Scenario Based Seismic Hazard Analysis, the engine simulates a set of ground motion fields (GMFs) at the target sites for the requested set of intensity measure types. This set of GMFs can then be used in -:ref:`Scenario Damage Assessment` and :ref:`Scenario Risk Assessment` +:ref:`sec-scenario_damage_assessment` and :ref:`sec-config_scenario_risk` to estimate the distribution of potential damage, economic losses, fatalities, and other consequences. The scenario calculator is useful for simulating both historical and hypothetical earthquakes. @@ -2355,7 +2355,7 @@ be specifed by using the ``sites`` or ``sites_csv`` parameters, or the ``region`` and ``region_grid_spacing`` parameters, similar to the classical PSHA and event-based PSHA calculators; other options include the definition of the sites through the ``site_model_file`` or the -exposure model (see Section :ref:`Exposure Models`). +exposure model (see Section :ref:`sec-exposure`). The parameters unique to the scenario calculator are described below: @@ -2400,15 +2400,16 @@ a ``site_model_stations.csv`` file. | VIGA | LAS VIGAS | -99.23326 | 16.7587 | seismic | 0.355 | 0 | 0.5262 | 0 | 0.1012 | 0 | | VNTA | LA VENTA | -99.81885 | 16.91426 | seismic | 0.2061 | 0 | 0.3415 | 0 | 0.1051 | 0 | | COYC | COYUCA | -100.08996 | 16.99778 | seismic | 0.1676 | 0 | 0.2643 | 0 | 0.0872 | 0 | - | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | + | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | | UTM_14Q_041_186 | NA | -99.7982 | 16.86687 | macroseismic | 0.6512 | 0.8059 | 0.9535 | 1.0131 | 0.4794 | 1.0822 | | UTM_14Q_041_185 | NA | -99.79761 | 16.77656 | macroseismic | 0.5797 | 0.8059 | 0.8766 | 1.0131 | 0.4577 | 1.0822 | | UTM_14Q_040_186 | NA | -99.89182 | 16.86655 | macroseismic | 0.477 | 0.8059 | 0.722 | 1.0131 | 0.3223 | 1.0822 | - | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | + | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | ⋮ | +-----------------+--------------+------------+----------+--------------+-----------+--------------+---------------+------------------+---------------+------------------+ The following parameters are mandatory: -- ``STATION_ID``: string; subject to the same validity checks as the ``id`` fields + +- ``STATION_ID``: string; subject to the same validity checks as the ``id`` fields in other input files. - ``LONGITUDE``, ``LATITUDE``: floats; valid longitude and latitude values. @@ -2427,6 +2428,7 @@ The following parameters are mandatory: using the column headers _VALUE, _STDDEV respectively. The following parameters are optional: + - ``STATION_NAME``: string; free form and not subject to the same constraints as the `STATION_ID` field. The optional STATION_NAME field can contain information that aids in identifying a particular station. diff --git a/doc/manual/risk.rst b/doc/manual/risk.rst index e31f2747e702..50fef2e388be 100644 --- a/doc/manual/risk.rst +++ b/doc/manual/risk.rst @@ -66,6 +66,8 @@ options and methodologies can be easily introduced, without affecting the overall calculation workflow. Each workflow is described in more detail in the following sections. +.. _sec-scenario_damage_assessment: + Scenario Damage Assessment ^^^^^^^^^^^^^^^^^^^^^^^^^^ The scenario damage diff --git a/doc/samples/README.md b/doc/samples/README.md new file mode 100644 index 000000000000..7e7a6ab3fca0 --- /dev/null +++ b/doc/samples/README.md @@ -0,0 +1,6 @@ +Files `dot_ddown_adv.json.sample` and `dot_ddown_man.json.sample` are samples of +files `.ddown_adv.json` and `.ddown_man.json` referred by +`oq-engine/doc/adv-manual/conf.py` and `oq-engine/doc/manual/conf.py`, +needed by `html_theme_options['switcher']['json_url']`. +They are meant to be found in the `oq-engine` directory. +These files are generated automatically by .github/workflows/docs.yml diff --git a/doc/samples/dot_ddown_adv.json.sample b/doc/samples/dot_ddown_adv.json.sample new file mode 100644 index 000000000000..8533ed469f58 --- /dev/null +++ b/doc/samples/dot_ddown_adv.json.sample @@ -0,0 +1 @@ +[{ "name": "3.16 (LTS)", "version": "3.16", "url": "https://docs.openquake.org/oq-engine/3.16/advanced/" }, { "name": "development", "version": "master", "url": "https://docs.openquake.org/oq-engine/master/advanced/" }] diff --git a/doc/samples/dot_ddown_man.json.sample b/doc/samples/dot_ddown_man.json.sample new file mode 100644 index 000000000000..39a1222c0611 --- /dev/null +++ b/doc/samples/dot_ddown_man.json.sample @@ -0,0 +1 @@ +[{ "name": "3.16 (LTS)", "version": "3.16", "url": "https://docs.openquake.org/oq-engine/3.16/manual/" }, { "name": "development", "version": "master", "url": "https://docs.openquake.org/oq-engine/master/manual/" }] diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile index 908302ca38a7..9382049461d6 100644 --- a/doc/sphinx/Makefile +++ b/doc/sphinx/Makefile @@ -2,7 +2,10 @@ # # You can set these variables from the command line. -SPHINXOPTS = -j 8 # -n -W +# NOTE: -W treats also warnings as errors and produces an exit code != 0 in presence +# of any warning or error. A bug in sphinx causes the build to produce an +# exit code == 0 if -W is not set, regardless from the presence of any error. +SPHINXOPTS = -j 8 -W --keep-going # -n SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build diff --git a/doc/sphinx/openquake.hazardlib.gsim.rst b/doc/sphinx/openquake.hazardlib.gsim.rst index 29a2c2ae0d44..edfe006f29bf 100644 --- a/doc/sphinx/openquake.hazardlib.gsim.rst +++ b/doc/sphinx/openquake.hazardlib.gsim.rst @@ -156,10 +156,10 @@ arteta_2021 :undoc-members: :show-inheritance: -arteta_2023_nosam +arteta_2023 --------------------------------------------------- -.. automodule:: openquake.hazardlib.gsim.arteta_2023_nosam +.. automodule:: openquake.hazardlib.gsim.arteta_2023 :members: :undoc-members: :show-inheritance: diff --git a/doc/sphinx/openquake.hazardlib.rst b/doc/sphinx/openquake.hazardlib.rst index 6262ed1a280f..b9bcf69587cf 100644 --- a/doc/sphinx/openquake.hazardlib.rst +++ b/doc/sphinx/openquake.hazardlib.rst @@ -12,8 +12,6 @@ Subpackages openquake.hazardlib.mfd openquake.hazardlib.scalerel openquake.hazardlib.source - openquake.hazardlib.source_reader - openquake.hazardlib.logictree source_reader module diff --git a/openquake/hazardlib/gsim/kotha_2020.py b/openquake/hazardlib/gsim/kotha_2020.py index a547b44dec92..c9781ca0b26b 100644 --- a/openquake/hazardlib/gsim/kotha_2020.py +++ b/openquake/hazardlib/gsim/kotha_2020.py @@ -345,6 +345,7 @@ class KothaEtAl2020(GMPE): always being used if defined on input. In the core form of the GMPE no site term is included. This is added in the subclasses. + :param float sigma_mu_epsilon: Parameter to control the source-region scaling as a number of standard deviations by which to multiply the source-region to source- diff --git a/openquake/hazardlib/gsim/wong2022.py b/openquake/hazardlib/gsim/wong2022.py index c05ab6a9ccf4..212918eaf8b9 100644 --- a/openquake/hazardlib/gsim/wong2022.py +++ b/openquake/hazardlib/gsim/wong2022.py @@ -19,7 +19,7 @@ """ Module exports :class:`WongEtAl2015`. :class:`WongEtAl2022Shallow`. - :class:`WongEtAl2022Deep. + :class:`WongEtAl2022Deep`. """ import numpy as np @@ -50,8 +50,8 @@ class WongEtAl2022Shallow(GMPE): Implements GMPE developed by Ivan Wong, Robert Darragh, Sarah Smith, Qimin Wu, Walter Silva, Tadahiro Kishida; "Ground motion models for shallow crustal and deep earthquakes in Hawaii and analyses of the 2018 M 6.9 - Kalapana sequence." Earthquake Spectra 2022;; 38 (1): 579–614. doi: - https://doi.org/10.1177/87552930211044521 + Kalapana sequence." Earthquake Spectra 2022;; 38 (1): 579–614. doi: + https://doi.org/10.1177/87552930211044521 SA are given up to 10 s. The regressions are developed considering the average horizontal component of the as-recorded horizontal components diff --git a/openquake/hazardlib/gsim/zhang_zhao_2005.py b/openquake/hazardlib/gsim/zhang_zhao_2005.py index 8413077188e2..7857015488fe 100644 --- a/openquake/hazardlib/gsim/zhang_zhao_2005.py +++ b/openquake/hazardlib/gsim/zhang_zhao_2005.py @@ -139,17 +139,19 @@ def compute(self, ctx: np.recarray, imts, mean, sig, tau, phi): LSD 0.456 0.0552 3.204 -1.0248 -4.743 0.22 """) + class Zhang_Zhao2005SSlab(Zhang_Zhao2005SInter): """ - Implements the GMPE of Zhang and Zhao. (2005) for Permanent ground deformation (m) - from lateral spread - Zhang, J., & Zhao, J. X. (2005). Empirical models for estimating liquefaction-induced - lateral spread displacement. Soil Dynamics and Earthquake Engineering, 25(6), 439-450. - This model is based on Sadigh et al. (1997) and Young et al. (1997) models + Implements the GMPE of Zhang and Zhao. (2005) for Permanent ground + deformation (m) from lateral spread + Zhang, J., & Zhao, J. X. (2005). Empirical models for estimating + liquefaction-induced lateral spread displacement. Soil Dynamics and + Earthquake Engineering, 25(6), 439-450. This model is based on Sadigh et + al. (1997) and Young et al. (1997) models """ - #: This GMPE is based on subduction intraslab earthquakes + #: This GMPE is based on subduction intraslab earthquakes DEFINED_FOR_TECTONIC_REGION_TYPE = const.TRT.SUBDUCTION_INTRASLAB - + def compute(self, ctx: np.recarray, imts, mean, sig, tau, phi): for m, imt in enumerate(imts): ctx = ctx.copy()