Add log-uniform sampling method

Author: matthewhoffman

compass/landice/tests/ensemble_generator/ensemble_templates/default/spinup/ensemble_generator.cfg

@@ -11,23 +11,26 @@ ensemble_template = default
 # Additional runs can be added and run to an existing ensemble
 # without affecting existing runs, but trying to set up a run
 # that already exists will generate a warning and skip that run.
-# If using uniform sampling, start_run should be 0 and end_run should be
-# equal to (max_samples - 1), otherwise unexpected behavior may result.
+# If using uniform or log-uniform sampling, start_run should be 0 and
+# end_run should be equal to (max_samples - 1), otherwise unexpected
+# behavior may result.
 # These values do not affect viz/analysis, which will include any
 # runs it finds.
 start_run = 0
 end_run = 3
 
-# sampling_method can be either 'sobol' for a space-filling Sobol sequence
-# or 'uniform' for uniform sampling.  Uniform sampling is most appropriate
-# for a single parameter sensitivity study.  It will sample uniformly across
-# all dimensions simultaneously, thus sampling only a small fraction of
-# parameter space
+# sampling_method can be 'sobol' for a space-filling Sobol sequence,
+# 'uniform' for linear sampling, or 'log-uniform' for logarithmic sampling.
+# Uniform and log-uniform are most appropriate for a single-parameter
+# sensitivity study because they sample each active parameter using the
+# same rank ordering, thus sampling only a small fraction of parameter space
+# in higher dimensions.
 sampling_method = sobol
 
 # maximum number of samples to be considered.
 # max_samples needs to be greater or equal to (end_run + 1)
-# When using uniform sampling, max_samples should equal (end_run + 1).
+# When using uniform or log-uniform sampling, max_samples should equal
+# (end_run + 1).
 # When using Sobol sequence, max_samples ought to be a power of 2.
 # max_samples should not be changed after the first set of ensemble.
 # So, when using Sobol sequence, max_samples might be set larger than

compass/landice/tests/ensemble_generator/spinup_ensemble/__init__.py

@@ -93,12 +93,10 @@ def configure(self):
         if max_samples < self.end_run:
             sys.exit("ERROR: max_samples is exceeded by end_run")
         sampling_method = section.get('sampling_method')
-        param_unit_values = _sample_parameter_unit_values(
-            sampling_method=sampling_method, n_params=n_params,
-            max_samples=max_samples)
-
         parameter_specs = _populate_parameter_vectors(
-            parameter_specs, param_unit_values)
+            parameter_specs=parameter_specs,
+            sampling_method=sampling_method,
+            max_samples=max_samples)
 
         spec_by_name = {spec['name']: spec for spec in parameter_specs}
 
@@ -181,45 +179,51 @@ def _get_parameter_specs(section):
     return specs
 
 
-def _sample_parameter_unit_values(sampling_method, n_params, max_samples):
-    """Create an ``(max_samples, n_params)`` array in unit space.
+def _populate_parameter_vectors(parameter_specs, sampling_method,
+                                max_samples):
+    """Generate and scale samples to each parameter range.
 
-    The returned values are in the range ``[0, 1]`` and are later scaled to
-    each parameter's configured min/max bounds.
+    This function updates each ``spec['vec']`` in ``parameter_specs`` and
+    returns the same list for explicit readability at call site.
+    ``sobol`` creates a space-filling sequence in unit space,
+    ``uniform`` creates linearly spaced samples, and ``log-uniform`` samples
+    linearly in log10 space (requiring strictly positive bounds).
 
     Returns
     -------
-    numpy.ndarray
-        Unit-space samples with shape ``(max_samples, n_params)``.
+    list of dict
+        The same ``parameter_specs`` list with each ``spec['vec']`` populated.
     """
+    n_params = len(parameter_specs)
     if sampling_method == 'sobol':
         print(f"Generating Sobol sequence for {n_params} parameter(s)")
         sampler = qmc.Sobol(d=n_params, scramble=True, seed=4)
-        return sampler.random(n=max_samples)
-
-    if sampling_method == 'uniform':
-        print(f"Generating uniform sampling for {n_params} parameter(s)")
+        param_unit_values = sampler.random(n=max_samples)
+    elif sampling_method in {'uniform', 'log-uniform'}:
+        print(f"Generating {sampling_method} sampling for "
+              f"{n_params} parameter(s)")
         samples = np.linspace(0.0, 1.0, max_samples).reshape(-1, 1)
-        return np.tile(samples, (1, n_params))
-
-    sys.exit("ERROR: Unsupported sampling method specified.")
-
+        param_unit_values = np.tile(samples, (1, n_params))
+    else:
+        sys.exit("ERROR: Unsupported sampling method specified.")
 
-def _populate_parameter_vectors(parameter_specs, param_unit_values):
-    """Scale unit samples to configured parameter ranges.
+    if sampling_method == 'log-uniform':
+        for spec in parameter_specs:
+            if spec['min'] <= 0.0 or spec['max'] <= 0.0:
+                sys.exit(
+                    "ERROR: log-uniform sampling requires positive min/max "
+                    f"for parameter '{spec['name']}'.")
 
-    This function updates each ``spec['vec']`` in ``parameter_specs`` and
-    returns the same list for explicit readability at call site.
-
-    Returns
-    -------
-    list of dict
-        The same ``parameter_specs`` list with each ``spec['vec']`` populated.
-    """
     for idx, spec in enumerate(parameter_specs):
         print('Including parameter ' + spec['name'])
-        spec['vec'] = param_unit_values[:, idx] * \
-            (spec['max'] - spec['min']) + spec['min']
+        if sampling_method == 'log-uniform':
+            log_min = np.log10(spec['min'])
+            log_max = np.log10(spec['max'])
+            spec['vec'] = 10.0 ** (param_unit_values[:, idx] *
+                                   (log_max - log_min) + log_min)
+        else:
+            spec['vec'] = param_unit_values[:, idx] * \
+                (spec['max'] - spec['min']) + spec['min']
     return parameter_specs
 
 

docs/developers_guide/landice/test_groups/ensemble_generator.rst

@@ -125,6 +125,7 @@ Spinup run-control options (for example, ``start_run``, ``end_run``,
 are read from ``[ensemble_generator]``, while spinup resource paths and
 related values (for example ``input_file_path`` and ``iceshelf_area_obs``)
 are read from ``[spinup_ensemble]``.
+Supported sampling methods are ``sobol``, ``uniform``, and ``log-uniform``.
 The values for each parameter are
 passed to the ``EnsembleMember`` constructor to define each run.
 

docs/users_guide/landice/test_groups/ensemble_generator.rst

@@ -6,7 +6,8 @@ ensemble_generator
 The ``landice/ensemble_generator`` test group creates ensembles of MALI
 simulations with different parameter values.  The ensemble framework
 sets up a user-defined number of simulations with parameter values selected
-from either uniform sampling or a space-filling Sobol sequence.
+from uniform sampling, log-uniform sampling, or a space-filling Sobol
+sequence.
 
 A test case in this test group consists of a number of ensemble members,
 and one ensemble manager.
@@ -157,23 +158,27 @@ The template-specific spinup config options (from
    # Additional runs can be added and run to an existing ensemble
    # without affecting existing runs, but trying to set up a run
    # that already exists will generate a warning and skip that run.
-   # If using uniform sampling, start_run should be 0 and end_run should be
-   # equal to (max_samples - 1), otherwise unexpected behavior may result.
+  # If using uniform or log-uniform sampling, start_run should be 0 and
+  # end_run should be equal to (max_samples - 1), otherwise unexpected
+  # behavior may result.
    # These values do not affect viz/analysis, which will include any
    # runs it finds.
    start_run = 0
    end_run = 3
 
-   # sampling_method can be either 'sobol' for a space-filling Sobol sequence
-   # or 'uniform' for uniform sampling.  Uniform sampling is most appropriate
-   # for a single parameter sensitivity study.  It will sample uniformly across
-   # all dimensions simultaneously, thus sampling only a small fraction of
-   # parameter space
+  # sampling_method can be 'sobol' for a space-filling Sobol sequence,
+  # 'uniform' for linear sampling, or 'log-uniform' for logarithmic
+  # sampling between min and max parameter bounds.
+  # Uniform and log-uniform are most appropriate for a single-parameter
+  # sensitivity study because they sample each active parameter using the
+  # same rank ordering, thus sampling only a small fraction of parameter
+  # space in higher dimensions.
    sampling_method = sobol
 
    # maximum number of samples to be considered.
    # max_samples needs to be greater or equal to (end_run + 1)
-   # When using uniform sampling, max_samples should equal (end_run + 1).
+  # When using uniform or log-uniform sampling, max_samples should equal
+  # (end_run + 1).
    # When using Sobol sequence, max_samples ought to be a power of 2.
    # max_samples should not be changed after the first set of ensemble.
    # So, when using Sobol sequence, max_samples might be set larger than
@@ -238,6 +243,9 @@ The parameter sampling definitions live in a separate section,
 dimension ordering, special parameters are unprefixed, and namelist
 parameters use the ``nl.`` prefix with a companion ``.option_name``.
 
+For ``log-uniform`` sampling, each parameter bound must be strictly
+positive because sampling is performed in log space.
+
 .. code-block:: cfg
 
    [ensemble.parameters]