Implements ConditionalGMPE class and applies it with model of Macedo et al. (2019)

[g-weatherill]

The pull request implements a new form of GMPE, which is a conditional ground motion model. This describes a family of ground motion models in which the predicted parameter is dependent not only on source, distance and site properties, but also on a different ground motion measure (e.g. PGA, SA(T)). This is applied here to the GMM of Macedo et al. (2019), but several other examples can be found in the literature (e.g. Abrahamson et al., 2016; Liu et al. 2022; Campbell et al., 2023; among others). Most conditional GMMs are for intensity measures such as duration, Arias Intensity or Cumulative Absolute Velocity, which include as predictors the more common peak motion or response spectral parameters such as PGA or SA(T).

A general template for a conditional GMPE is provided via the ConditionalGMPE class, which extends the standard GMPE class in two ways: 1) it requires specification of the intensity measures upon which the predicted parameter is conditioned (including the spectral period) and 2) it adds a function get_conditioning_ground_motions, which retrieves the ground motion values themselves.

The implementation is designed to address two use cases:

1. The case in which the ground motion values (GMVs) that form the inputs to the ConditionalGMPE are known explicitly or calculated independently of OpenQuake. This is the "Shakemap" case and applies when the GMM is used directly from the library (rather than as part of an OpenQuake calculation). Here the known GMVs and their uncertainties can be input into the GMM by adding these as labelled vectors inside the ctx recarray alonside the source, path and distance properties, e.g. PGA_MEAN, PGA_TOTAL_STDDEV, SA(1.0)_MEAN, SA(1.0)_TOTAL_STDDEV etc.

2. The case in which the ground motion values (GMVs) are not specified a priori and must instead be determined from a ground motion model. This case would allow the conditional GMM to be used in a probabilistic seismic hazard and risk calculation, for which no GMVs are known a priori. The extact manner in which the uncertainty in the conditioning ground motion is propagated through to the predicted ground motion may vary from model to model and is therefore left to be addressed in the implementation of the GMM in question. The Macedo et al. (2019) GMM here illustrates clearly how this should be done, however.

If the GMPE is not specified nor are the predictor GMVs provided in the ctx then an error will be raised.

Tests are developed for both the ConditionalGMM class and the MacedoEtAl2019SInter/SSlab classes. For the Macedo et al. (2019) model we have not yet been able to obtain an independent implementation of the model from the authors to generate the test tables. We did, however, verify the output ground motions against the figures provided in the original publication to a satisfactory level of agreement. Wetherefore apply the NotVerified warning. The Macedo et al. (2019) model is also regionalised, so this is included as a configurable parameter and as a set of aliases.

Finally, the conditional GMM is demonstrated in a classical PSHA test case via the Macedo et al. (2019) GMM to produce curves for Arias intensity conditioned on PGA and SA(1.0 s).

Including here @emthompson-usgs and @cbworden for feedback regarding the Shakemap use case.

[emthompson-usgs]

Thanks @g-weatherill and sorry for not posting earlier. This will be very important for the ShakeMap team, and we plan to use this as a template to contribute more conditional models to OQ in the coming months.

[emthompson-usgs]

Hi @g-weatherill and @mmpagani,

I'm trying to work out how to call this class with the preferred method as indicated in @micheles's response to an issue we had in which the advice is to use the ContextMaker class along with it's get_mean_stds method. I'll note that it is relatively easy to get this to work by calling the ConditionalGMPE class directly, so this quesiton is about how to make the ConditionalGMPE class work with the ContextMaker.

If I simply substitute in the MacedoEtAl2019SInter model into @micheles's example:

import numpy as np
from openquake.hazardlib import valid
from openquake.hazardlib.contexts import simple_cmaker

gsim = valid.gsim('''[MacedoEtAl2019SInter]''')
n = 10
mags = np.linspace(5, 7, n)
cmaker = simple_cmaker([gsim], ['PGA'], mags=['%.2f' % mag for mag in mags])
ctx = cmaker.new_ctx(n)
ctx["mag"] = mags
ctx["vs30"] = np.linspace(200, 300, n)
ctx["rrup"] = np.linspace(1, 100, n)

mean, sigma, tau, phi = cmaker.get_mean_stds([ctx])

I get a sensible error since I haven't specified a conditioning data or model:

ValueError: Conditioning ground motions must be specified in ctx or a GMPE must be provided

If I try to add the condition data to the ctx:

ctx["SA(1.0)_MEAN"] = np.logspace(-1., 0.0, n)

I get an error:

ValueError: no field of name SA(1.0)_MEAN

I can get around this by directly creating the ctx with np.recarray.

Additionally, the ConditionalGMPE class takes a gmpe argument that can be used if conditioning data are not provided. It seems like this should be provided through the valid.gsim method. My first guess at how this would work is like this:

gsim = valid.gsim('''[MacedoEtAl2019SInter]
gmpe=[AbrahamsonEtAl2015SInter]''')

But that results in an error:

AttributeError: 'str' object has no attribute 'items'

Any guidance on how to resolve these issues would be great. Thanks.