Source code for romtools.workflows.greedy.run_greedy

#
# ************************************************************************
#
#                         ROM Tools and Workflows
# Copyright 2019 National Technology & Engineering Solutions of Sandia,LLC
#                              (NTESS)
#
# Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.
#
# ROM Tools and Workflows is licensed under BSD-3-Clause terms of use:
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# 3. Neither the name of the copyright holder nor the names of its
# contributors may be used to endorse or promote products derived
# from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
#
# Questions? Contact Eric Parish (ejparis@sandia.gov)
#
# ************************************************************************
#

'''
The greedy procedure iteratively constructs a reduced basis ROM until it reaches a desired tolerance.
The algorithm is as follows:
 1. We generate a parameter training set, :math:`\\mathcal{D}_{\\mathrm{train}}`,
    :math:`|\\mathcal{D}_{\\mathrm{train}}| = N_{\\mathrm{train}}`
 2. We select an initial sample, :math:`\\mu_1 \\in \\mathcal{D}_{\\mathrm{train}}` and set
    :math:`\\mathcal{D}_{\\mathrm{train}}=\\mathcal{D}_{\\mathrm{train}} - \\{\\mu_1\\}`
 3. We then solve the FOM to obtain the solution, :math:`\\mathbf{u}(\\mu_1)`.
 4. We select a second sample, :math:`\\mu_2 \\in \\mathcal{D}_{\\mathrm{train}}` and set
    :math:`\\mathcal{D}_{\\mathrm{train}}=\\mathcal{D}_{\\mathrm{train}} - \\{\\mu_2\\}`
 4. We then solve the FOM to obtain the solution, :math:`\\mathbf{u}(\\mu_2)`.
 5. We employ the first two solutions to compute the trial space, e.g.,

    .. math::

       \\boldsymbol \\Phi = \\mathrm{orthogonalize}(\\mathbf{u}(\\mu_2)) - \\mathbf{u}_{\\mathrm{shift}}, \\\\
       \\mathbf{u}_{\\mathrm{shift}} = \\mathbf{u}(\\mu_1)

 6. We then solve the resulting ROM for the remaining parameter samples :math:`\\mathcal{D}_{\\mathrm{train}}` to
    generate approximate solutions :math:`\\mathbf{u}(\\mu), \\mu \\in \\mathcal{D}_{\\mathrm{train}}`
 7. For each ROM solution :math:`\\mathbf{u}(\\mu), \\mu \\in \\mathcal{D}_{\\mathrm{train}}` we compute an error
    estimate, :math:`e(\\mu)`
 8. If the maximum error estimate is less than some tolerance, we exit the algorithm. If not, we:
   - Set :math:`\\mu^* = \\underset{ \\mu \\in \\mathcal{D}_{\\mathrm{train}} }{ \\mathrm{arg\\; max} } \\; e(\\mu)`
   - Remove :math:`\\mu^{*}` from the training set,
     :math:`\\mathcal{D}_{\\mathrm{train}}=\\mathcal{D}_{\\mathrm{train}} - \\{\\mu^{*}\\}`
   - Solve the FOM for :math:`\\mathbf{u}(\\mu^{*})`
   - Set the reduced basis to be

     .. math::

        \\boldsymbol \\Phi = \\mathrm{orthogonalize}(\\boldsymbol \\Phi, \\mathbf{u}(\\mu^{*})) - \\mathbf{u}_{\\mathrm{shift}}
   - Go back to step 6 and continue until convergence.

This function implements the basic greedy workflow. In addition, we enable an adaptive
error estimate based on a QoI. This is based on the fact that, throughout the greedy algorithm, we have a
history of error indicators as well as a set of FOM and ROM runs for the same parameter instance. We leverage this data
to improve the error estimate. Specifically, for the max error estimates over the first :math:`j` iterations,
:math:`e_1,\\ldots,e_j`, we additionally can access QoI errors :math:`e^q_1,\\ldots,e^q_j` from our FOM-ROM runs, and we
define a scaling based on

.. math::

   C = \\frac{\\sum_{i=1}^j | e^q_j| }{ \\sum_{i=1}^j | e_j | }.

The error at the :math:`j+1` iteration can be approximated by :math:`C e(\\mu)`.
This will adaptively scale the error estimate to match the QoI error as
closely as possible, which can be helpful for defining exit criterion.

Alternatively, if `calibrated_error` is set to `False`, then the scaling factor :math:`C` will always be :math:`1`.
'''

import time
import warnings
from dataclasses import dataclass
from numbers import Integral
from typing import Optional, Tuple
import numpy as np

import romtools.linalg.linalg as la
from romtools.workflows.model_execution import ModelEvaluation, execute_models
from romtools.workflows.models import QoiModel, QoiModelWithErrorEstimate
from romtools.workflows.parameter_spaces import ParameterSpace
from romtools.workflows.workflow_utils import create_empty_dir
from romtools.workflows.model_builders import QoiModelBuilderWithTrainingData


__all__ = ["GreedyResult", "run_greedy", "QoIvsErrorIndicatorRegressor"]


[docs] @dataclass class GreedyResult: """Final ROM, aligned training data, and completed enrichment histories. Error histories describe the ROMs before their corresponding enrichments, rather than independent validation of the final ROM. ``sample_counts`` includes the initial build and every subsequent rebuild. Array fields are independent copies of workflow state; the final ROM is returned directly. """ rom_model: QoiModelWithErrorEstimate training_parameters: np.ndarray training_qois: np.ndarray training_dirs: Tuple[str, ...] training_sample_indices: np.ndarray max_error_indicators: np.ndarray qoi_errors: np.ndarray predicted_qoi_errors: np.ndarray sample_counts: np.ndarray converged: bool termination_reason: str @property def iterations(self) -> int: """Number of completed enrichments after the initial build.""" return len(self.qoi_errors)
def _create_parameter_dict(parameter_names, parameter_values): return dict(zip(parameter_names, parameter_values)) def _compute_qoi(model, evaluation): """Keep one independent, flattened QoI row per completed FOM run.""" return np.asarray( evaluation.compute_qoi(model), ).reshape(-1).copy() def _compute_error_estimate(model, evaluation): return model.compute_error_estimate(evaluation.run_directory, evaluation.parameter_sample) def _exclude_training_samples(parameters, candidates, training): """Exclude exact matches to explicitly supplied/accumulated training rows.""" return np.asarray([ index for index in candidates if not any(np.array_equal(parameters[index], parameters[i]) for i in training) ], dtype=int)
[docs] def run_greedy(fom_model: QoiModel, rom_model_builder: QoiModelBuilderWithTrainingData, parameter_space: ParameterSpace, absolute_work_dir: str = None, tolerance: float = None, testing_sample_size: int = 10, random_seed: int = 1, calibrated_error: bool=True, *, initial_sample_size: int = 2, max_iterations: int = 100, initial_samples: Optional[np.ndarray] = None, create_rom_run_directories: bool = True, absolute_greedy_work_directory: str = None) -> GreedyResult: ''' Train a ROM using adaptive error-indicator-based sample selection. The builder receives ``offline_data_dir``, ``training_data_dirs``, ``training_parameters`` of shape (N, parameter_dimension), and ``training_qois`` of shape (N, qoi_dimension), all in matching training order. Every rebuild includes all completed training FOM runs. Scalars become one-component QoI rows; array QoIs are flattened. Copies of the training arrays are passed so builders cannot modify the sampling pool or accumulated QoI history. The returned ROM must implement ``compute_error_estimate`` in addition to the QoiModel methods. Directory-only builders must be adapted to the four-argument QoiModelBuilderWithTrainingData interface. ``initial_sample_size`` selects the first training rows from the initial candidate pool (default two). ``max_iterations`` bounds the number of subsequent greedy FOM enrichments and defaults to 100; zero builds only the initial ROM. Without explicit initial samples, ``testing_sample_size`` must exceed ``initial_sample_size`` for enrichment so there is an untrained candidate. Calibration and convergence checks retain their existing behavior: the first convergence check follows one enrichment. Run directories are populated once, immediately before their model evaluation. ``initial_samples``, if supplied, is a nonempty (N, parameter_dimension) array of parameter rows to simulate before adaptation. Its row count overrides ``initial_sample_size``; ``testing_sample_size`` then controls a separate adaptation candidate pool. Exact matches to accumulated training rows are excluded from this pool. No domain projection or reuse of existing FOM outputs is performed. ``create_rom_run_directories=False`` skips only per-evaluation ROM run directory creation. Model methods still receive their nominal paths and must support in-memory execution. FOM, offline-data, log, and statistics directories remain available. Returns the final ROM and training history in a ``GreedyResult``, including for initial-only and limit exits. ''' if absolute_greedy_work_directory is not None: warnings.warn( "'absolute_greedy_work_directory' is deprecated; use 'absolute_work_dir' instead.", DeprecationWarning, stacklevel=2, ) if absolute_work_dir is not None: raise TypeError("Specify only 'absolute_work_dir', not both directory arguments.") absolute_work_dir = absolute_greedy_work_directory if absolute_work_dir is None: raise TypeError("'absolute_work_dir' is required") if tolerance is None: raise TypeError("'tolerance' is required") if not isinstance(create_rom_run_directories, bool): raise TypeError("create_rom_run_directories must be a bool") parameter_names = list(parameter_space.get_names()) supplied_initial_samples = initial_samples is not None if supplied_initial_samples: initial_samples = np.asarray(initial_samples).copy() if (initial_samples.ndim != 2 or initial_samples.shape[0] == 0 or initial_samples.shape[1] != len(parameter_names)): raise ValueError("initial_samples must be nonempty and have shape (N, parameter_dimension)") if initial_samples.dtype.kind in "biufc" and not np.all(np.isfinite(initial_samples)): raise ValueError("initial_samples must contain finite numeric values") initial_sample_size = len(initial_samples) for name, value, minimum in ( ("initial_sample_size", initial_sample_size, 1), ("testing_sample_size", testing_sample_size, 1), ("max_iterations", max_iterations, 0), ): if isinstance(value, bool) or not isinstance(value, Integral) or value < minimum: qualifier = "nonnegative" if minimum == 0 else "positive" raise ValueError(f"{name} must be a {qualifier} integer") if not supplied_initial_samples and initial_sample_size > testing_sample_size: raise ValueError("initial_sample_size must not exceed testing_sample_size") if not supplied_initial_samples and max_iterations > 0 and initial_sample_size == testing_sample_size: raise ValueError("testing_sample_size must exceed initial_sample_size for greedy enrichment") np.random.seed(random_seed) if supplied_initial_samples and max_iterations == 0: parameter_samples = initial_samples else: parameter_samples = np.asarray(parameter_space.generate_samples(testing_sample_size)) if parameter_samples.ndim != 2 or parameter_samples.shape[1] != len(parameter_names): raise ValueError("generated samples must have shape (N, parameter_dimension)") if parameter_samples.shape[0] != testing_sample_size: raise ValueError("parameter_space must generate testing_sample_size candidate rows") if supplied_initial_samples: parameter_samples = np.concatenate((initial_samples, parameter_samples), axis=0) training_samples = np.arange(initial_sample_size) samples_left = np.arange(initial_sample_size, len(parameter_samples)) if supplied_initial_samples: samples_left = _exclude_training_samples(parameter_samples, samples_left, training_samples) greedy_directory = absolute_work_dir create_empty_dir(greedy_directory) offline_directory_prefix = 'offline_data' run_directory_prefix = "run_" greedy_file = open(f"{greedy_directory}/greedy_status.log", "w", encoding="utf-8") # pylint: disable=consider-using-with greedy_file.write("Greedy reduced basis status \n") fom_time = 0. rom_time = 0. basis_time = 0. # Run FOM training cases t0 = time.time() training_dirs = [] initial_fom_qois = [] for i in training_samples: greedy_file.write(f"Running FOM sample {i} \n") sample_index = i parameter_dict = _create_parameter_dict(parameter_names,parameter_samples[sample_index]) fom_run_directory = f'{greedy_directory}/fom/{run_directory_prefix}{sample_index}' create_empty_dir(fom_run_directory) fom_model.populate_run_directory(fom_run_directory,parameter_dict) fom_qoi = execute_models( fom_model, [ModelEvaluation(fom_run_directory, parameter_dict)], postprocess=_compute_qoi, ignore_blocking_status=True, )[0].output initial_fom_qois.append(fom_qoi) training_dirs.append(fom_run_directory) fom_qois = np.stack(initial_fom_qois) fom_time += time.time() - t0 # Create ROM bases t0 = time.time() greedy_file.write("Creating ROM bases \n") outer_loop_counter = 0 updated_offline_data_dir = f'{greedy_directory}/rom_iteration_{outer_loop_counter}/{offline_directory_prefix}/' create_empty_dir(updated_offline_data_dir) rom_model = rom_model_builder.build_from_training_dirs( updated_offline_data_dir, list(training_dirs), parameter_samples[training_samples], fom_qois.copy(), ) basis_time += time.time() - t0 converged = False max_error_indicators = np.zeros(0) reg = QoIvsErrorIndicatorRegressor(calibrated_error) qoi_errors = np.zeros(0) predicted_qoi_errors = np.zeros(0) greedy_file.flush() def save_stats(termination_reason): np.savez(f'{greedy_directory}/greedy_stats', max_error_indicators=max_error_indicators, qoi_errors=qoi_errors, predicted_qoi_errors=predicted_qoi_errors, training_samples=training_samples, training_parameters=parameter_samples[training_samples], training_qois=fom_qois, training_dirs=np.asarray(training_dirs), sample_counts=np.arange(initial_sample_size, training_samples.size + 1), fom_time=fom_time, rom_time=rom_time, basis_time=basis_time, initial_sample_size=initial_sample_size, create_rom_run_directories=create_rom_run_directories, max_iterations=max_iterations, iterations=training_samples.size - initial_sample_size, converged=converged, termination_reason=termination_reason) save_stats("running") termination_reason = "max_iterations" while converged is False and outer_loop_counter < max_iterations: if samples_left.size == 0: termination_reason = "candidate_pool_exhausted" break print(f'Greedy iteration # {outer_loop_counter}') error_indicators = np.zeros(samples_left.size) rom_evaluations = {} t0 = time.time() greedy_file.write(f"Greedy iteration # {outer_loop_counter}\n" + f"Parameter samples: \n {parameter_samples}\n") greedy_file.flush() for counter, sample_index in enumerate(samples_left): greedy_file.write(f" Running ROM sample {sample_index}\n") greedy_file.flush() parameter_dict = _create_parameter_dict(parameter_names,parameter_samples[sample_index]) rom_run_directory = f'{greedy_directory}/rom_iteration_{outer_loop_counter}/{run_directory_prefix}{sample_index}' if create_rom_run_directories: create_empty_dir(rom_run_directory) rom_model.populate_run_directory(rom_run_directory,parameter_dict) evaluation = execute_models( rom_model, [ModelEvaluation(rom_run_directory, parameter_dict)], postprocess=_compute_error_estimate, ignore_blocking_status=True, )[0] error_indicators[counter] = evaluation.output rom_evaluations[sample_index] = evaluation rom_time += time.time() - t0 sample_with_highest_error_indicator = samples_left[la.argmax(error_indicators)] max_error_indicator = np.amax(error_indicators) greedy_file.write(f"Sample {sample_with_highest_error_indicator}" " had the highest error indicator of" f" {max_error_indicator} \n") outer_loop_counter += 1 if outer_loop_counter > 1: predicted_max_qoi_error = reg.predict(error_indicators[la.argmax(error_indicators)]) greedy_file.write("Our MLEM error estimate is " f"{predicted_max_qoi_error}\n") greedy_file.flush() if np.amax(predicted_max_qoi_error < tolerance): converged = True print('Run converged, max approximate qoi error' f' = {predicted_max_qoi_error}') break predicted_qoi_errors = np.append(predicted_qoi_errors, predicted_max_qoi_error) # Histories describe completed enrichments, excluding the final # tolerance check that does not select another FOM training sample. max_error_indicators = np.append(max_error_indicators, max_error_indicator) t0 = time.time() greedy_file.write("Running FOM sample" f" {sample_with_highest_error_indicator}\n") greedy_file.flush() ## Identify the sample with the highest error and run FOM fom_run_directory = f'{greedy_directory}/fom/{run_directory_prefix}{sample_with_highest_error_indicator}' parameter_dict = _create_parameter_dict(parameter_names,parameter_samples[sample_with_highest_error_indicator]) create_empty_dir(fom_run_directory) fom_model.populate_run_directory(fom_run_directory, parameter_dict) fom_qoi = execute_models( fom_model, [ModelEvaluation(fom_run_directory, parameter_dict)], postprocess=_compute_qoi, ignore_blocking_status=True, )[0].output fom_time += time.time() - t0 # Get ROM QoI to calibrate our error estimator rom_qoi = _compute_qoi(rom_model, rom_evaluations[sample_with_highest_error_indicator]) qoi_error = np.linalg.norm(rom_qoi - fom_qoi) / np.linalg.norm(fom_qoi) greedy_file.write(f"Sample {sample_with_highest_error_indicator} had " f"an error of {qoi_error}\n") qoi_errors = np.append(qoi_errors, qoi_error) reg.fit(max_error_indicators, qoi_errors) ## Update our samples training_samples = np.append(training_samples, sample_with_highest_error_indicator) fom_qois = np.vstack((fom_qois, fom_qoi)) samples_left = np.delete(samples_left, la.argmax(error_indicators)) # Update ROM basis t0 = time.time() greedy_file.write("Computing ROM bases \n") greedy_file.flush() training_dirs = [f'{greedy_directory}/fom/run_{i}' for i in training_samples] updated_offline_data_dir = f'{greedy_directory}/rom_iteration_{outer_loop_counter}/{offline_directory_prefix}/' create_empty_dir(updated_offline_data_dir) rom_model = rom_model_builder.build_from_training_dirs( updated_offline_data_dir, list(training_dirs), parameter_samples[training_samples], fom_qois.copy(), ) basis_time += time.time() - t0 # Replenish only if another iteration can run. Directory preparation # is deferred until a candidate actually needs a FOM or ROM evaluation. if outer_loop_counter < max_iterations: new_parameter_sample = parameter_space.generate_samples(1) new_sample_number = len(parameter_samples) parameter_samples = np.append(parameter_samples, new_parameter_sample, axis=0) samples_left = np.append(samples_left, new_sample_number) if supplied_initial_samples: samples_left = _exclude_training_samples(parameter_samples, samples_left, training_samples) greedy_file.flush() save_stats("running") if converged: termination_reason = "tolerance" elif termination_reason == "max_iterations": print(f'Maximum greedy iterations ({max_iterations}) reached') else: print('No untrained samples remain in the greedy candidate pool') save_stats(termination_reason) greedy_file.write(f"Stopped: {termination_reason}\n") greedy_file.close() return GreedyResult( rom_model=rom_model, training_parameters=parameter_samples[training_samples].copy(), training_qois=fom_qois.copy(), training_dirs=tuple(training_dirs), training_sample_indices=training_samples.copy(), max_error_indicators=max_error_indicators.copy(), qoi_errors=qoi_errors.copy(), predicted_qoi_errors=predicted_qoi_errors.copy(), sample_counts=np.arange(initial_sample_size, training_samples.size + 1), converged=converged, termination_reason=termination_reason, )
class QoIvsErrorIndicatorRegressor: ''' Regressor for modeling the relationship between QoI error and error indicator. This class provides a simple linear regression model for estimating the scaling factor (c) between QoI error and the error indicator. ''' def __init__(self, calibrated_error: bool=True): ''' Initializes the regressor with a default scaling factor of 1.0. ''' self.__c = 1. self.__calibrated_error = calibrated_error def fit(self, x, y): ''' If calibrated_error was specified, this function fits the regression model to the provided data points (x, y) to estimate the scaling factor. Args: x: Error indicator values. y: Corresponding QoI error values. ''' if self.__calibrated_error: self.__c = np.mean(y) / np.mean(x) def predict(self, x): ''' Predicts QoI error based on the error indicator using the estimated scaling factor. Args: x: Error indicator value(s) for prediction. ''' return self.__c*x