Correlation of Ground Motion Fields ========================================= There are multiple different kind of correlation on the engine, so it is extremely easy to get confused. Here I will list all possibilities, in historical order. 1. Spatial correlation of ground motion fields has been a feature of the engine from day one. The available models are JB2009 and HM2018. 2. Cross correlation in ShakeMaps has been available for a few years. The model used there is hard-coded an the user cannot change it, only disable it. The models list below (3. and 4.) *have no effect on ShakeMaps*. 3. Since version 3.13 the engine provides the BakerJayaram2008 cross correlation model, however at the moment it is used only in the conditional spectrum calculator. 4. Since version 3.13 the engine provides the GodaAtkinson2009 cross correlation model and the FullCrossCorrelation model which can be used in scenario and event based calculations. Earthquake theory tells us that ground motion fields depend on two different lognormal distributions with parameters (:math:\mu, :math:\tau) and (:math:\mu, :math:\phi) respectively, which are determined by the GMPE (Ground Motion Prediction Equal). Given a rupture, a set of M intensity measure types and a collection of N sites, the parameters :math:\mu, :math:\tau and :math:\phi are arrays of shape (M, N). :math:\mu is the mean of the logarithms and :math:\tau the between-event standard deviation, associated to the cross correlation, while :math:\phi is the within-event standard deviation, associated to the spatial correlation. math:\tau and :math:\phi are normally N-independent, i.e. each array of shape (M, N) actually contains N copies of the same M values read from the coefficient table of the GMPE. In the OpenQuake engine each rupture has associated a random seed generated from the parameter ses_seed given in the job.ini file, therefore given a fixed number E of events it is possible to generate a deterministic distribution of ground motion fields, i.e. an array of shape (M, N, E). Technically such feature is implemented in the class openquake.hazardlib.calc.gmf.GmfComputer. The algorithm used there is to generate two arrays of normally distributed numbers called :math:\epsilon_\tau (of shape (M, E)) and :math:\epsilon_\phi (of shape (M, N, E)), one using the between-event standard deviation :math:\tau and the other using the within-event standard deviation :math:\phi, while keeping the same mean :math:\mu. Then the ground motion fields are generated as an array of shape (M, N, E) with the formula .. math:: gmf = exp(\mu + crosscorrel(\epsilon_\tau) + spatialcorrel(\epsilon\phi)) The details depend on the form of the cross correlation model and of the spatial correlation model and you have to study the source code if you really want to understand how it works, in particular how the correlation matrices are extracted from the correlation models. By default, if no cross correlation nor spatial correlation are specified, then there are no correlation matrices and :math:crosscorrel(\epsilon_\tau) and :math:spatialcorrel(\epsilon\phi) are computed by using scipy.stats.truncnorm. Otherwise scipy.stats.multivariate_normal with a correlation matrix of shape (M, M) is used for cross correlation and scipy.stats.multivariate_normal distribution with a matrix of shape (N, N) is used for spatial correlation. Notice that the truncation feature is lost if you use correlation, since scipy does not offer at truncated multivariate_normal distribution. Not truncating the normal distribution can easily generated non-physical fields, but even if the truncation is on it is very possible to generate exceedingly large ground motion fields, so the user has to be *very* careful. Correlation is important because its presence normally causes the risk to increase, i.e. ignoring the correlation will under-estimate the risk. The best way to play with the correlation is to consider a scenario_risk calculation with a single rupture and to change the cross and spatial correlation models. Possibilities are to specify in the job.ini all possible combinations of cross_correlation = FullCrossCorrelation cross_correlation = GodaAtkinson2009 ground_motion_correlation_model = JB2009 ground_motion_correlation_model = HM2018 including removing one or the other or all correlations.