openquake.hazardlib.correlation_models package#

Base interfaces#

Base interfaces shared by ground-motion correlation models.

class openquake.hazardlib.correlation_models.base.CholeskyFactor(lower_triangle: ndarray)[source]#

Bases: object

Dense Cholesky factorization used by the default implementation.

apply(samples)[source]#

lower_triangle: ndarray#

class openquake.hazardlib.correlation_models.base.CorrelationContext(mag: float | None = None, rake: float | None = None, trt: str | None = None, region: str | None = None)[source]#

Bases: object

Optional predictors used by context-dependent correlation models.

mag: float | None = None#

rake: float | None = None#

region: str | None = None#

trt: str | None = None#

class openquake.hazardlib.correlation_models.base.CorrelationFactor(*args, **kwargs)[source]#

Bases: Protocol

A factorization capable of applying correlation to samples.

apply(samples: ndarray) → ndarray[source]#: Apply the factorization to standard-normal samples.

class openquake.hazardlib.correlation_models.base.CorrelationModel[source]#

Bases: object

Common metadata and validation for all correlation models.

CALIBRATED_FOR_INTENSITY_MEASURE_TYPES = None#

DEFINED_FOR_INTENSITY_MEASURE_COMPONENT = None#

DEFINED_FOR_INTENSITY_MEASURE_TYPES = None#

DEFINED_FOR_REGION = None#

DEFINED_FOR_RESIDUAL_COMPONENT = None#

DEFINED_FOR_SA_DAMPING = None#

DEFINED_FOR_SA_PERIOD_RANGE = None#

INTENSITY_MEASURE_TYPE_APPROXIMATIONS = {}#

SUPPORTS_CIRCULANT_EMBEDDING = False#

validate()[source]#: Validate model parameters after construction.

validate_imts(imts)[source]#: Raise when an IMT is outside the model’s declared scope.

class openquake.hazardlib.correlation_models.base.CrossIMTCorrelationModel[source]#

Bases: SpatialCrossIMTCorrelationModel

Cross-IMT correlation at a single site.

These models describe dependence among IMTs but not spatial dependence. When used for within-event residuals, the same IMT correlation is applied independently at each site.

correlation_matrix(imts, component=None, context=None, dtype=<class 'float'>)[source]#: Return an M x M cross-IMT correlation matrix.

covariance(sites, imts, component=None, context=None)[source]#: Embed cross-IMT matrices for each site in IMT-major ordering.

factor(sites, imts, component=None, context=None, ensure_psd=True)[source]#

Factor the small IMT matrix once for all independent sites.

The returned SiteIndependentFactor reuses one M x M Cholesky factor across N sites. This is the sampling equivalent of factoring the full site-and-IMT covariance, without its quadratic memory cost.

get_correlation(from_imt, to_imt)[source]#: Compatibility alias for rho().

get_cross_correlation_mtx(imts)[source]#: Compatibility alias returning the historical float32 matrix.

rho(from_imt, to_imt, component=None, context=None)[source]#: Return the correlation between two IMTs.

class openquake.hazardlib.correlation_models.base.ResidualComponent(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: str, Enum

Residual components for which a model can be calibrated.

BETWEEN_EVENT = 'between'#

TOTAL = 'total'#

WITHIN_EVENT = 'within'#

class openquake.hazardlib.correlation_models.base.SiteIndependentFactor(lower_triangle: ndarray, num_sites: int)[source]#

Bases: object

Cross-IMT factor applied independently at every site.

lower_triangle is the Cholesky factor of the M x M IMT correlation matrix and num_sites is N. In IMT-major ordering, this object applies the equivalent of lower_triangle Kronecker I_N without constructing that (M*N) x (M*N) matrix.

apply(samples)[source]#: Correlate (M*N, E) samples while retaining their shape.

lower_triangle: ndarray#

num_sites: int#

class openquake.hazardlib.correlation_models.base.SpatialCorrelationModel[source]#

Bases: SpatialCrossIMTCorrelationModel

Same-IMT spatial correlation over a collection of sites.

apply_correlation(sites, imt, residuals, stddev_intra=0)[source]#: Apply spatial correlation to sampled within-event residuals.

correlation_matrix(sites, imt, component=None, context=None)[source]#: Return a same-IMT spatial correlation matrix or block.

covariance(sites, imts, component=None, context=None)[source]#: Embed same-IMT matrices in IMT-major diagonal blocks.

get_lower_triangle_correlation_matrix(sites, imt)[source]#: Return the dense Cholesky factor of the correlation matrix.

class openquake.hazardlib.correlation_models.base.SpatialCrossIMTCorrelationModel[source]#

Bases: CorrelationModel

Correlation over a joint, IMT-major vector of sites and IMTs.

correlate(sites, imts, samples, component=None, context=None)[source]#

Correlate standard-normal samples across IMTs and sites.

samples must have shape (M, N, E). The first two dimensions are flattened in IMT-major order before applying the factorization.

correlation_block(distances, imts1, imts2=None, component=None, context=None)[source]#

Return correlation between two IMT-major site vectors.

distances has shape (N1, N2) and the returned matrix has shape (len(imts1) * N1, len(imts2) * N2). Joint models should implement this method so they can also be used for conditioning.

covariance(sites, imts, component=None, context=None)[source]#: Return a covariance matrix with shape (M*N, M*N).

factor(sites, imts, component=None, context=None, ensure_psd=True)[source]#

Return the default dense factorization of covariance().

The fast path attempts Cholesky decomposition directly. A covariance repair is performed only when decomposition fails and ensure_psd is true. Models with efficient structured factorizations should override this method.

class openquake.hazardlib.correlation_models.base.TruncatedCrossIMTCorrelationModel(truncation_level=99.0)[source]#

Bases: CrossIMTCorrelationModel

Cross-IMT model able to sample truncated normal residuals.

get_inter_eps(imts, num_events, rng)[source]#: Return an M x E matrix of correlated event terms.

matrix_dtype#: alias of float

Registry#

Registry for ground-motion correlation models.

class openquake.hazardlib.correlation_models.registry.ModelSpec(name: str, cls: type[openquake.hazardlib.correlation_models.base.CorrelationModel], aliases: tuple[str, ...], model_type: str, description: str)[source]#

Bases: object

Registration metadata for a correlation model.

aliases: tuple[str, ...]#

property calibrated_imts#

cls: type[openquake.hazardlib.correlation_models.base.CorrelationModel]#

description: str#

property imc#

property intensity_measure_type_approximations#

model_type: str#

name: str#

property region#

property residual_component#

property sa_damping#

property sa_period_range#

property supported_imts#

openquake.hazardlib.correlation_models.registry.get_model(name, model_type=None, **parameters)[source]#: Instantiate and validate the model registered under name.

openquake.hazardlib.correlation_models.registry.get_model_class(name, model_type=None)[source]#: Return the class registered under name.

openquake.hazardlib.correlation_models.registry.get_model_specs(model_type=None)[source]#: Return canonical model specifications, optionally by model type.

openquake.hazardlib.correlation_models.registry.register_model(*aliases, description='')[source]#: Register a model class under its canonical name and aliases.

Scalable sampling#

class openquake.hazardlib.correlation_models.circulant_embedding.RegularGridLayout(grid_shape: tuple, spacing: tuple, site_indices: ndarray, crs: int, projected_origin: tuple, maximum_error: float)[source]#

Projected regular-grid geometry for a geographic site collection.

expanded(sites, margin)[source]#: Return a grid enlarged around sites by margin cells.

classmethod from_sites(sites, max_cell_ratio=4)[source]#: Infer a square UTM lattice, retaining holes as unused cells.

grid_coordinates(sites)[source]#: Return fractional row and column coordinates for sites.

property occupancy#: Return the fraction of enclosing grid cells containing a site.

class openquake.hazardlib.correlation_models.circulant_embedding.CirculantEmbeddingFactor(spectral_root: ndarray, grid_shape: tuple, embedded_shape: tuple, num_imts: int, site_indices: ndarray, embedding_multiplier: int, minimum_eigenvalue: float)[source]#

FFT factorization of an IMT-major regular-grid covariance.

Use build() to construct a positive-semidefinite periodic embedding. apply() accepts a two-dimensional array containing one white-noise vector per column and returns fields in IMT-major order.

apply(samples)[source]#: Apply the embedding to columns of independent normal values.

batch_size(memory_budget)[source]#: Return how many realizations fit in the workspace budget.

classmethod build(model, imts, grid_shape, spacing, component=None, context=None, site_indices=None, max_multiplier=8)[source]#: Build an embedding, enlarging it until its spectrum is PSD.

property input_size#: Number of independent values required for each realization.

property output_size#: Number of correlated values returned for each realization.

property workspace_bytes_per_realization#: Conservative FFT workspace estimate for one realization.

class openquake.hazardlib.correlation_models.local_kriging.LocalKrigingFactor(layout: RegularGridLayout, num_imts: int, num_stations: int, on_grid_stations: ndarray, on_grid_cells: ndarray, groups: tuple, error_size: int)[source]#

Map regular-grid fields and local errors to station fields.

apply(grid_fields, errors)[source]#: Return IMT-major station fields for one or more realizations.

classmethod build(model, imts, layout, stations, order=4, component=None, context=None)[source]#: Build fourth-order local conditionals by default.

property nbytes#: Return bytes retained by the station mapping and factors.

Spatial models#

class openquake.hazardlib.correlation_models.spatial.jayaram_baker_2009.JayaramBaker2009(vs30_clustering)[source]#

Bases: SpatialCorrelationModel

Within-event spatial correlation by Jayaram and Baker (2009).

The publication calibrated PGA and 5%-damped SA through 10 seconds. PGV is retained temporarily using OpenQuake’s historical SA(1.0) proxy.

class openquake.hazardlib.correlation_models.spatial.heresi_miranda_2019.HeresiMiranda2019(uncertainty_multiplier=0)[source]#

Bases: SpatialCorrelationModel

Within-event spatial correlation by Heresi and Miranda (2019).

apply_correlation(sites, imt, residuals, stddev_intra)[source]#: Apply spatial correlation to sampled within-event residuals.

class openquake.hazardlib.correlation_models.spatial.aldea_et_al_2022.AldeaEtAl2022[source]#

Bases: SpatialCorrelationModel

Within-event model for the Chilean subduction zone.

class openquake.hazardlib.correlation_models.spatial.schiappapietra_et_al_2022.SchiappapietraEtAl2022NorthernItaly[source]#

Bases: _SchiappapietraEtAl2022

Median model calibrated for Northern Italy.

class openquake.hazardlib.correlation_models.spatial.schiappapietra_et_al_2022.SchiappapietraEtAl2022CentralItaly[source]#

Bases: _SchiappapietraEtAl2022

Median model calibrated for Central Italy.

class openquake.hazardlib.correlation_models.spatial.schiappapietra_et_al_2022.SchiappapietraEtAl2022SouthernItaly[source]#

Bases: _SchiappapietraEtAl2022

Median model calibrated for Southern Italy.

The publication notes that this regional model is less well constrained than the Northern and Central Italy models because only six earthquakes were available for its calibration.

Joint spatial and cross-IMT models#

class openquake.hazardlib.correlation_models.spatial_cross_imt.loth_baker_2013.LothBaker2013[source]#

Bases: SpatialCrossIMTCorrelationModel

Within-event spatial cross-IMT model by Loth and Baker (2013).

The model was calibrated for 5%-damped SA from 0.01 to 10 s. PGA is supported through the conventional SA(0.01) correlation proxy.

class openquake.hazardlib.correlation_models.spatial_cross_imt.markhvida_et_al_2018.MarkhvidaEtAl2018[source]#

Bases: SpatialCrossIMTCorrelationModel

Within-event spatial cross-IMT model by Markhvida et al. (2018).

The model uses all nineteen principal components, following the authors’ current reference implementation, and was calibrated for 5%-damped SA from 0.01 to 5 seconds. PGA is supported through the conventional SA(0.01) correlation proxy; this is an operational approximation rather than a calibrated part of the model.

class openquake.hazardlib.correlation_models.spatial_cross_imt.wang_du_2013.WangDu2013PGAIAPGV(vs30_correlation_range=12.5)[source]#

Bases: _WangDu2013

Joint correlation for the publication’s PGA, IA, and PGV set.

class openquake.hazardlib.correlation_models.spatial_cross_imt.wang_du_2013.WangDu2013SpectralAcceleration(vs30_correlation_range=12.5)[source]#

Bases: _WangDu2013

Joint correlation for 5%-damped SA from 0.01 to 10 seconds.

The publication permits linear interpolation of the tabulated coregionalization matrices. Interpolation can change their marginal variances, so the resulting covariance is normalized to a correlation matrix. This preserves the standard deviations supplied by the GSIM.

class openquake.hazardlib.correlation_models.spatial_cross_imt.du_ning_2021.DuNing2021[source]#

Bases: SpatialCrossIMTCorrelationModel

Published seven-PC within-event joint correlation model.

The 0.9 scale factor in equations 22-24 is common to every principal-component covariance and therefore cancels during the normalization in equation 12. PGA and SA(0.01) are separate calibrated IMTs. Their first seven published coefficients, which are the only ones retained by this simplified model, are identical; their complete 23-PC rows in Table 3 are not.

class openquake.hazardlib.correlation_models.spatial_cross_imt.du_ning_2021.DuNing2021Interpolated[source]#

Bases: DuNing2021

Within-event joint model with explicit off-grid SA interpolation.

The author-supplied Matlab function bilinearly interpolates final correlations in ordinary period. Here the equivalent normalized loading vectors are interpolated first and then renormalized using the zero-distance principal-component covariance. Thus the result equals the Matlab value divided by the square root of its two interpolated marginal variances. It is exact at every published node, symmetric, unit-diagonal, and positive semidefinite for arbitrary periods within 0.01–10 seconds.

Cross-IMT models#

class openquake.hazardlib.correlation_models.cross_imt.abrahamson_et_al_2014.AbrahamsonEtAl2014BetweenEvent(truncation_level=99.0)[source]#

Bases: _AbrahamsonEtAl2014Correlation, TruncatedCrossIMTCorrelationModel

ASK14 between-event cross-IMT correlation.

The table was derived from ASK14 residuals for active shallow crustal earthquakes. The closest application is therefore with the AbrahamsonEtAl2014 GMM, although the engine does not restrict its use with other GMMs.

class openquake.hazardlib.correlation_models.cross_imt.abrahamson_et_al_2014.AbrahamsonEtAl2014WithinEvent[source]#

Bases: _AbrahamsonEtAl2014Correlation, CrossIMTCorrelationModel

ASK14 same-site within-event cross-IMT correlation.

The model correlates IMTs at each site independently. It does not define spatial correlation between different sites and therefore does not replace a joint spatial-cross-IMT model such as Loth and Baker (2013).

class openquake.hazardlib.correlation_models.cross_imt.baker_bradley_2017.BakerBradley2017[source]#

Bases: CrossIMTCorrelationModel

Corrected total-residual amplitude and duration correlation.

The paper reports active-shallow-crustal NGA-West2 records with magnitude greater than 5 and Joyner-Boore distance below 100 km. SA is supported at the 105 published, 5%-damped periods from 0.01 to 10 s. RSD575 and RSD595 are also directly calibrated. The amplitude IMTs use RotD50, whereas the duration GMM uses the geometric mean; model-wide component metadata is therefore intentionally unset.

class openquake.hazardlib.correlation_models.cross_imt.baker_cornell_2006.BakerCornell2006[source]#

Bases: CrossIMTCorrelationModel

Total-residual spectral correlation by Baker and Cornell (2006).

The publication calibrated 5%-damped SA from 0.05 to 5 seconds. PGA and PGV are retained temporarily using the engine’s historical SA(0.05) proxy.

class openquake.hazardlib.correlation_models.cross_imt.baker_jayaram_2008.BakerJayaram2008[source]#

Bases: CrossIMTCorrelationModel

Total-residual cross-IMT correlation for GMRotI50.

The publication calibrated 5%-damped SA from 0.01 to 10 seconds. PGA is represented by the model’s shortest calibrated period, SA(0.01).

class openquake.hazardlib.correlation_models.cross_imt.bradley_2012.Bradley2012(truncation_level=99.0)[source]#

Bases: TruncatedCrossIMTCorrelationModel

Total-residual correlation between PGV and spectrum-based IMTs.

class openquake.hazardlib.correlation_models.cross_imt.goda_atkinson_2009.GodaAtkinson2009(truncation_level=99.0)[source]#

Bases: TruncatedCrossIMTCorrelationModel

Between-event cross-IMT correlation by Goda and Atkinson (2009).

The model was calibrated for 5%-damped SA from 0.1 to 5 seconds. PGA is retained temporarily using the engine’s historical SA(0.05) proxy, which lies outside that calibrated range.

matrix_dtype#: alias of float32

class openquake.hazardlib.correlation_models.cross_imt.no_cross_correlation.NoCrossCorrelation(truncation_level=99.0)[source]#

Bases: TruncatedCrossIMTCorrelationModel

Represent the absence of cross-IMT correlation.

get_inter_eps(imts, num_events, rng)[source]#: Return an M x E matrix of correlated event terms.

class openquake.hazardlib.correlation_models.cross_imt.full_cross_correlation.FullCrossCorrelation(truncation_level=99.0)[source]#

Bases: TruncatedCrossIMTCorrelationModel

Represent perfect cross-IMT correlation.

get_inter_eps(imts, num_events, rng)[source]#: Return an M x E matrix of correlated event terms.

Compatibility modules#

openquake.hazardlib.correlation and openquake.hazardlib.cross_correlation are compatibility modules for the historical APIs. New code should import canonical classes from openquake.hazardlib.correlation_models subpackages or resolve configured models through the registry.