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 = {}#

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.

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.

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.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.

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.

Cross-IMT models#

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.