"""Sequential batches of geometrically selected FOM runs for ROM training."""
from dataclasses import dataclass
import os
from typing import Callable, Optional, Tuple
import numpy as np
from romtools.workflows.model_builders import QoiModelBuilderWithTrainingData
from romtools.workflows.models import QoiModel
from romtools.workflows.parameter_spaces import ParameterSpace
from .._adaptive.execution import _evaluate_batch, _process_state
from .._adaptive.sampling import _parameter_names, _positive_integer, select_space_filling_samples
from .._adaptive.validation import (
KFoldValidation, SpaceFillingValidationContext, _build_rom, _error_value,
relative_l2_error, _readonly_copy,
)
[docs]
@dataclass
class SpaceFillingResult:
"""Final production ROM and ordered data from completed training rounds."""
rom_model: QoiModel
training_parameters: np.ndarray
training_qois: np.ndarray
training_dirs: Tuple[str, ...]
validation_errors: np.ndarray
sample_counts: np.ndarray
converged: bool
termination_reason: str
def _save_stats(directory, names, parameters, qois, training_dirs, errors,
counts, run_times, reason):
temporary = os.path.join(directory, ".space_filling_stats.tmp.npz")
np.savez(
temporary, parameter_names=np.asarray(names), training_parameters=parameters,
training_qois=qois, training_dirs=np.asarray(training_dirs),
validation_errors=np.asarray(errors), sample_counts=np.asarray(counts),
fom_run_times=np.asarray(run_times), converged=reason == "tolerance",
termination_reason=reason,
)
os.replace(temporary, os.path.join(directory, "space_filling_stats.npz"))
[docs]
def run_space_filling(
fom_model: QoiModel,
rom_model_builder: QoiModelBuilderWithTrainingData,
parameter_space: ParameterSpace,
absolute_work_dir: str,
tolerance: float,
initial_sample_size: int = 10,
batch_size: int = 5,
candidate_pool_size: int = 1000,
distance_metric: Optional[Callable] = None,
max_concurrent_fom_runs: int = 5,
random_seed: int = 1,
*,
error_functor: Optional[Callable] = None,
validation_strategy: Optional[Callable] = None,
max_iterations: int = 20,
max_fom_samples: Optional[int] = None,
) -> SpaceFillingResult:
"""Train a ROM by alternating complete maximin FOM batches and validation.
``batch_size`` controls new training points independently of the active
process limit ``max_concurrent_fom_runs``. Concurrent FOM objects must be
serializable with multiprocessing's spawn context. All three model methods
execute in one worker task and may use that task's independent directory.
Builders and validation run sequentially in the parent process.
The builder receives directories, parameter rows, and QoI rows in matching
order, using QoiModelBuilderWithTrainingData's four-argument method. It must
build independent models from only the supplied data. Default validation
rebuilds five fold-specific ROMs and returns maximum held-out relative L2
QoI error. ``error_functor(qoi_rom, qoi_fom)`` replaces that per-sample error
completely; no normalization is applied to a custom functor's result.
A custom ``validation_strategy(context)`` owns validation and aggregation.
``max_iterations`` includes the initial batch; ``max_fom_samples`` bounds
training FOM runs scheduled here, excluding any references prepared by a
custom validation strategy. Short candidate pools and final budget-limited
batches are allowed. No restart, automatic retry, or overwrite is performed.
Output must be an absent or empty absolute directory. Failed batches retain
all run files and never trigger a rebuild or enter accepted training data.
"""
for name, value in (
("initial_sample_size", initial_sample_size), ("batch_size", batch_size),
("candidate_pool_size", candidate_pool_size),
("max_concurrent_fom_runs", max_concurrent_fom_runs),
("max_iterations", max_iterations),
):
_positive_integer(value, name)
if max_fom_samples is not None:
_positive_integer(max_fom_samples, "max_fom_samples")
tolerance = _error_value(tolerance, "tolerance")
for name, value in (("distance_metric", distance_metric),
("error_functor", error_functor),
("validation_strategy", validation_strategy)):
if value is not None and not callable(value):
raise TypeError(f"{name} must be callable or None")
for name in ("populate_run_directory", "run_model", "compute_qoi"):
if not callable(getattr(fom_model, name, None)):
raise TypeError(f"fom_model must implement {name}")
if not callable(getattr(rom_model_builder, "build_from_training_dirs", None)):
raise TypeError("rom_model_builder must implement build_from_training_dirs")
names = _parameter_names(parameter_space)
strategy = KFoldValidation() if validation_strategy is None else validation_strategy
error_functor = relative_l2_error if error_functor is None else error_functor
initial_count = min(initial_sample_size, max_fom_samples or initial_sample_size)
if isinstance(strategy, KFoldValidation) and initial_count < strategy.num_folds:
raise ValueError("initial sample count/budget must be at least num_folds")
# Separate streams make sampling independent of validation/build activity.
streams = np.random.SeedSequence(random_seed).spawn(4)
sampling_rng, fom_rng, validation_rng, build_rng = map(np.random.default_rng, streams)
directory = os.fspath(absolute_work_dir)
if not os.path.isabs(directory):
raise ValueError("absolute_work_dir must be absolute")
if os.path.exists(directory) and (not os.path.isdir(directory) or os.listdir(directory)):
raise ValueError("absolute_work_dir must be absent or empty; overwrite/restart is unsupported")
os.makedirs(directory, exist_ok=True)
parameters = None
qois = None
training_dirs, errors, counts, run_times = [], [], [], []
rom = None
reason = "max_iterations"
with open(os.path.join(directory, "space_filling_status.log"), "w", encoding="utf-8") as log:
try:
for iteration in range(max_iterations):
target = initial_sample_size if iteration == 0 else batch_size
if max_fom_samples is not None:
target = min(target, max_fom_samples - len(training_dirs))
batch = select_space_filling_samples(
parameter_space, parameters, target, candidate_pool_size,
distance_metric, int(sampling_rng.integers(0, 2**32)),
)
if iteration == 0:
if not len(batch):
raise ValueError("initial candidate pool contains no samples")
if isinstance(strategy, KFoldValidation) and len(batch) < strategy.num_folds:
raise ValueError("initial candidate pool has fewer distinct samples than num_folds")
if not len(batch):
reason = "candidate_pool_exhausted"
break
start = len(training_dirs)
ids = list(range(start, start + len(batch)))
batch_dirs = [os.path.join(directory, "fom", f"run_{i}") for i in ids]
seeds = [int(fom_rng.integers(0, 2**32)) for _ in ids]
log.write(f"Round {iteration}: selected {len(batch)} FOM samples\n")
log.flush()
batch_qois, times = _evaluate_batch(
fom_model, names, batch, batch_dirs, ids, seeds,
max_concurrent_fom_runs, None if qois is None else qois.shape[1],
)
parameters = batch if parameters is None else np.concatenate((parameters, batch))
qois = batch_qois if qois is None else np.concatenate((qois, batch_qois))
training_dirs.extend(batch_dirs)
run_times.extend(times)
round_directory = os.path.join(directory, f"iteration_{iteration}")
rom = _build_rom(
rom_model_builder, os.path.join(round_directory, "offline_data"),
training_dirs, parameters, qois, int(build_rng.integers(0, 2**32)),
)
validation_directory = os.path.join(round_directory, "validation")
os.makedirs(validation_directory)
validation_seed = int(validation_rng.integers(0, 2**32))
context = SpaceFillingValidationContext(
rom, rom_model_builder, names, _readonly_copy(parameters),
_readonly_copy(qois), tuple(training_dirs), iteration,
validation_directory, validation_seed, error_functor,
)
with _process_state(validation_seed):
error = _error_value(strategy(context), "validation strategy result")
errors.append(error)
counts.append(len(training_dirs))
log.write(f"Round {iteration}: {len(training_dirs)} training samples, error={error:.16g}\n")
log.flush()
if error <= tolerance:
reason = "tolerance"
elif max_fom_samples is not None and len(training_dirs) >= max_fom_samples:
reason = "max_fom_samples"
elif iteration + 1 == max_iterations:
reason = "max_iterations"
else:
reason = "running"
_save_stats(directory, names, parameters, qois, training_dirs,
errors, counts, run_times, reason)
if reason != "running":
break
# Pool exhaustion is detected before another round is built.
_save_stats(directory, names, parameters, qois, training_dirs,
errors, counts, run_times, reason)
log.write(f"Stopped: {reason}\n")
except Exception as exception:
log.write(f"Failed: {exception}\n")
raise
return SpaceFillingResult(
rom, parameters, qois, tuple(training_dirs), np.asarray(errors),
np.asarray(counts), reason == "tolerance", reason,
)