Committee Training

The committee-training API orchestrates multiple seeded TorchANNPotential runs while preserving the existing single-member training primitive.

The main workflow is:

  • train a committee with TorchCommitteePotential.train()

  • reload a saved committee run with TorchCommitteePotential.from_directory() or load specific member files with TorchCommitteePotential.from_files()

  • aggregate PyTorch-side predictions with TorchCommitteePotential.predict()

  • export committee members to .nn.ascii files with TorchCommitteePotential.to_aenet_ascii() for the Fortran-backed ensemble interfaces

Committee Config

class aenet.torch_training.TorchCommitteeConfig(num_members: int, base_seed: int | None = None, member_seeds: list[int] | None = None, max_parallel: int = 1, devices: list[str] | None = None, output_dir: PathLike | str | None = None)[source]

Bases: object

Configuration for committee training orchestration.

Parameters:

  • num_members (int) – Number of independently trained committee members.

  • base_seed (int, optional) – Base run-level seed for deterministic member-seed derivation. Member i receives base_seed + i unless member_seeds is provided explicitly.

  • member_seeds (list[int], optional) – Explicit per-member run seeds. When provided, the list length must equal num_members and overrides base_seed.

  • max_parallel (int, optional) – Maximum number of committee members to train concurrently. Default: 1.

  • devices (list[str], optional) – Explicit device assignment pool. Member devices are assigned round-robin across this list. When omitted, members inherit TorchTrainingConfig.device.

  • output_dir (str or Path, optional) – Output directory for committee artifacts. Defaults to committee_run in the current working directory.

base_seed: int | None = None
devices: list[str] | None = None
max_parallel: int = 1
member_seeds: list[int] | None = None
num_members: int
output_dir: PathLike | str | None = None

Committee Potential

class aenet.torch_training.TorchCommitteePotential(arch: dict[str, list[tuple[int, str]]], descriptor: Any)[source]

Bases: object

Committee-training orchestration built on top of TorchANNPotential.

Parameters:

  • arch (dict[str, list[tuple[int, str]]]) – Shared per-species network architecture for all members.

  • descriptor (Any) – Shared descriptor instance for all members.

classmethod from_directory(path: PathLike | str, device: str | None = None) → TorchCommitteePotential[source]

Build a committee from a saved committee output directory.

Parameters:

  • path (str | Path) – Committee output directory or the committee_metadata.json file inside it.

  • device (str, optional) – Device used when loading the saved member models.

Returns:

Committee wrapper with member models loaded from the saved committee run.

Return type:

TorchCommitteePotential

classmethod from_files(model_paths: Sequence[PathLike | str], device: str | None = None) → TorchCommitteePotential[source]

Build a committee from one or more saved member model files.

Parameters:

  • model_paths (sequence[str | Path]) – Saved model.pt files produced by TorchANNPotential.save() or by committee training.

  • device (str, optional) – Device used when loading the saved member models.

Returns:

Committee wrapper with the loaded members cached for inference and export.

Return type:

TorchCommitteePotential

last_result: TorchCommitteeTrainResult | None
load_members(device: str | None = None) → list[TorchANNPotential][source]

Load committee member models from the latest saved committee result.

Parameters:

device (str, optional) – Device used when loading the saved member models. When omitted, models are loaded on CPU.

Returns:

Loaded member trainers in committee order.

Return type:

list[TorchANNPotential]

member_model_paths() → list[Path][source]

Return the saved model paths for the current committee members.

Returns:

Saved model paths in member order.

Return type:

list[pathlib.Path]

predict(structures: list[Structure] | list[Any] | list[PathLike], eval_forces: bool = False, config: Any | None = None, aggregation: str = 'mean', reference_member: int = 0) → list[AenetEnsembleResult][source]

Predict committee energies and uncertainties for one or more structures.

Parameters:

  • structures (list) – Same structure inputs accepted by aenet.torch_training.TorchANNPotential.predict().

  • eval_forces (bool, optional) – If True, also aggregate atomic-force predictions.

  • config (PredictionConfig, optional) – Prediction configuration passed through to each member.

  • aggregation ({"mean", "reference"}, optional) – Aggregation mode for the reported energy and forces.

  • reference_member (int, optional) – Reference member index used when aggregation='reference'.

Returns:

List-like committee result containing aggregate per-structure predictions and the per-member PredictOut objects.

Return type:

TorchCommitteePredictResult

predict_dataset(dataset: torch.utils.data.Dataset, eval_forces: bool = False, config: Any | None = None, aggregation: str = 'mean', reference_member: int = 0) → TorchCommitteePredictResult[source]

Predict committee energies and uncertainties for a dataset.

Parameters:

  • dataset (torch.utils.data.Dataset) – Dataset accepted by TorchANNPotential.predict_dataset. Subset wrappers are supported and source indices are tracked back to the root dataset.

  • eval_forces (bool, optional) – Dataset-backed force prediction is currently limited by TorchANNPotential.predict_dataset and is not implemented.

  • config (PredictionConfig, optional) – Prediction configuration passed through to each member.

  • aggregation ({"mean", "reference"}, optional) – Aggregation mode for the reported energy and forces.

  • reference_member (int, optional) – Reference member index used when aggregation='reference'.

Returns:

List-like committee result containing aggregate per-structure predictions, per-member PredictOut objects, and dataset indices/identifiers.

Return type:

TorchCommitteePredictResult

to_aenet_ascii(output_dir: PathLike | str, prefix: str = 'potential', descriptor_stats: dict[str, Any] | None = None, structures: list[Structure] | None = None, compute_stats: bool = True) → list[dict[str, str]][source]

Export all committee members to aenet .nn.ascii files.

Parameters:

  • output_dir (str | Path) – Destination directory for the exported committee.

  • prefix (str, optional) – Filename prefix passed through to each member export.

  • descriptor_stats (dict, optional) – Pre-computed descriptor statistics shared across all members.

  • structures (list[Structure], optional) – Structures used to compute exact descriptor statistics.

  • compute_stats (bool, optional) – Whether descriptor statistics should be computed when they are not provided explicitly.

Returns:

Per-member species-to-file mapping compatible with AenetEnsembleInterface and AenetEnsembleCalculator.

Return type:

list[dict[str, str]]

train(structures: StructureInput | None = None, dataset: Dataset | None = None, train_dataset: Dataset | None = None, test_dataset: Dataset | None = None, config: TorchTrainingConfig | None = None, committee_config: TorchCommitteeConfig | None = None) → TorchCommitteeTrainResult[source]

Train multiple committee members with shared training settings.

Parameters:

  • structures – Same top-level data inputs accepted by aenet.torch_training.TorchANNPotential.train().

  • dataset – Same top-level data inputs accepted by aenet.torch_training.TorchANNPotential.train().

  • train_dataset – Same top-level data inputs accepted by aenet.torch_training.TorchANNPotential.train().

  • test_dataset – Same top-level data inputs accepted by aenet.torch_training.TorchANNPotential.train().

  • config (TorchTrainingConfig, optional) – Shared single-model training configuration used as the baseline for all committee members.

  • committee_config (TorchCommitteeConfig, optional) – Committee orchestration parameters.

Returns:

Structured result containing per-member artifacts and the top-level metadata path.

Return type:

TorchCommitteeTrainResult

Committee Results

class aenet.torch_training.TorchCommitteeTrainResult(output_dir: Path, metadata_path: Path, members: list[TorchCommitteeMemberResult], execution_mode: str)[source]

Bases: object

Top-level result for one committee training run.

property completed_members: list[TorchCommitteeMemberResult]

Return successfully trained committee members.

execution_mode: str
property failed_members: list[TorchCommitteeMemberResult]

Return any members that failed during training.

members: list[TorchCommitteeMemberResult]
metadata_path: Path
output_dir: Path
property stats: dict[str, dict[str, float | int]]

Return aggregate statistics over completed committee members.

to_dataframe()[source]

Return one row per member with status, paths, and final metrics.

property trainouts: list[TrainOut]

Return TrainOut objects for completed members with histories.

class aenet.torch_training.TorchCommitteeMemberResult(member_index: int, seed: int | None, split_seed: int | None, device: str, member_dir: Path, model_path: Path | None, history_json_path: Path | None, history_csv_path: Path | None, summary_path: Path | None, checkpoint_dir: Path | None, status: str, metrics: dict[str, float | None], error: str | None = None)[source]

Bases: object

Structured result for one committee member run.

checkpoint_dir: Path | None
device: str
error: str | None = None
history_csv_path: Path | None
history_json_path: Path | None
member_dir: Path
member_index: int
metrics: dict[str, float | None]
model_path: Path | None
seed: int | None
split_seed: int | None
property stats: dict[str, float]

Return TrainOut-style final metrics for this committee member.

status: str
summary_path: Path | None
to_metadata() → dict[str, Any][source]

Return a JSON-serializable metadata view.

property trainout: TrainOut | None

Return this member’s TrainOut result, loaded from history.json.

The top-level committee metadata stores compact summaries only. Member histories are persisted separately, so this property rebuilds the familiar single-network TrainOut view lazily when it is available.