Public API

adaptivepy

AdaptivePy: adaptive sampling for molecular dynamics trajectories.

__version__ module-attribute

__version__ = '1.0.0'

run_adaptive_sampling

run_adaptive_sampling(config_path: str | Path, config: Optional[RunConfig] = None) -> Dict[str, List[SeedResult]]

Execute a full adaptive sampling run from a YAML configuration.

Workflow

1. Load features (and optionally validate trajectories).
2. Cluster the concatenated feature matrix.
3. Compute cluster statistics.
4. Apply each configured policy and select seed frames.
5. Write metadata, assignments, model, and optional PDBs.

Parameters:

Name	Type	Description	Default
config_path	str or Path	Path to the YAML configuration file.	required
config	RunConfig or None	Pre-parsed configuration. If None, loaded from config_path.	None

Returns:

Type	Description
dict	Mapping from policy name to lists of :class:SeedResult.

Raises:

Type	Description
FileNotFoundError	If required input paths do not exist.
ValueError	If validation checks fail.

api

High-level API orchestrating the adaptive sampling workflow.

run_adaptive_sampling

run_adaptive_sampling(config_path: str | Path, config: Optional[RunConfig] = None) -> Dict[str, List[SeedResult]]

Execute a full adaptive sampling run from a YAML configuration.

Workflow

1. Load features (and optionally validate trajectories).
2. Cluster the concatenated feature matrix.
3. Compute cluster statistics.
4. Apply each configured policy and select seed frames.
5. Write metadata, assignments, model, and optional PDBs.

Parameters:

Name	Type	Description	Default
config_path	str or Path	Path to the YAML configuration file.	required
config	RunConfig or None	Pre-parsed configuration. If None, loaded from config_path.	None

Returns:

Type	Description
dict	Mapping from policy name to lists of :class:SeedResult.

Raises:

Type	Description
FileNotFoundError	If required input paths do not exist.
ValueError	If validation checks fail.

validate_config

validate_config(config_path: str | Path) -> RunConfig

Validate a configuration file and input data without running clustering.

Parameters:

Name	Type	Description	Default
config_path	str or Path	Path to the YAML configuration file.	required

Returns:

Type	Description
RunConfig	Parsed configuration if validation succeeds.

Raises:

Type	Description
ValueError	If validation fails.

models

Core data models for AdaptivePy.

FrameRecord dataclass

FrameRecord(traj_id: int, frame_id: int, features: ndarray, cluster_id: Optional[int] = None, global_index: Optional[int] = None)

A single frame tracked through the adaptive sampling pipeline.

Attributes:

Name	Type	Description
traj_id	int	Index of the source trajectory.
frame_id	int	Frame index within the source trajectory.
features	ndarray	Feature vector for this frame, shape (n_features,).
cluster_id	int or None	Assigned cluster label after clustering.
global_index	int or None	Row index in the concatenated feature matrix.

Dataset dataclass

Dataset(frames: List[FrameRecord] = list(), feature_matrix: Optional[ndarray] = None, traj_index_map: Dict[int, tuple[int, int]] = dict(), traj_names: List[str] = list())

Internal representation of loaded trajectory features.

Attributes:

Name	Type	Description
frames	list of FrameRecord	One record per frame across all trajectories.
feature_matrix	ndarray	Concatenated features, shape (n_total_frames, n_features).
traj_index_map	dict	Maps traj_id to (start_index, end_index) in feature_matrix.
traj_names	list of str	Basenames of feature files (without extension), e.g. traj_0.

SeedResult dataclass

SeedResult(seed_id: int, policy: str, traj_id: int, frame_id: int, cluster_id: Optional[int], global_index: int)

A selected seed frame produced by a policy.

Attributes:

Name	Type	Description
seed_id	int	Sequential identifier within a policy run.
policy	str	Name of the policy that selected this seed.
traj_id	int	Source trajectory index.
frame_id	int	Frame index within the source trajectory.
cluster_id	int or None	Cluster from which the seed was drawn, or None for frame-level policies that do not use clustering.
global_index	int	Row index in the concatenated feature matrix.