hybrid greedy training — detailed notes#
Detailed methodology and configuration for Hybrid greedy and space-filling training.
run_hybrid_greedy combines one error-indicator-selected point per adaptation
batch with geometric maximin coverage. An independent validation error controls
termination. It does not calibrate error indicators against QoI errors.
Algorithm and interfaces#
Initialization draws initial_sample_size rows directly from
ParameterSpace.generate_samples. The parameter space controls the distribution,
including LHS when configured; the workflow adds no LHS construction. Repeated or
metric-equivalent initial rows are removed in sampler order. This differs from
Batch space-filling ROM training, whose initialization remains maximin-based.
The workflow executes the initial FOM batch, constructs a ROM, and validates it before any adaptation. Each subsequent round:
Draws a fresh
candidate_pool_sizepool and excludes points equivalent to historical training samples.Evaluates the current ROM’s raw error indicator at every remaining candidate and selects the largest, breaking ties by input order.
Selects up to
batch_size - 1further points by maximin distance, accounting for all historical samples, the greedy point, and points already selected in this batch. Both selection steps use the same candidate pool.Executes the entire selected FOM batch concurrently, rebuilds using all accumulated training data, and validates again.
batch_size=1 gives purely greedy adaptation with the same validation stopping
rule. A short distinct candidate pool or remaining FOM budget shortens a batch.
An empty admissible pool stops with candidate_pool_exhausted; it does not
prove the entire parameter domain is exhausted. Accepted FOM training runs are
retained and never repeated.
The FOM implements QoiModel. The builder implements
QoiModelBuilderWithTrainingData and receives aligned training directories,
parameter rows, and QoI rows from all completed batches. Its production ROM
must implement QoiModelWithErrorEstimate, including
compute_error_estimate(run_directory, parameter_dict). Missing methods produce
a diagnostic error. Indicators must be finite, nonnegative scalars. They rank
candidates only and need not have the units or normalization of the validation
error. Indicator failures report candidate parameters, index, path, and model stage.
Public API and example#
- romtools.workflows.hybrid_greedy.run_hybrid_greedy(fom_model, rom_model_builder, parameter_space, absolute_work_dir, tolerance, initial_sample_size=10, batch_size=5, candidate_pool_size=1000, distance_metric=None, max_concurrent_fom_runs=5, random_seed=1, *, error_functor=None, validation_strategy=None, max_iterations=20, max_fom_samples=None, create_rom_run_directories=True)[source]#
Train with one greedy point and up to
batch_size - 1maximin points.Initialization draws directly from
parameter_space.generate_samples; duplicate/metric-equivalent rows are removed in sampler order. Each later round draws a fresh pool, excludes training-equivalent points, ranks raw error indicators, and completes the batch by maximin selection from the same pool. Ties use candidate order. No parameter normalization is applied. A short pool or remaining FOM budget may shorten a batch.The four-argument builder receives all accumulated FOM directories, parameter rows, and QoI rows. Production ROMs must implement QoiModelWithErrorEstimate. Indicators rank candidates only; the unchanged space-filling validation strategy controls stopping (default: maximum held-out relative L2 error over five folds). Initial training is validated before any adaptation.
Candidate ROM evaluations are serial and use temporary directories removed after selection, including on failure. Set
create_rom_run_directoriesto False for in-memory models: calls still receive nominal absolute paths, which need not exist. Validation retains its existing directory behavior.FOM batches use process-isolated execution with independent directories; parallel FOM objects must support multiprocessing spawn serialization. All tasks finish before any rebuild or failure is reported. Failed batches retain FOM files and never enter a ROM build.
max_iterationsincludes initialization;max_fom_samplescaps training runs, not custom validation references. Output must be an absent or empty absolute directory. Restart and automatic retries are not supported.- Parameters:
fom_model (QoiModel)
rom_model_builder (QoiModelBuilderWithTrainingData)
parameter_space (ParameterSpace)
absolute_work_dir (str)
tolerance (float)
initial_sample_size (int)
batch_size (int)
candidate_pool_size (int)
distance_metric (Callable | None)
max_concurrent_fom_runs (int)
random_seed (int)
error_functor (Callable | None)
validation_strategy (Callable | None)
max_iterations (int)
max_fom_samples (int | None)
create_rom_run_directories (bool)
- Return type:
- class romtools.workflows.hybrid_greedy.HybridGreedyResult(rom_model, training_parameters, training_qois, training_dirs, validation_errors, sample_counts, greedy_parameters, greedy_error_indicators, converged, termination_reason)[source]#
Bases:
objectFinal ROM, accumulated FOM data, and completed-round selection history.
greedy_parametersandgreedy_error_indicatorscontain one entry per adaptation round, excluding initialization.sample_countsandvalidation_errorsinclude initialization.- Parameters:
rom_model (QoiModelWithErrorEstimate)
training_parameters (ndarray)
training_qois (ndarray)
training_dirs (Tuple[str, ...])
validation_errors (ndarray)
sample_counts (ndarray)
greedy_parameters (ndarray)
greedy_error_indicators (ndarray)
converged (bool)
termination_reason (str)
The result holds the final ROM, accumulated training arrays/directories,
validation errors and cumulative sample counts (including initialization), and
greedy_parameters / greedy_error_indicators (one entry per completed
adaptation round). hybrid_greedy_stats.npz records the same histories plus FOM
run times; hybrid_greedy_status.log records progress and failures. Output must
be an absent or empty absolute directory. There is no restart/resume support.
examples/hybrid_greedy_demo.py is a complete surrogate example. It adapts the
existing scalar Gaussian-process builder to expose predictive standard deviation
as the greedy indicator. This indicator is distinct from the measured K-fold
QoI error. Its initial design uses the existing LHS sampler:
from pathlib import Path
from examples.hybrid_greedy_demo import ScalarFom, UncertaintyBuilder
from romtools.workflows import run_hybrid_greedy
from romtools.workflows.parameter_spaces import UniformParameterSpace
from romtools.workflows.sampling_methods import LatinHypercubeSampler
if __name__ == "__main__":
result = run_hybrid_greedy(
ScalarFom(), UncertaintyBuilder(),
UniformParameterSpace(["x"], [0], [1], LatinHypercubeSampler),
str(Path("hybrid_training").resolve()), tolerance=0.02,
initial_sample_size=5, batch_size=3, candidate_pool_size=256,
max_concurrent_fom_runs=3, max_iterations=6, max_fom_samples=20,
create_rom_run_directories=False,
)
print(result.termination_reason, result.validation_errors)
Run the complete example from the checkout with a fresh output directory:
python examples/hybrid_greedy_demo.py --work-dir /tmp/hybrid-greedy-demo
For a reusable geometric selector that accepts an explicit candidate pool, use
select_maximin_samples (also exported from romtools.workflows):
- romtools.workflows.space_filling.select_maximin_samples(candidates, existing_samples, batch_size, distance_metric=None)[source]#
Select up to
batch_sizedistinct rows from an explicit candidate pool.Ties use input order; with no existing samples, start at the first candidate. Zero distance excludes equivalent points. Euclidean distances are vectorized and updated incrementally; custom metrics may use nonnumeric parameter rows. Input arrays are never modified.