adaptivepy-sampling 0.1.0__tar.gz

adaptivepy_sampling-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: adaptivepy-sampling
+Version: 0.1.0
+Summary: Adaptive sampling on MD trajectories via clustering and policy-driven seed selection
+Author: AdaptivePy Contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: joblib>=1.0
+Requires-Dist: mdtraj>=1.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AdaptivePy
+
+Adaptive sampling on molecular dynamics trajectories using clustering-based state space partitioning and policy-driven seed selection.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+1. Prepare feature files (`features/traj_0.npy`, ...) with shape `(n_frames, n_features)`.
+2. Optionally add matching coordinate trajectories (`trajectories/traj_0.xtc`, ...) and a topology file.
+3. Edit `examples/config.yaml` and run:
+
+```bash
+adaptivepy run examples/config.yaml
+```
+
+## CLI
+
+```bash
+adaptivepy run config.yaml
+adaptivepy validate config.yaml
+adaptivepy list-policies
+```
+
+## Python API
+
+```python
+from adaptivepy import run_adaptive_sampling
+
+results = run_adaptive_sampling("config.yaml")
+```

adaptivepy_sampling-0.1.0/README.md

@@ -0,0 +1,35 @@
+# AdaptivePy
+
+Adaptive sampling on molecular dynamics trajectories using clustering-based state space partitioning and policy-driven seed selection.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+1. Prepare feature files (`features/traj_0.npy`, ...) with shape `(n_frames, n_features)`.
+2. Optionally add matching coordinate trajectories (`trajectories/traj_0.xtc`, ...) and a topology file.
+3. Edit `examples/config.yaml` and run:
+
+```bash
+adaptivepy run examples/config.yaml
+```
+
+## CLI
+
+```bash
+adaptivepy run config.yaml
+adaptivepy validate config.yaml
+adaptivepy list-policies
+```
+
+## Python API
+
+```python
+from adaptivepy import run_adaptive_sampling
+
+results = run_adaptive_sampling("config.yaml")
+```

adaptivepy_sampling-0.1.0/adaptivepy/__init__.py

@@ -0,0 +1,7 @@
+"""AdaptivePy: adaptive sampling for molecular dynamics trajectories."""
+
+__version__ = "0.1.0"
+
+from adaptivepy.api import run_adaptive_sampling
+
+__all__ = ["run_adaptive_sampling", "__version__"]

adaptivepy_sampling-0.1.0/adaptivepy/api.py

@@ -0,0 +1,229 @@
+"""High-level API orchestrating the adaptive sampling workflow."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from adaptivepy.clustering import create_clusterer, fit_clusterer
+from adaptivepy.config.schema import RunConfig, load_config
+from adaptivepy.io.loader import (
+    list_trajectory_files,
+    load_features,
+    validate_dataset,
+    validate_feature_trajectory_mapping,
+)
+from adaptivepy.io.trajectory import (
+    build_trajectory_map,
+    validate_trajectory_frame_counts,
+)
+from adaptivepy.models import SeedResult
+from adaptivepy.output.pdb_writer import write_seed_pdbs
+from adaptivepy.output.writer import (
+    write_assignments,
+    write_cluster_model,
+    write_cluster_statistics,
+    write_combined_metadata,
+    write_policy_outputs,
+    write_run_config,
+)
+from adaptivepy.policies import get_policy
+from adaptivepy.selection.frame_selector import select_seeds
+from adaptivepy.stats.cluster_stats import assign_clusters, compute_cluster_stats
+from adaptivepy.utils.io_utils import ensure_dir
+from adaptivepy.utils.logging import setup_logger
+
+logger = logging.getLogger(__name__)
+
+
+def 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
+    ----------
+    config_path : str or Path
+        Path to the YAML configuration file.
+    config : RunConfig or None
+        Pre-parsed configuration. If ``None``, loaded from ``config_path``.
+
+    Returns
+    -------
+    dict
+        Mapping from policy name to lists of :class:`SeedResult`.
+
+    Raises
+    ------
+    FileNotFoundError
+        If required input paths do not exist.
+    ValueError
+        If validation checks fail.
+    """
+    config_path = Path(config_path)
+    if config is None:
+        config = load_config(config_path)
+
+    output_dir = ensure_dir(config.output_dir)
+    log_path = output_dir / "logs.txt"
+    setup_logger("adaptivepy", log_file=log_path)
+    logger.info("Starting AdaptivePy run with config %s", config_path)
+
+    np.random.seed(config.random_seed)
+
+    # --- Load and validate data ---
+    feature_files = sorted(Path(config.features_dir).glob("*.npy"))
+    trajectory_files: Optional[List[Path]] = None
+    trajectory_map: Optional[Dict[int, Path]] = None
+
+    if config.trajectories_dir is not None:
+        trajectory_files = list_trajectory_files(config.trajectories_dir)
+        validate_feature_trajectory_mapping(feature_files, trajectory_files)
+
+    dataset = load_features(config.features_dir)
+    validate_dataset(dataset, trajectory_files)
+
+    if config.trajectories_dir is not None and config.topology is not None:
+        trajectory_map = build_trajectory_map(
+            config.trajectories_dir, dataset.traj_names
+        )
+        expected_counts = {
+            traj_id: end - start
+            for traj_id, (start, end) in dataset.traj_index_map.items()
+        }
+        validate_trajectory_frame_counts(
+            config.topology, trajectory_map, expected_counts
+        )
+
+    # --- Clustering ---
+    clusterer = create_clusterer(
+        method=config.clustering.method,
+        n_clusters=config.clustering.n_clusters,
+        random_state=config.random_seed,
+        params=config.clustering.params,
+    )
+    fit_clusterer(clusterer, dataset.feature_matrix)
+    labels = clusterer.predict(dataset.feature_matrix)
+    assign_clusters(dataset, labels)
+
+    cluster_stats = compute_cluster_stats(dataset)
+    centers = clusterer.cluster_centers_
+
+    logger.info(
+        "Clustering complete: %d clusters, %d total frames",
+        len(cluster_stats),
+        len(dataset.frames),
+    )
+
+    # --- Global artifacts ---
+    write_run_config(config, output_dir, config_path)
+    write_assignments(labels, output_dir)
+    write_cluster_model(clusterer.model, output_dir)
+    write_cluster_statistics(cluster_stats, output_dir)
+
+    # --- Policies ---
+    policy_seeds: Dict[str, List[SeedResult]] = {}
+
+    for policy_name in config.policies:
+        logger.info("Applying policy: %s", policy_name)
+        policy_kwargs = {}
+        if policy_name == "random":
+            policy_kwargs["random_state"] = config.random_seed
+
+        policy = get_policy(policy_name, **policy_kwargs)
+        selected_clusters = policy.select_clusters(
+            cluster_stats, config.n_seeds
+        )
+        seeds = select_seeds(
+            policy_name=policy_name,
+            selected_clusters=selected_clusters,
+            cluster_stats=cluster_stats,
+            cluster_centers=centers,
+            method=config.seed_selection.method,
+            random_state=config.random_seed,
+        )
+        policy_seeds[policy_name] = seeds
+
+        policy_dir = write_policy_outputs(
+            policy_name, seeds, cluster_stats, output_dir
+        )
+
+        if (
+            config.write_pdbs
+            and trajectory_map is not None
+            and config.topology is not None
+        ):
+            write_seed_pdbs(
+                seeds, config.topology, trajectory_map, policy_dir
+            )
+
+        logger.info("Policy %s selected %d seeds", policy_name, len(seeds))
+
+    if len(policy_seeds) > 1:
+        write_combined_metadata(policy_seeds, output_dir)
+
+    logger.info("AdaptivePy run finished. Results written to %s", output_dir)
+    return policy_seeds
+
+
+def validate_config(config_path: str | Path) -> RunConfig:
+    """Validate a configuration file and input data without running clustering.
+
+    Parameters
+    ----------
+    config_path : str or Path
+        Path to the YAML configuration file.
+
+    Returns
+    -------
+    RunConfig
+        Parsed configuration if validation succeeds.
+
+    Raises
+    ------
+    ValueError
+        If validation fails.
+    """
+    config_path = Path(config_path)
+    config = load_config(config_path)
+
+    feature_files = sorted(Path(config.features_dir).glob("*.npy"))
+    if not feature_files:
+        raise ValueError(f"No feature files in {config.features_dir}")
+
+    trajectory_files = None
+    if config.trajectories_dir is not None:
+        trajectory_files = list_trajectory_files(config.trajectories_dir)
+        validate_feature_trajectory_mapping(feature_files, trajectory_files)
+
+    dataset = load_features(config.features_dir)
+    validate_dataset(dataset, trajectory_files)
+
+    if config.trajectories_dir is not None and config.topology is not None:
+        trajectory_map = build_trajectory_map(
+            config.trajectories_dir, dataset.traj_names
+        )
+        expected_counts = {
+            traj_id: end - start
+            for traj_id, (start, end) in dataset.traj_index_map.items()
+        }
+        validate_trajectory_frame_counts(
+            config.topology, trajectory_map, expected_counts
+        )
+
+    for policy_name in config.policies:
+        get_policy(policy_name)
+
+    return config

adaptivepy_sampling-0.1.0/adaptivepy/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI entry points for AdaptivePy."""
+
+from adaptivepy.cli.run import main
+
+__all__ = ["main"]

adaptivepy_sampling-0.1.0/adaptivepy/cli/run.py

@@ -0,0 +1,68 @@
+"""Command-line interface for AdaptivePy."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from adaptivepy import __version__
+from adaptivepy.api import run_adaptive_sampling, validate_config
+from adaptivepy.policies import list_policies
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="adaptivepy")
+def main() -> None:
+    """AdaptivePy: clustering-based adaptive sampling for MD trajectories."""
+
+
+@main.command("run")
+@click.argument("config", type=click.Path(exists=True, path_type=Path))
+def run_cmd(config: Path) -> None:
+    """Run adaptive sampling from a YAML configuration file.
+
+    Parameters
+    ----------
+    config : Path
+        Path to the YAML configuration file.
+    """
+    try:
+        run_adaptive_sampling(config)
+    except Exception as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command("validate")
+@click.argument("config", type=click.Path(exists=True, path_type=Path))
+def validate_cmd(config: Path) -> None:
+    """Validate configuration and input data without running clustering.
+
+    Parameters
+    ----------
+    config : Path
+        Path to the YAML configuration file.
+    """
+    try:
+        validate_config(config)
+        click.echo(f"Configuration valid: {config}")
+    except Exception as exc:
+        click.echo(f"Validation failed: {exc}", err=True)
+        sys.exit(1)
+
+
+@main.command("list-policies")
+def list_policies_cmd() -> None:
+    """List all registered adaptive sampling policies."""
+    policies = list_policies()
+    if not policies:
+        click.echo("No policies registered.")
+        return
+    for name in policies:
+        click.echo(name)
+
+
+if __name__ == "__main__":
+    main()

adaptivepy_sampling-0.1.0/adaptivepy/clustering/__init__.py

@@ -0,0 +1,103 @@
+"""Clustering backend factory and registry."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from adaptivepy.clustering.base import Clusterer
+from adaptivepy.clustering.regular_space import SklearnRegularSpaceClusterer
+from adaptivepy.clustering.sklearn_kmeans import SklearnKMeansClusterer
+from adaptivepy.clustering.sklearn_minibatch import SklearnMiniBatchClusterer
+
+CLUSTERER_REGISTRY: Dict[str, Type[Clusterer]] = {
+    "kmeans": SklearnKMeansClusterer,
+    "minibatch_kmeans": SklearnMiniBatchClusterer,
+    "regular_space": SklearnRegularSpaceClusterer,
+}
+
+
+def create_clusterer(
+    method: str,
+    n_clusters: int,
+    random_state: int | None = None,
+    params: Dict[str, Any] | None = None,
+) -> Clusterer:
+    """Instantiate a registered clustering backend.
+
+    Parameters
+    ----------
+    method : str
+        Clustering method name (``kmeans``, ``minibatch_kmeans``,
+        ``regular_space``).
+    n_clusters : int
+        Target number of clusters (used by k-means variants; mapped to
+        ``max_clusters`` for regular-space when applicable).
+    random_state : int or None
+        Random seed for reproducibility.
+    params : dict or None
+        Additional backend-specific parameters.
+
+    Returns
+    -------
+    Clusterer
+        Unfitted clusterer instance.
+
+    Raises
+    ------
+    ValueError
+        If ``method`` is not registered.
+    """
+    if method not in CLUSTERER_REGISTRY:
+        available = ", ".join(sorted(CLUSTERER_REGISTRY))
+        raise ValueError(f"Unknown clustering method '{method}'. Available: {available}")
+
+    params = dict(params or {})
+    clusterer_cls = CLUSTERER_REGISTRY[method]
+
+    if method == "regular_space":
+        if "min_dist" not in params:
+            raise ValueError(
+                "regular_space clustering requires 'min_dist' in clustering.params."
+            )
+        max_clusters = params.pop("max_clusters", n_clusters)
+        return SklearnRegularSpaceClusterer(
+            min_dist=float(params.pop("min_dist")),
+            max_clusters=int(max_clusters) if max_clusters else None,
+            random_state=random_state,
+            **params,
+        )
+
+    return clusterer_cls(
+        n_clusters=n_clusters,
+        random_state=random_state,
+        **params,
+    )
+
+
+def fit_clusterer(clusterer: Clusterer, X) -> Clusterer:
+    """Fit a clusterer and return it for chaining.
+
+    Parameters
+    ----------
+    clusterer : Clusterer
+        Unfitted clusterer instance.
+    X : np.ndarray
+        Feature matrix.
+
+    Returns
+    -------
+    Clusterer
+        Fitted clusterer.
+    """
+    return clusterer.fit(X)
+
+
+__all__ = [
+    "CLUSTERER_REGISTRY",
+    "Clusterer",
+    "SklearnKMeansClusterer",
+    "SklearnMiniBatchClusterer",
+    "SklearnRegularSpaceClusterer",
+    "create_clusterer",
+    "fit_clusterer",
+]

adaptivepy_sampling-0.1.0/adaptivepy/clustering/base.py

@@ -0,0 +1,73 @@
+"""Abstract base class for clustering backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+import numpy as np
+
+
+class Clusterer(ABC):
+    """Base interface for feature-space clustering algorithms.
+
+    Implementations wrap scikit-learn or custom clustering methods and expose
+    a uniform ``fit`` / ``predict`` API.
+    """
+
+    @abstractmethod
+    def fit(self, X: np.ndarray) -> "Clusterer":
+        """Fit the clusterer to feature data.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Feature matrix of shape ``(n_samples, n_features)``.
+
+        Returns
+        -------
+        Clusterer
+            Fitted clusterer instance (``self``).
+        """
+        ...
+
+    @abstractmethod
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Assign cluster labels to feature data.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Feature matrix of shape ``(n_samples, n_features)``.
+
+        Returns
+        -------
+        np.ndarray
+            Integer cluster labels of shape ``(n_samples,)``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def cluster_centers_(self) -> Optional[np.ndarray]:
+        """Return cluster centroids if available.
+
+        Returns
+        -------
+        np.ndarray or None
+            Array of shape ``(n_clusters, n_features)``, or ``None`` if the
+            method does not define explicit centers.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def model(self) -> Any:
+        """Return the underlying fitted model object for serialization.
+
+        Returns
+        -------
+        object
+            Backend-specific model instance.
+        """
+        ...