Ensemble Wrapper

A generic ensemble wrapper that composes N BaseModel instances into a single model. Assembles Predictions.empirical_dist from per-member outputs, supporting seed ensembles, MC dropout ensembles, and combined (seed + dropout) ensembles for uncertainty quantification.

class alf_tools.models.ensemble.EnsembleWrapper(model_factory, config, name='ensemble')

Bases: BaseModel

Generic ensemble wrapper that composes N BaseModel instances.

Assembles Predictions.empirical_dist from per-member outputs: - If a member returns empirical_dist, all its columns are concatenated. - If a member returns only means, that column is appended as a single column.

cleanup()

Delegate cleanup to each ensemble member.

Attempts cleanup on every member regardless of individual failures, then raises a summary RuntimeError if any cleanup calls failed.

Raises:

RuntimeError – If one or more members raise an exception during cleanup. The exception message will summarize all failures.

Return type:

None

featurise(inputs, member_index=0)

Delegate featurisation to the specified ensemble member.

Parameters:

• inputs (LabelledCandidates | list[Candidate]) – Input samples to featurise.

• member_index (int) – Index of the member to use for featurisation. Defaults to 0. Use non-zero values for heterogeneous ensembles where members have distinct featurise implementations.

Return type:

Any

Returns:

Feature representation returned by the specified member’s featurise().

get_epoch_metrics()

Return per-epoch metrics from all members, tagged with member index.

Return type:

list[SurrogateEpochMetrics]

get_training_summary_metrics()

Return summary metrics from all members, tagged with member index.

Return type:

dict[str, float | int | number]

predict(candidate_points)

Aggregate per-member predictions into a single Predictions object.

Return type:

Predictions

Returns:

Predictions with means, variances, and empirical_dist assembled from all member outputs concatenated along the sample axis.

Raises:

ValueError – If members return empirical_dist columns of different widths.

sample(condition=None)

Not implemented; raises NotImplementedError.

Return type:

list[Candidate]

setup(dataset)

Delegate setup to each ensemble member.

Parameters:

dataset (BaseDataset) – The dataset this ensemble will be trained on.

Return type:

None

train(train_data, val_data=None)

Train each member sequentially on full or subsampled training data.

When subsample is configured, each member receives a random subset of train_data. The subsample seed is taken from subsample.seeds[i] if provided, otherwise from the member’s model-init seed.

val_data is forwarded directly to each member unchanged (including None). Members that require a validation set must handle None gracefully.

If any member’s train() call raises, a warning is logged for that member, training continues for the remaining members, and a summary RuntimeError is raised at the end listing all failures.

Raises:

RuntimeError – If one or more members raise an exception during training. The exception message will summarize all failures.

Return type:

None

class alf_tools.models.ensemble.EnsembleWrapperConfig(base_seed=None, member_seeds=None, n_members=None, subsample=None)

Bases: object

Configuration for the generic ensemble wrapper.

Exactly one of base_seed or member_seeds must be provided.

Parameters:

• base_seed (int | None) – Base integer from which member seeds are derived as [base_seed, base_seed+1, …, base_seed+n_members-1]. Requires n_members to also be set.

• member_seeds (list[int] | None) – Explicit list of seeds, one per member. len(member_seeds) determines the number of members. n_members is ignored when this is set.

• n_members (int | None) – Number of ensemble members. Only used when base_seed is set.

• subsample (SubsampleConfig | None) – Optional per-member subsampling config. When None (default), each member trains on the full training dataset.

base_seed: int | None = None

member_seeds: list[int] | None = None

n_members: int | None = None

seeds: list[int]

subsample: SubsampleConfig | None = None

class alf_tools.models.ensemble.SubsampleConfig(fraction, replace=False, seeds=None)

Bases: object

Per-member training data subsampling strategy.

Parameters:

• fraction (float) – Fraction of training samples to use per member. Must be in (0, 1]. 1.0 with replace=False is a no-op (full dataset, no shuffle).

• replace (bool) – Sample with replacement when True (bootstrap), without when False.

• seeds (list[int] | None) – Explicit per-member seeds for the sampler. Length must match the number of ensemble members when provided. When None, each member’s model-init seed is used for data sampling.

fraction: float

replace: bool = False

seeds: list[int] | None = None