romtools.workflows.space_filling#

Batch maximin ROM training with process-isolated FOM runs.

class romtools.workflows.space_filling.KFoldValidation(num_folds=5)[source]#

Bases: object

Maximum held-out sample error from independent subset-trained ROMs.

No additional FOM evaluations are performed. Each validation uses num_folds builds and one held-out ROM evaluation per training sample. The error functor comes from the context; its result is not renormalized.

Parameters:

num_folds (int)

class romtools.workflows.space_filling.SpaceFillingResult(rom_model, training_parameters, training_qois, training_dirs, validation_errors, sample_counts, converged, termination_reason)[source]#

Bases: object

Final production ROM and ordered data from completed training rounds.

Parameters:
  • rom_model (QoiModel)

  • training_parameters (ndarray)

  • training_qois (ndarray)

  • training_dirs (Tuple[str, ...])

  • validation_errors (ndarray)

  • sample_counts (ndarray)

  • converged (bool)

  • termination_reason (str)

class romtools.workflows.space_filling.SpaceFillingValidationContext(rom_model, rom_model_builder, parameter_names, training_parameters, training_qois, training_dirs, iteration, validation_directory, random_seed, error_functor)[source]#

Bases: object

Inputs to a validation callable returning one nonnegative scalar error.

Parameter/QoI rows and training directories have matching order. Arrays are read-only copies. Builders must fit independent models using only their supplied subsets; a fold must not reuse the production ROM’s fitted basis. A custom strategy owns aggregation and can use error_functor to compare its predictions with independently prepared reference QoIs.

Parameters:
  • rom_model (QoiModel)

  • rom_model_builder (QoiModelBuilderWithTrainingData)

  • parameter_names (Tuple[str, ...])

  • training_parameters (ndarray)

  • training_qois (ndarray)

  • training_dirs (Tuple[str, ...])

  • iteration (int)

  • validation_directory (str)

  • random_seed (int)

  • error_functor (Callable)

romtools.workflows.space_filling.relative_l2_error(qoi_rom, qoi_fom)[source]#

Return ||q_rom-q_fom||_2 / max(||q_fom||_2, 1e-12).

Parameters:
  • qoi_rom (ndarray)

  • qoi_fom (ndarray)

Return type:

float

romtools.workflows.space_filling.run_space_filling(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)[source]#

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.

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)

Return type:

SpaceFillingResult

romtools.workflows.space_filling.select_maximin_samples(candidates, existing_samples, batch_size, distance_metric=None)[source]#

Select up to batch_size distinct 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.

romtools.workflows.space_filling.select_space_filling_samples(parameter_space, existing_samples, batch_size, candidate_pool_size=1000, distance_metric=None, random_seed=None)[source]#

Select up to batch_size maximin-separated candidate rows.

Candidates come exclusively from parameter_space.generate_samples. No bounds or parameter normalization are assumed. With no existing rows, the first point is selected randomly; subsequent ties use candidate order. A short result means the sampled pool has insufficient distinct points, not that the entire domain is exhausted. Zero metric distance identifies duplicates, including points coincident with existing training data.

The default metric is Euclidean and requires finite numeric arrays. A custom distance_metric(candidate, reference) must return a finite, nonnegative scalar and may operate on string/object rows. Use it when parameter units, scales, or geometry make raw Euclidean distance unsuitable.

Sampling is reproducible when the space honors its seed argument or uses NumPy’s legacy RNG. Independent, unseeded RNGs owned by custom spaces cannot be controlled by this function. The caller’s NumPy RNG state is preserved.

Parameters:
  • parameter_space (ParameterSpace)

  • existing_samples (ndarray | None)

  • batch_size (int)

  • candidate_pool_size (int)

  • distance_metric (Callable | None)

  • random_seed (int | None)

Return type:

ndarray

Modules

run_space_filling(fom_model, ...[, ...])

Train a ROM by alternating complete maximin FOM batches and validation.

sampling

Compatibility imports for shared adaptive-training utilities.

validation

Compatibility imports for shared adaptive-training utilities.