Correlation modules refactor #1 – architectural base - #11708
Merged
Conversation
Introduce common spatial, cross-IMT, and joint spatial-cross-IMT interfaces with explicit residual-component metadata and a model registry. Move each existing correlation implementation into its own canonical module with standardized class and function names. Preserve the current sampling algorithms, provide a direct Cholesky fast path with PSD repair only on failure, and keep NoCrossCorrelation and FullCrossCorrelation explicitly scoped to cross-IMT behavior.
Turn openquake.hazardlib.correlation and openquake.hazardlib.cross_correlation into documented compatibility modules that re-export the canonical implementations. Retain every existing public class and helper name so downstream imports and current job configurations continue to work without warnings or numerical changes during the deprecation window.
Resolve spatial and cross-IMT model names through the unified registry while retaining all existing job.ini identifiers and truncation behavior. Add regression coverage for aliases, metadata, component validation, IMT-major covariance ordering, PSD fallback behavior, and identity between legacy imports and canonical model classes.
Rename the shared truncated-normal sampling capability so it does not imply that every subclass is calibrated for between-event residuals. Keep Bradley2012 marked as a total-residual model while preserving the legacy CrossCorrelationBetween import and all existing configuration behavior.
Introduce canonical spatial and cross-IMT model settings, constructor parameters, and resolved-object names throughout the engine while preserving regular-calculation compatibility aliases. Route ShakeMap sampling through the shared registry, replace yes/no/full switches with named models or omission, and add BakerCornell2006 to reproduce the historical ShakeMap cross-IMT calculation. Keep correlation package initializers lightweight and legacy modules as documented compatibility facades.
Update current documentation, QA calculations, and server fixtures to use the canonical spatial_correlation_model, spatial_correlation_params, cross_imt_correlation_model, and cross_imt_correlation_params names. Use full canonical class names in maintained examples while leaving legacy aliases available for downstream job files. Document omission as the way to disable ShakeMap correlation and named models as the way to enable it.
Keep the configured between-event truncation level when constructing cross-IMT sampling models, matching the legacy resolver's split-truncation behavior. Mark lazy registry loading complete only after every model package imports successfully so a transient import failure can be retried.
micheles
reviewed
Aug 14, 2026
| 'spatial_correlation_params', | ||
| 'cross_correlation': 'cross_imt_correlation_model', | ||
| 'spatial_correlation': 'spatial_correlation_model'} | ||
|
|
Contributor
There was a problem hiding this comment.
I like that you are keeping backward compability
Resolve the conditioned GMF conflict by combining the registry-based correlation model names with master's optimized truncation-level-zero path and vector covariance scaling. Retain the upstream event-based and risk performance changes while preserving the correlation refactor's backward-compatible configuration behavior.
Contributor
|
Overall I like the plan and also the implementation. LGTM if all tests are green. Good job! |
CB-quakemodel
approved these changes
Aug 14, 2026
Use the 2019 journal publication year for the new canonical HeresiMiranda model class, module, registry entry, and QA configuration. Preserve the established HM2018 and HM2018CorrelationModel names as compatibility aliases and cover both old and new names in the registry tests.
Document the journal citation and DOI alongside each implemented Baker-Cornell, Baker-Jayaram, Goda-Atkinson, Bradley, Jayaram-Baker, and Heresi-Miranda correlation model. Keep the references in the canonical per-model modules so their scientific provenance is easy to review.
Record the correlation model registry and per-model module refactor, the standardized regular and ShakeMap correlation settings, and the corrected Heresi-Miranda publication year with model references.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Establishing the architectural base for #11230.
This PR:
openquake.hazardlib.correlationandcross_correlationas backward compatibility modules, to be retained for a few releases at least until the new correlation module is well tested and functioning efficiently;spatial_correlation_modelspatial_correlation_paramscross_imt_correlation_modelcross_imt_correlation_paramsyes|no|fullsyntax which deviates from regular scenario calculations;BakerCornell2006to preserve the historical ShakeMap cross-IMT behavior for now, which seems to be the provenance of the current hard-coded cross-correlation model in hazardlib/shakemap/gmfs.py, to be updated soon in upcoming PRs related to Generate ShakeMap GMFs fromshake_result.hdfinstead ofgrid.xmlanduncertainty.xml#11706.Existing sampling algorithms, truncation level behavior, and numerical results are preserved in this PR.
This PR deliberately does not yet implement a joint spatial-cross-IMT model or new efficient sampling algorithms; those will follow in smaller PRs to keep reviews manageable.