Correlation modules refactor #1 – architectural base

doc/getting-started/demos-tutorials/index.rst

@@ -521,8 +521,8 @@ A demo showing an example of Event Based PSHA calculation is provided with the f
 
 	[event_based_params]
 	ses_per_logic_tree_path = 100
-	ground_motion_correlation_model =
-	ground_motion_correlation_params =
+	spatial_correlation_model =
+	spatial_correlation_params =
 
 	[output]
 	export_dir = ...

doc/user-guide/advanced/advanced-calculations.rst

@@ -322,7 +322,7 @@ In order to perform a conditional spectrum calculation you need to specify, in a
 classical calculation:
 
 1. a reference intensity measure type (i.e. imt_ref = SA(0.2))
-2. a cross correlation model (i.e. cross_correlation = BakerJayaram2008)
+2. a cross correlation model (i.e. cross_imt_correlation_model = BakerJayaram2008)
 3. a set of poes (i.e. poes = 0.01 0.1)
 
 The engine will compute a mean conditional spectrum for each ``poe`` and site, as well as the usual mean uniform hazard 

doc/user-guide/configuration-file/event-based-psha-config.rst

@@ -28,8 +28,8 @@ in the ``calculation_configuration`` part). Additionally, in this section the us
 model to be used for the generation of ground motion fields.::
 
 	ses_per_logic_tree_path = 5
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 The acceptable flags for the parameter ``vs30_clustering`` are ``False`` and ``True``, with a capital ``F`` and ``T`` 
 respectively. ``0`` and ``1`` are also acceptable flags.

doc/user-guide/configuration-file/event-based-risk-config.rst

@@ -42,8 +42,8 @@ event based damage calculation is shown in the listing below.::
 	number_of_logic_tree_samples = 0
 
 	[correlation]
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 	[hazard_calculation]
 	random_seed = 24
@@ -129,8 +129,8 @@ event based risk calculation is shown in the listing below.::
 	gsim_logic_tree_file = gsim_logic_tree.xml
 
 	[correlation]
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 	[hazard_calculation]
 	random_seed = 24

doc/user-guide/configuration-file/scenario-hazard-config.rst

@@ -28,8 +28,8 @@ The basic job configuration file required for running a scenario hazard calculat
 	site_model_file = site_model.csv site_model_stations.csv
 
 	[correlation]
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 	[hazard_calculation]
 	intensity_measure_types = PGA, SA(0.3), SA(1.0)

doc/user-guide/configuration-file/scenario-risk-config.rst

@@ -101,8 +101,8 @@ damage distribution for a portfolio of assets due to the ground motion fields.
 	gsim = BooreAtkinson2008
 	intensity_measure_types = PGA, SA(0.3)
 	number_of_ground_motion_fields = 1000
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 **Scenario damage example**::
 
@@ -306,8 +306,8 @@ The only change that needs to be made in the hazard job configuration file is to
 	gsim_logic_tree_file = gsim_logic_tree.xml
 	intensity_measure_types = PGA, SA(0.3)
 	number_of_ground_motion_fields = 1000
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 **Example 5**
 
@@ -338,8 +338,8 @@ is shown in the listing below.::
 	maximum_distance = 200.0
 	gsim = BooreAtkinson2008
 	number_of_ground_motion_fields = 1000
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 	[fragility]
 	structural_fragility_file = structural_fragility_model.xml
@@ -411,8 +411,8 @@ is shown in the listing below.::
 	maximum_distance = 200.0
 	gsim = BooreAtkinson2008
 	number_of_ground_motion_fields = 1000
-	ground_motion_correlation_model = JB2009
-	ground_motion_correlation_params = {"vs30_clustering": True}
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
 
 	[vulnerability]
 	structural_vulnerability_file = structural_vulnerability_model.xml

doc/user-guide/workflows/scenario-hazard.rst

@@ -316,8 +316,9 @@ file like the following::
 	number_of_ground_motion_fields = 10
 	truncation_level = 3
 	shakemap_id = usp000fjta
-	spatial_correlation = yes
-	cross_correlation = yes
+	spatial_correlation_model = JayaramBaker2009
+	spatial_correlation_params = {"vs30_clustering": True}
+	cross_imt_correlation_model = BakerCornell2006
 
 This example refers to the 2007 Mw8.0 Pisco earthquake in Peru 
 (see https://earthquake.usgs.gov/earthquakes/eventpage/usp000fjta#shakemap). 
@@ -385,27 +386,16 @@ Irrespective of the input, the engine will perform the following operations:
 Correlation
 ***********
 
-By default the engine tries to compute both the spatial correlation and the cross 
-correlation between different intensity measure types. Please note that if you 
-are using MMI as intensity measure type in your vulnerability model, it is not 
-possible to apply correlations since those are based on physical measures.
+ShakeMap and regular calculations use the same named correlation models. Set
+``spatial_correlation_model`` and/or ``cross_imt_correlation_model`` to a
+registered model name. Omitting a parameter disables that kind of correlation.
+The example above preserves the historical ShakeMap defaults: Jayaram and Baker
+(2009) spatial correlation with clustered Vs30, and Baker and Cornell (2006)
+cross-IMT correlation.
 
-For each kind of correlation you have three choices, that you can set in the 
-*job.ini*, for a total of nine combinations::
-
-	- spatial_correlation = yes, cross_correlation = yes  # the default
-	- spatial_correlation = no, cross_correlation = no   # disable everything
-	- spatial_correlation = yes, cross_correlation = no
-	- spatial_correlation = no, cross_correlation = yes
-	- spatial_correlation = full, cross_correlation = full
-	- spatial_correlation = yes, cross_correlation = full
-	- spatial_correlation = no, cross_correlation = full
-	- spatial_correlation = full, cross_correlation = no
-	- spatial_correlation = full, cross_correlation = yes
-
-yes means using the correlation matrix of the `Silva-Horspool <https://onlinelibrary.wiley.com/doi/abs/10.1002/eqe.3154>`__
-paper; *no* mean using no correlation; *full* means using an all-ones correlation 
-matrix.
+MMI is not a physical ground-motion measure, so correlation models configured
+for MMI-only ShakeMaps are ignored. Other IMTs are checked against each
+model's declared scope before the calculation starts.
 
 Apart from performance considerations, disabling either the spatial correlation 
 or the cross correlation (or both) might be useful to see how significant the 
@@ -438,8 +428,9 @@ is feasible, so the risk computation can be performed.
 
 Clearly in situations in which the number of hazard sites is too large, 
 approximations will have to be made such as using a larger *region_grid_spacing*. 
-Disabling spatial AND cross correlation makes it possible run much larger 
-calculations. The performance can be further increased by not using a ``truncation_level``.
+Omitting both correlation model parameters makes it possible to run much larger
+calculations. The performance can be further increased by not using a
+``truncation_level``.
 
 When applying correlation, a soft cap on the size of the calculations is defined. 
 This is done and modifiable through the parameter ``cholesky_limit`` which refers to 
@@ -463,4 +454,4 @@ Mean ground motion field by GMPE, used to reduce disk space and make risk calcul
 
 Mean ground motion field by event, used for debugging/plotting purposes.
 
-Single-rupture hazardlib mean ground motion field, used for analysis/plotting purposes.
+Single-rupture hazardlib mean ground motion field, used for analysis/plotting purposes.

openquake/calculators/base.py

@@ -617,7 +617,7 @@ def read_inputs(self):
         self._read_risk4()
 
         if (oq.calculation_mode == 'event_based' and
-                oq.ground_motion_correlation_model and
+                oq.spatial_correlation_model and
                 len(self.sitecol) > oq.max_sites_correl):
             raise ValueError('You cannot use a correlation model with '
                              f'{self.N} sites [{oq.max_sites_correl=}]')
@@ -1784,7 +1784,8 @@ def store_gmfs_from_shakemap(calc, haz_sitecol, assetcol):
         # calculations with MMI should be executed
         if len(oq.imtls) == 1:
             # only MMI intensities
-            if oq.spatial_correlation != 'no' or oq.cross_correlation != 'no':
+            if (oq.spatial_correlation_model or
+                    oq.cross_imt_correlation_model):
                 logging.warning('Calculations with MMI intensities do not '
                                 'support correlation. No correlations '
                                 'are applied.')
@@ -1800,11 +1801,14 @@ def store_gmfs_from_shakemap(calc, haz_sitecol, assetcol):
         # no MMI intensities, calculation with or without correlation
         if oq.impact:
             gmf_dict = {'kind': 'basic'}  # possibly add correlation
-        elif oq.spatial_correlation != 'no' or oq.cross_correlation != 'no':
-            # cross correlation and/or spatial correlation after S&H
+        elif (oq.spatial_correlation_model or
+              oq.cross_imt_correlation_model):
+            # spatial and cross-IMT correlation after Silva and Horspool
             gmf_dict = {'kind': 'Silva&Horspool',
-                        'spatialcorr': oq.spatial_correlation,
-                        'crosscorr': oq.cross_correlation,
+                        'spatial_model':
+                        oq.get_spatial_correlation_model(),
+                        'cross_imt_model':
+                        oq.get_cross_imt_correlation_model(),
                         'cholesky_limit': oq.cholesky_limit}
         else:
             # no correlation required, basic calculation is faster

openquake/calculators/event_based.py

@@ -189,15 +189,17 @@ def get_computer(cmaker, ebr, sites, sec_perils=(),
                 ebr, sites, sites.complete.filtered(station_sids),
                 station_data.loc[station_sids],
                 observed_imts, cmaker,
-                oq.correl_model, oq.cross_correl,
-                oq.ground_motion_correlation_params,
+                oq.get_spatial_correlation_model(),
+                oq.get_cross_imt_correlation_model(),
+                oq.spatial_correlation_params,
                 oq.number_of_ground_motion_fields,
                 oq._amplifier, sec_perils)
         else:
             logging.warning('There are no stations!')
 
     return GmfComputer(
-        ebr, sites, cmaker, oq.correl_model, oq.cross_correl,
+        ebr, sites, cmaker, oq.get_spatial_correlation_model(),
+        oq.get_cross_imt_correlation_model(),
         oq._amplifier, sec_perils)
 
 

openquake/calculators/postproc/compute_mrd.py

@@ -20,7 +20,8 @@
 import numpy
 from openquake.baselib import parallel
 from openquake.hazardlib.calc.mrd import calc_mean_rate_dist
-from openquake.hazardlib import contexts, cross_correlation as cc
+from openquake.hazardlib import contexts
+from openquake.hazardlib.correlation_models.registry import get_model
 
 
 class Input(object):
@@ -70,7 +71,7 @@ def main(dstore, imt1, imt2, cross_correlation, seed, meabins, sigbins,
 
     NB: this is meant to work only for parametric ruptures!
     """
-    crosscorr = getattr(cc, cross_correlation)()
+    crosscorr = get_model(cross_correlation, 'cross_imt')
     oq = dstore['oqparam']
     N = len(dstore['sitecol'])
     L1 = oq.imtls.size // len(oq.imtls) - 1

openquake/calculators/postproc/conditional_spectrum.py

@@ -175,9 +175,10 @@ def main(dstore):
     logging.warning('Conditional spectrum calculations are still '
                     'experimental')
     oq = dstore['oqparam']
-    if not oq.cross_correl:
-        raise InvalidFile("%(job_ini)s: you must specify cross_correlation"
-                          % oq.inputs)
+    if not oq.get_cross_imt_correlation_model():
+        raise InvalidFile(
+            "%(job_ini)s: you must specify cross_imt_correlation_model"
+            % oq.inputs)
     if not oq.imt_ref:
         raise InvalidFile("%(job_ini)s: you must specify imt_ref" % oq.inputs)
     if not oq.poes:

openquake/calculators/views.py

@@ -367,7 +367,7 @@ def view_params(token, dstore):
               'rupture_mesh_spacing', 'complex_fault_mesh_spacing',
               'width_of_mfd_bin', 'area_source_discretization',
               'pointsource_distance',
-              'ground_motion_correlation_model', 'minimum_intensity',
+              'spatial_correlation_model', 'minimum_intensity',
               'random_seed', 'master_seed', 'ses_seed']
     if 'risk' in oq.calculation_mode:
         params.append('avg_losses')

openquake/commands/shakemap2gmfs.py

@@ -26,7 +26,9 @@
 
 # see qa_tests_data/scenario/case_21
 def main(id, site_model='', *, num_gmfs: int = 1, random_seed: int = 42,
-         trunclevel: float = 3, spatialcorr='yes', crosscorr='yes',
+         trunclevel: float = 3, spatial_correlation_model='',
+         spatial_correlation_params='', cross_imt_correlation_model='',
+         cross_imt_correlation_params='',
          cholesky_limit: int = 10_000, imt_mode='warn'):
     """
     Given a shakemap ID and a path to a site_model.csv file build a
@@ -46,6 +48,12 @@ def main(id, site_model='', *, num_gmfs: int = 1, random_seed: int = 42,
                  calculation_mode='scenario',
                  random_seed=str(random_seed),
                  inputs={'job_ini': '<memory>'})
+    if spatial_correlation_model:
+        param['spatial_correlation_model'] = spatial_correlation_model
+        param['spatial_correlation_params'] = spatial_correlation_params
+    if cross_imt_correlation_model:
+        param['cross_imt_correlation_model'] = cross_imt_correlation_model
+        param['cross_imt_correlation_params'] = cross_imt_correlation_params
     if site_model:
         param['inputs']['site_model'] = [os.path.abspath(site_model)]
     else:
@@ -68,8 +76,9 @@ def main(id, site_model='', *, num_gmfs: int = 1, random_seed: int = 42,
         calc.datastore['sitecol'] = sitecol
         calc.datastore['full_lt'] = logictree.FullLogicTree.fake()
         gmfdic = {'kind': 'Silva&Horspool',
-                  'spatialcorr': spatialcorr,
-                  'crosscorr': crosscorr,
+                  'spatial_model': oq.get_spatial_correlation_model(),
+                  'cross_imt_model':
+                  oq.get_cross_imt_correlation_model(),
                   'cholesky_limit': cholesky_limit}
         store_gmfs(calc, sitecol, shakemap, gmfdic)
     gmv = float(calc.datastore.read_df('gmf_data')[imts[0]].max())
@@ -82,7 +91,9 @@ def main(id, site_model='', *, num_gmfs: int = 1, random_seed: int = 42,
 main.num_gmfs = 'Number of GMFs to generate'
 main.random_seed = 'Random seed to use'
 main.trunclevel = 'Truncation level'
-main.spatialcorr = 'Spatial correlation'
-main.crosscorr = 'Cross correlation among IMTs'
+main.spatial_correlation_model = 'Spatial correlation model name'
+main.spatial_correlation_params = 'Spatial model parameter dictionary'
+main.cross_imt_correlation_model = 'Cross-IMT correlation model name'
+main.cross_imt_correlation_params = 'Cross-IMT model parameter dictionary'
 main.cholesky_limit = 'Cholesky Limit'
 main.imt_mode = 'if "strict", raise an error in case expected imts are missing'

openquake/commands/tests/commands_test.py

@@ -656,8 +656,7 @@ def test_shakemap2gmfs(self):
         with chdir(os.path.dirname(case_25.__file__)):
             with redirect_stdout(io.StringIO()) as out:
                 sap.runline('openquake.commands shakemap2gmfs usp0006dv8 '
-                            'site_model_uniform_grid_rock.csv -n 1 -t 0 '
-                            '--spatialcorr no -c no')
+                            'site_model_uniform_grid_rock.csv -n 1 -t 0')
             got = out.getvalue()
             assert f'gmv={exp}' in got