.. _sigma-gmpes:

GMPE/GMM: Ground Motion Prediction Equations and Models
=======================================================

The |appname| packages provides :term:`GMPEs <GMPE>`/:term:`GMMs <GMM>` which are
:ref:`internally defined <sigma-gmpes-internal>`.
For greater flexibility :ref:`externally defined custom GMPEs <sigma-gmpes-external>`
can by added.


.. _sigma-gmpes-internal:

Internal GMPE/GMM
-----------------

The internally defined GMPE models and GMMs provide the fasted access to results.
They are made available through the plugin **cppgmpe** and can be used without
further software installations. Read the
:ref:`instructions for their configuration <sigma-plugins-internal>`.

.. hint::

   Some models require to define a focal mechanism and a finite fault, e.g. to
   compute distance measures. Read the section :ref:`sigma-rupture` for
   instructions on defining a focal mechanism and rupture geometry interactively.

We mainly discriminate the GMPEs based on their tectonic or geographical region:

- :ref:`Tectonic regions <sigma-tectonic-regions>`
   - :ref:`Active Shallow Crust <sigma-asc>`
   - :ref:`Geothermal <sigma-geothermal>`
   - :ref:`Induced <sigma-induced>`
   - :ref:`Stable Shallow Crust <sigma-ssc>`
   - :ref:`Subduction IntraSlab <sigma-sis>`
   - :ref:`Subduction Interface <sigma-sif>`
   - :ref:`Volcanic <sigma-volcanic>`

- :ref:`Geographical Regions <sigma-geo-regions>`
   - :ref:`Iceland <sigma-iceland>`
   - :ref:`India <sigma-india>`

- :ref:`Additional GMPEs <sigma-additional>`


.. _sigma-tectonic-regions:

Tectonic regions
~~~~~~~~~~~~~~~~

.. _sigma-asc:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Active Shallow Crust, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   AkkarBommer2010 :cite:p:`akkar-2010`;      ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   AkkarEtAl2014_Repi :cite:p:`akkar-2014`;   ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Repi <distance, epicentral>`; Magnitude, Rake; ✅;
   AkkarEtAl2014_Rhyp :cite:p:`akkar-2014`;   ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude, Rake; ✅;
   AkkarEtAl2014_Rjb :cite:p:`akkar-2014`;    ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreAtkinson2008 :cite:p:`boore-2008`;    ✅; ✅; ✅; ;   Avg. Horiz. (GMRotI50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreAtkinson2011 :cite:p:`atkinson-2011`; ✅; ✅; ✅; ;   Avg. Horiz. (GMRotI50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreEtAl2014 :cite:p:`boore-2014`;        ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreEtAl2014_HighQ :cite:p:`boore-2014`;  ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreEtAl2014_LowQ :cite:p:`boore-2014`;   ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   BooreEtAl2020 :cite:p:`boore-2021`;        ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   DerrasEtAl2014 :cite:p:`derras-2014`;      ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake, HypoDepth; ✅;
   DerrasEtAl2014_RhypoGermany :cite:p:`derras-2014`;      ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>` / :term:`Rhypo <distance, hypocentral>`; Magnitude, Rake, HypoDepth, Width; ✅;
   KaleEtAl2015_Iran :cite:p:`kale-2015`;     ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   KaleEtAl2015_Turkey :cite:p:`kale-2015`;   ✅; ✅; ✅; ;   Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;
   KothaEtAl2020 :cite:p:`kotha-2020`;        ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, HypoDepth; ;
   KothaEtAl2020_Site :cite:p:`kotha-2020`;   ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`; Magnitude, HypoDepth;  ✅;
   ZhaoEtAl2006_Asc :cite:p:`zhao-2006`;      ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, Rake, HypoDepth; ✅;
   ZhaoEtAl2006_AscSGS :cite:p:`zhao-2006`;   ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, Rake, HypoDepth; ✅;

.. _sigma-geothermal:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Geothermal, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   ConvertitoEtAl2012_Geysers :cite:p:`convertito-2012`;  ; ✅;  ; ;  Greater of two horizontal; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;

.. _sigma-induced:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Induced, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   Atkinson2015 :cite:p:`atkinson-2015`;            ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rhypo <distance, hypocentral>`; Magnitude; ;
   Atkinson2015_AltDistSat :cite:p:`atkinson-2015`; ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rhypo <distance, hypocentral>`; Magnitude; ;
   DostEtAl2004 :cite:p:`dost-2004`;                    ; ✅; ✅; ;   Avg. Horiz. (GMRotD100); :term:`Rhypo <distance, hypocentral>`; Magnitude; ;
   ZalachorisRathje2019 :cite:p:`zalachoris-2019`;  ✅; ✅; ✅; ;   Avg. Horiz. (RotD50); :term:`Rjb <distance, Joyner-Boore>`, :term:`Rhypo <distance, hypocentral>`; Magnitude, Rake;  ✅;

.. _sigma-ssc:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Stable Shallow Crust, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   Allen2012 :cite:p:`allen-2012`;              ✅; ✅; ; ;  Med. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ;
   Allen2012_SS14 :cite:p:`allen-2012`;         ✅; ✅; ; ;  Med. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;
   AtkinsonBoore2006 :cite:p:`atkinson-2006`;   ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude; ✅;
   BindiEtAl2017_Rhypo :cite:p:`bindi-2017`;    ✅; ✅; ; ; Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude;  ✅;
   BindiEtAl2017_Rjb :cite:p:`bindi-2017`;      ✅; ✅; ; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;  ✅;
   RietbrockEtAl2013_MagDependent :cite:p:`rietbrock-2013`; ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;
   RietbrockEtAl2013_SelfSimilar :cite:p:`rietbrock-2013`; ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;
   RietbrockEdwards2019_Low :cite:p:`edwards-2019`; ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;
   RietbrockEdwards2019_Mean :cite:p:`edwards-2019`; ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;
   RietbrockEdwards2019_Up :cite:p:`edwards-2019`; ✅; ✅; ✅; ; Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;

.. _sigma-sis:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Subduction IntraSlab, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   Allen2022 :cite:p:`allen-2022`;                    ✅; ✅; ✅; ;   Med. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude, HypoDepth; ✅;
   ZhaoEtAl2006_SSlab :cite:p:`zhao-2006`;            ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;
   ZhaoEtAl2006_SSlabCascadia :cite:p:`zhao-2006`;    ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;
   ZhaoEtAl2006_SSlabNSHMP2014 :cite:p:`zhao-2006`;   ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;

.. _sigma-sif:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Subduction Interface, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   ZhaoEtAl2006_SInter :cite:p:`zhao-2006`;           ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;
   ZhaoEtAl2006_SInterCascadia :cite:p:`zhao-2006`;   ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude, HypoDepth; ✅;
   ZhaoEtAl2006_SInterNSHMP2008 :cite:p:`zhao-2006`;  ✅; ✅; ; ;   Avg. Horiz.; :term:`Rrup <distance, rupture>`; Magnitude; ✅;

.. _sigma-volcanic:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Volcanic, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   Atkinson2010_Hawaii :cite:p:`atkinson-2010`;    ✅; ✅; ✅; ;  Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake, HypoDepth; ✅;
   LanzanoLuzi2019_Deep :cite:p:`lanzano-2020`;    ✅; ✅; ✅; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;
   LanzanoLuzi2019_DeepScaled :cite:p:`lanzano-2020`;    ✅; ✅; ✅; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;
   LanzanoLuzi2019_Shallow :cite:p:`lanzano-2020`;    ✅; ✅; ✅; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;
   LanzanoLuzi2019_ShallowScaled :cite:p:`lanzano-2020`;    ✅; ✅; ✅; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;
   TusaLanger2016_RepiBA08DE :cite:p:`tusa-2016`;    ✅; ✅; ; ;  Greater of two horizontal; :term:`Repi <distance, epicentral>`; Magnitude; ✅;
   TusaLanger2016_RepiBA08SE :cite:p:`tusa-2016`;    ✅; ✅; ; ;  Greater of two horizontal; :term:`Repi <distance, epicentral>`; Magnitude; ✅;
   TusaLanger2016_RepiSP87DE :cite:p:`tusa-2016`;    ✅; ✅; ; ;  Greater of two horizontal; :term:`Repi <distance, epicentral>`; Magnitude; ✅;
   TusaLanger2016_RepiSP87SE :cite:p:`tusa-2016`;    ✅; ✅; ; ;  Greater of two horizontal; :term:`Repi <distance, epicentral>`; Magnitude; ✅;
   TusaLanger2016_Rhypo :cite:p:`tusa-2016`;    ✅; ✅; ; ;  Greater of two horizontal; :term:`Rhypo <distance, hypocentral>`; Magnitude; ✅;

.. _sigma-geo-regions:

Geographical regions
~~~~~~~~~~~~~~~~~~~~

.. _sigma-iceland:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Iceland, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   IMO-PV09 :cite:p:`petursson-2010`;               ; ✅; ✅; MMI; ; :term:`Repi <distance, epicentral>`; Magnitude; ;
   KowsariEtAl2020_Y1 :cite:p:`kowsari-2020`;      ✅; ✅; ; ; ; :term:`Rjb <distance, Joyner-Boore>`; Magnitude;  ;
   KowsariEtAl2020_Y2 :cite:p:`kowsari-2020`;      ✅; ✅; ; ; ; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake;  ;
   UICE-K20A :cite:p:`kowsari-2020` specifically developed for south Iceland seismic zone;   ; ✅; ; MMI; ; :term:`Rjb <distance, Joyner-Boore>`; Magnitude; ; Soil factor (based on vs30)
   UICE-K20C :cite:p:`kowsari-2020` specifically developed for south Iceland seismic zone;   ; ✅; ; MMI; ; :term:`Rjb <distance, Joyner-Boore>`; Magnitude; ; Soil factor (based on vs30)

.. _sigma-india:

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: India, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   NathEtAl2012_Lower :cite:p:`nath-2012`;            ✅; ✅; ✅; ;   Vertical; :term:`Rrup <distance, rupture>`; Magnitude;
   NathEtAl2012_Upper :cite:p:`nath-2012`;            ✅; ✅; ✅; ;   Vertical; :term:`Rrup <distance, rupture>`; Magnitude;
   RaghukanthIyengar2007 :cite:p:`raghukanth-2007`;   ✅; ✅; ; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;
   RaghukanthIyengar2007_KoynaWarna :cite:p:`raghukanth-2007`;   ✅; ✅; ; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;
   RaghukanthIyengar2007_Southern :cite:p:`raghukanth-2007`;   ✅; ✅; ; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;
   RaghukanthIyengar2007_WesternCentral :cite:p:`raghukanth-2007`;   ✅; ✅; ; ;  Avg. Horiz.; :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;
   SharmaEtAl2019 :cite:p:`sharma-2009`;              ✅; ✅; ; ;  Avg. Horiz.; :term:`Rjb <distance, Joyner-Boore>`; Magnitude, Rake; ✅;

.. _sigma-additional:

Additional GMPEs
~~~~~~~~~~~~~~~~

.. csv-table::
   :widths: 7 1 1 1 1 2 1 1 1 1
   :align: center
   :header: Additional models, SA, PGA, PGV, Other IMTs, Component, Distances, Rupture Parameters, vs30, Other Site Parameters
   :delim: ;

   BEA2014 :cite:p:`bindi-2014`;          ✅; ✅; ✅; DRS; ;  :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;
   CEA2014 :cite:p:`cauzzi-2015`;         ✅; ✅; ✅; DRS; ;  :term:`Rrup <distance, rupture>` / :term:`Rhypo <distance, hypocentral>`; Magnitude ; ✅;

* If not explicitly listed in 'Other IMTs', MMI is :ref:`derived from PGA <sigma-gmpes-mmi>`.
* Further, see  :term:`SA <SA>`, :term:`PGA <PGA>`, :term:`PGV <PGV>`, :ref:`Vs30 grid<sigma_vs30>`
* For a detailed description of the implemented code and coefficients see also `OpenQuake documentation <https://docs.openquake.org/oq-engine/latest/reference/openquake.hazardlib.gsim.html>`_.


.. _sigma-gmpes-external:

External custom GMPEs
---------------------

In |autoappname| and |guiname| you may use external custom GMPEs, e.g. by your
own or other custom Python scripts. For example the modules can interface with
the :term:`GMPEs<GMPE>`
provided by OpenQuake :cite:p:`openquake` and the Python script
:file:`$SEISCOMP_ROOT/share/sigma/pygmpe/oq-sm.py` of the |appname| package.
This unique feature allows to additionally
implement their own GMPEs which may come from their own research and which may be
tailored to specific regions. Check the list of models :cite:p:`openquake-models`
provided by OpenQuake.

The interface to custom GMPEs is provided through the plugin **py3gmpe**.
Read the :ref:`instructions for the configuration <sigma-plugins-external>`.

.. _sigma-gmpes-mmi:

Modified Mercalli intensity (MMI)
---------------------------------

Some GMPEs/GMMs such as IMO-PV09 provide estimates of Modified Mercalli
intensity (MMI), others not, e.g., CEA2014. When not provided by a GMPE/GMM, MMI
is estimated from :term:`PGA <PGA>` using formulas in :cite:t:`wald-1999`:

* :math:`MMI < 5`: :math:`MMI` = 2.20 * log_{10}(PGA) + 1
* :math:`MMI \ge 5`: :math:`MMI` = 3.66 * log_{10}(PGA) - 1.66

where PGA is given in :math:`cm/s^2`.

The debug logging output tells how MMI is computed for a selected GMPE/GMM.