Modifications to Indirect AvgSA and implementation of European Direct AvgSA GMM

[g-weatherill]

This PR includes several features to enhance the support for AvgSA in seismic hazard and risk calculations. AvgSA, in its most general definition, is taken as the geometric mean spectral acceleration for a range of periods centred on period $T_0$. Normally this range of periods is defined with respect to T0, such as a range of N spectral periods between $a \cdot T_0$ and $b \cdot T_0$, with $a$ and $b$ commonly set as 0.2 and 1.5 respectively. Prediction of AvgSA for hazard and risk purposes can take two forms:

"Direct" AvgSA, in which a ground motion model (GMM) is constructed taking AvgSA as the ground motion value.

or

"Indirect" AvgSA, in which the mean and standard of AvgSA is determined from an existing GMM by computing the mean and total standard deviation of SA for the required range of periods and taking the first and second moment of these values accounting for the cross-correlation between periods.

Currently, indirect AvgSA is supported in OpenQuake via the GenericGmpeAvgSA, which requires the user specifies the choice of GMM, the cross-correlation model and the list of periods from which to determine AvgSA. This implementation is general, but it has a significant limitation which is that it treats AvgSA a scalar intensity measure given the user-defined list of periods. In reality, AvgSA is a vector IM (dependent on $T_0$), and when used as the selected intensity measure for risk calculations on a diverse portfolio of buildings it is usual to define the fragility functions for each building class with respect to AvgSA centred on $T_0$ (e.g. Vamvatsikos & Cornell, 2005; Kohrangi et al., 2016; Silva et al., 2019; Iacoletti et al., 2023, and many more). By defining AvgSA as a scalar IM with the period list specified in the GMPE logic tree file, as OpenQuake currently does, it is not possible to run risk calculations for a diverse portfolio in which the fragility functions are determined for AvgSA($T_0$) where $T_0$ may vary for some building classes. This severely restricts the use of AvgSA for regional risk modelling.

To address this limitation, and to be able to facilitate use of AvgSA fragility/vulnerability models for risk applications in Europe, this PR introduces several changes to the way OpenQuake handles AvgSA.

1. Introduction of the class GmpeIndirectAvgSA, which considers indirect AvgSA as a vector quantity. As wth the existing GenericGmpeAvgSA this requires specification of the choice of GMPE and cross-correlation model. However, instead of requiring a fixed list of periods the user can specify instead the factors by which to scale $T_0$ in order to define the lower (t_low) and upper (t_high) limits of the period range, along with the number of periods (n_per) to use within that range in order to find the AvgSA.

One point of note here is that if multiple AvgSA($T_0$) values are required for the hazard and/or risk calculation and each AvgSA($T_0$) is conditioned on n_per periods then it is possible that the total number of periods for which SA(T) is needed can rapidly become large. To keep this under control, when the required number of periods for which SA is calculated exceeds a user-defined threshold (max_num_per) then rather than calculating all of the periods for all values of $T_0$ directly, the code will instead calculate SA only for max_num_per periods between $t_{low} \cdot \min\left( {T_0} \right)$ and $t_{high} \cdot \max\left( {T_0} \right)$, from which the required conditioning periods for each $T_0$ will be interpolated. A default value of max_num_per = 30 was found reproduce AvgSA($T_0$) efficiently without loss of accuracy.

2. Modifications to the definition of AvgSA in the IMT class to allow it to become a vector quantity (AvgSA(T)). For backward compatibility, when no T is supplied then AvgSA can operate as a scalar quantity as per its current form.

3. Implementation of a new direct AvgSA GMPE for shallow crustal seismicity Europe, which adopts the same process of GMPE construction as per the backbone GMM of the 2020 European Seismic Hazard and Risk Models (ESHM20 and ESRM20), but fit to AvgSA according to the definition adopted by Iacolleti et al. (2023), who take AvgSA from 10 periods spaced between 0.2 T0 and 1.5 T0. Three versions of the GMPE are implemented: i) Weatherill2024ESHM20AvgSA is the AvgSA equivalent of the core KothaEtAl2020ESHM20 model used for ESHM20, ii) Weatherill2024ESHM20SlopeGeologyAvgSA is the AvgSA equivalent of KothaEtAl2020ESHM20SlopeGeology, which adopts slope and geology as the input site parameters (used for ESRM20), iii) Weatherill2024ESHM20Homokedastic, which is a variant of the Weatherill2024ESHM20AvgSA GMM but retaining the original homoskedastic between-, within- and site-to-site variability terms of the regression rather than the re-calibrated heterskedastic variability model. A paper describing the construction of this GMM and its variants is in preparation.

4. As part of the development of the aleatory variability term of the AvgSA GMM a new cross-correlation model is defined that re-fits functional form of the Baker & Jayaram (2008) cross-correlation model to the original between-event, between-site and site-corrected within-event residuals of the original Kotha et al. (2020) GMM. As the functional form stayed the same but the ESHM20 version adjusts the coefficients, the Baker & Jayaram (2008) cross-correlation model found within the generic_gmpe_avgsa.py file is re-factored to support all variations without too much repetition of code.

For backward compatibility the GenericGmpeAvgSA remains in place and no changes have been made to its operation. A unit test is added to ensure that when GenericGmpeAvgSA and GmpeIndirectAvgSA are set up to calculate AvgSA from the same configuration then they give the same results.

A classical hazard test case for AvgSA at three different periods (using both the direct and new indirect GMPE) is also added.

[micheles]

Please resolve the conflict on openquake.hazardlib.gsim.rst