Refactor correlation modules to support combined spatial-cross-correlation models

[raoanirudh]

Motivation

The engine currently supports:

• Same-IMT spatial correlation in hazardlib/correlation.py – this applies to the within-event residuals
• Cross-IMT (non-spatial / same-site) correlation in hazardlib/cross_correlation.py – these models might be either parametric or empirical, might apply to the within-event residuals or between-event residuals or total residuals, and might have been derived for different intensity measure components (IMCs)

GMF generation not involving conditioning on station data, with both spatial and cross-IMT correlation turned on currently applies:

• spatial correlation to within-event residuals per IMT
• cross-IMT correlation to between-event residuals

The conditioned GMF calculator also supports cross-IMT correlation of within-event residuals in addition to the above. The full correlation structure is obtained by composing together the cross-IMT correlation of between-event residuals, cross-IMT correlation of within-event residuals, and spatial correlation to within-event residuals, which might be provided by separate models.

Models such as Loth and Baker (2013)¹, Wang and Du (2013)², Markhvida et al. (2018)³, and Du and Ning (2021)⁴, which provide joint spatial-cross-correlation models (for within-event residuals) cannot be readily implemented in the engine given the current separation into two modules handling correlation.

Monteiro and O’Reilly (2026)⁵ provide a comprehensive overview of 45 ground motion correlation models available in the literature, with Python implementations of each available at https://github.com/vitorazevedomonteiro/correlation-models. Ideally, the OpenQuake engine should be able to support all of these model classes via a unified and extensible architecture.

Goals

• Unify correlation handling into a framework that can provide correlation/covariance for:
  • within-event, between-event, and total residuals (as applicable)
• Support:
  • joint spatial-cross correlation models (IMT×site jointly)
  • non-spatial (single-site) cross-IMT correlation, with the conditional spectra calculator being a primary use case (sep. dist. h = 0)
  • same-IMT spatial correlation
  • the latter two cases should fall out as special cases of the first
• Keep backward compatibility with existing engine configs and outputs as far as possible .

Proposed changes

1) Unified correlation framework

Introduce a small set of interfaces and a registry so that new correlation models can be plugged in consistently:

• SpatialCrossIMTCorrelationModel — returns joint correlations/covariances over (IM, site)
• CrossIMTCorrelationModel — returns IMT×IMT correlations at a single site
• SpatialCorrelationModel — returns site×site correlations for a single IM
• The latter two could be subclasses of the former

Add helpers for converting between total/within/between correlations when sensible (using GSIM tau/phi where available).

2) GMF calculator changes

Update hazardlib/calc/gmf.py to accept three distinct correlation roles:

1. between-event cross-IMT model (existing behavior)
2. within-event same-IMT spatial model (existing behavior)
3. NEW: within-event cross-IMT and/or joint spatial-cross-correlation model to generate joint within-event residual fields across IMTs (should support models such as Loth and Baker (2013), etc. as mentioned above)

Backward-compatible behavior:

• if (3) is not provided, produce the current within-event residual handling.

3) Conditional spectra changes

Update hazardlib/calc/cond_spectra.py so conditional spectra can use a correlation-model object rather than a precomputed rho vector:

• rho = model.rho(conditioning_imt, target_imt, component="total")

Acceptance criteria

• A registry-based mechanism exists to instantiate correlation models by name and metadata (IMT support, component type, etc.).

• GMF simulation supports:

  • same-IMT spatial correlation (existing)
  • between-event cross-IMT correlation (existing)
  • within-event cross-IMT and/or spatial-cross correlation (new)

• Conditional spectra can draw correlations from any supported non-spatial cross-IMT model via a consistent API.

• Unit tests cover representative model outputs and preserve legacy behavior when using legacy settings.

Current modules which would need to be refactored:

• https://github.com/gem/oq-engine/blob/master/openquake/hazardlib/correlation.py
• https://github.com/gem/oq-engine/blob/master/openquake/hazardlib/cross_correlation.py
• https://github.com/gem/oq-engine/blob/master/openquake/hazardlib/calc/gmf.py
• https://github.com/gem/oq-engine/blob/master/openquake/hazardlib/calc/cond_spectra.py
• https://github.com/gem/oq-engine/blob/master/openquake/hazardlib/calc/conditioned_gmfs.py

Note: Computational performance issues to be addressed in a subsequent issue.

Implementation strategy

A more detailed implementation strategy can be found here: Ground motion correlation refactor

References

Footnotes

1. Loth, C., & Baker, J. W. (2013). A spatial cross‐correlation model of spectral accelerations at multiple periods. Earthquake Engineering & Structural Dynamics, 42(3), 397–417. https://doi.org/10.1002/eqe2212 ↩

2. Wang, G., & Du, W. (2013). Spatial cross-correlation models for vector intensity measures (PGA, Ia, PGV, and SAs) considering regional site conditions. Bulletin of the Seismological Society of America, 103(6), 3189–3204. https://doi.org/10.1785/0120130061 ↩

3. Markhvida, M., Ceferino, L., & Baker, J. W. (2018). Modeling spatially correlated spectral accelerations at multiple periods using principal component analysis and geostatistics. Earthquake Engineering & Structural Dynamics, 1107–1123. https://doi.org/10.1002/eqe.3007 ↩

4. Du, W., & Ning, C. L. (2021). Modeling spatial cross-correlation of multiple ground motion intensity measures (SAs, PGA, PGV, Ia, CAV, and significant durations) based on principal component and geostatistical analyses. Earthquake Spectra, 37(1), 486–504. https://doi.org/10.1177/8755293020952442 ↩

5. Monteiro, V. A., & O’Reilly, G. J. (2026). A review of ground motion correlation modelling for regional seismic risk analysis. Bulletin of Earthquake Engineering. https://doi.org/10.1007/s10518-026-02377-0 ↩

[g-weatherill]

@raoanirudh Great to see this coming ... in case it helps, here is my implementation of many of these features that adapt OQ's implementation of correlation to extend it to spatial cross-correlation: https://git.gfz-potsdam.de/shakemap/shakyground2/-/blob/master/shakyground2/correlation.py?ref_type=heads. Unit tests available here: https://git.gfz-potsdam.de/shakemap/shakyground2/-/blob/master/tests/correlation_test.py?ref_type=heads

[raoanirudh]

@raoanirudh Great to see this coming ... in case it helps, here is my implementation of many of these features that adapt OQ's implementation of correlation to extend it to spatial cross-correlation: https://git.gfz-potsdam.de/shakemap/shakyground2/-/blob/master/shakyground2/correlation.py?ref_type=heads. Unit tests available here: https://git.gfz-potsdam.de/shakemap/shakyground2/-/blob/master/tests/correlation_test.py?ref_type=heads

Thanks @g-weatherill, will take a look!

[micheles]

I need to make a comment: PERFORMANCE IS CRUCIAL. The worst thing you can do is to set up a complex framework, just to discover that calculations are too slow to be performed and then all that work is wasted. One must start with a performance study first. For instance we know that one can easily get a 385x slowdown as seen in #11332.