feat: bump to v0.2.0 with refreshed docs and AI instructions

Summary of changes since v0.1.0 (now reflected in the docs / AI
instruction files):

- Pluggable compute backends (mdtraj / numba / cupy / torch / jax)
  for compute_distances, compute_rmsd_matrix, and compute_dccm.
  DCCM defaults to "numpy" (BLAS GEMM); distance and RMSD default
  to "mdtraj" for PBC correctness.
- sklearn-style callable clustering classes: Gromos, Hierarchical,
  DBSCAN, HDBSCAN, KMeans, MiniBatchKMeans, RegularSpace.
- compute_delta_rmsf with MSF-space averaging and SEM propagation.
- compute_native_contacts (vectorised) and refreshed plot helpers
  (plot_delta_rmsf, plot_feature_clustering, plot_native_contacts).
- Stable float dtype system (_dtype.py, DtypeArg, float32 default).

Docs / AI instruction refresh:

- docs/index.md: new "Highlights" section, backends + clustering.
- docs/guide/analysis.md: correct compute_delta_rmsf example,
  new DCCM backend table and dispatch notes.
- README.md: backends row covers DCCM, clustering row lists all
  seven classes, new "Cluster conformations" quick-start snippet.
- CLAUDE.md / AGENTS.md: DCCM default exception, refreshed
  _backends/ tree, clustering class table, np.floating Protocol
  return type, GPU cache cleanup expanded.
- .cursor/rules/*.mdc: project + python-analysis + shell-scripts
  brought in line with the current dtype system and backend
  conventions; shell shebang corrected to env bash.

Verified with: pre-commit (ruff/mypy/mdformat/shellcheck) clean,
pytest -m "not gpu and not slow and not benchmark" (583 passed),
mkdocs build --clean --strict (no warnings).

Author: FridrichMethod

.cursor/rules/project.mdc

@@ -9,10 +9,15 @@ alwaysApply: true
 
 ```
 src/mdpp/
+├── _types.py    # shared type aliases (StrPath, PathLike, DtypeArg)
+├── _dtype.py    # float dtype config (get/set_default_dtype, resolve_dtype)
 ├── constants.py # physical constants (GAS_CONSTANT_KJ_MOL_K, DEFAULT_TEMPERATURE_K)
 ├── core/        # trajectory I/O (load_trajectory, align), file parsers (read_xvg, read_edr)
 ├── analysis/    # compute_* functions returning frozen dataclass results
-├── plots/       # plot_* functions returning matplotlib Axes
+│   └── _backends/   # private subpackage: mdtraj/numba/cupy/torch/jax kernels for
+│                     # distances, RMSD matrix, DCCM; BackendRegistry[F] + Literals
+├── chem/        # RDKit-based cheminformatics (descriptors, fingerprints, similarity, filters)
+├── plots/       # plot_* / draw_* / view_* functions returning matplotlib Axes / 3D widgets
 └── prep/        # system preparation (protein fixing, ligand topology, trajectory manipulation)
 ```
 
@@ -40,15 +45,19 @@ Every `compute_*` function follows this contract:
 
 ## Compute Backend Default Rule
 
-Every public analysis function that accepts a `backend=` argument MUST default to `"mdtraj"`. Other backends (`numba`, `torch`, `jax`, `cupy`) exist for performance (50-200x CPU speedup or GPU acceleration) and MUST be opted into explicitly by the caller.
+Every public analysis function that accepts a `backend=` argument MUST default to `"mdtraj"` **when mdtraj provides a native kernel for that computation**. Other backends (`numba`, `torch`, `jax`, `cupy`) exist for performance (50-200x CPU speedup or GPU acceleration) and MUST be opted into explicitly by the caller. The only current exception is `compute_dccm`, which defaults to `"numpy"` because mdtraj has no covariance kernel -- `numpy`'s BLAS GEMM is multi-threaded and ships with the base install.
 
 Why:
 
 - Only `mdtraj` supports periodic boundary conditions -- defaulting to anything else silently drops PBC.
 - Consistent defaults across all analysis functions avoid surprising behavior when users switch between them.
 - The GPU backends (`[gpu]` extra) must never be required for the common path.
 
-**Never change a public function's default backend away from `"mdtraj"`.** Add performance notes in the docstring pointing users to `backend="numba"` or a GPU backend when they need speed.
+**Never silently change a public function's default backend away from its current value** (`"mdtraj"`, or `"numpy"` for DCCM). Add performance notes in the docstring pointing users to `backend="numba"` or a GPU backend when they need speed.
+
+## Float Dtype Rule
+
+mdpp uses **float32 by default**, matching mdtraj's coordinate precision. Never force float64 for "numerical stability". Every `compute_*` function takes `dtype: DtypeArg = None` as the final keyword argument, calls `resolved = resolve_dtype(dtype)` at the top, and casts outputs with `astype(resolved, copy=False)` (zero-copy when the backend's native dtype already matches). Import `DtypeArg` from `mdpp._types`; never inline the union type.
 
 ## Backend Registry Typing Rule
 
@@ -62,11 +71,13 @@ class RMSDMatrixBackendFn(Protocol):
         self,
         traj: md.Trajectory,
         atom_indices: NDArray[np.int_],
-    ) -> NDArray[np.float64]: ...
+    ) -> NDArray[np.floating]: ...
 
 rmsd_matrix_backends: BackendRegistry[RMSDMatrixBackendFn] = BackendRegistry(default="mdtraj")
 ```
 
+Protocols return `NDArray[np.floating]` (not `NDArray[np.float64]`) so each backend can return its native dtype -- float32 for mdtraj / torch / jax / cupy, float64 for numba. The public `compute_*` wrapper casts with `astype(resolved, copy=False)` so when the backend's native dtype already matches the resolved dtype, no second buffer is allocated. Never add an unconditional `.astype(np.float64)` at a backend boundary -- on an N^2 matrix at N=120k that is 115 GB of pointless copying.
+
 **Never** declare a bare `BackendRegistry` without a type parameter -- `registry.get(backend)` would return an unbound `F`, and callers like `compute_fn = rmsd_matrix_backends.get(backend)` would lose type information. The Protocol lives next to the backends it describes (not in the shared `_registry.py`) so the registry module stays decoupled.
 
 **Uniform signature rule**: every backend registered in the same registry MUST accept the exact Protocol call signature. If one backend needs an extra keyword argument (e.g. `periodic` on mdtraj), every other backend MUST also accept that keyword, silently ignoring it if unused (`# noqa: ARG001` + docstring note). This preserves type inference at call sites and keeps dispatchers branch-free.

.cursor/rules/python-analysis.mdc

@@ -1,5 +1,5 @@
 ---
-description: Patterns for analysis modules — dataclass results, compute functions
+description: Patterns for analysis modules — dataclass results, compute functions, dtype handling
 globs: src/mdpp/analysis/*.py
 alwaysApply: false
 ---
@@ -12,40 +12,67 @@ alwaysApply: false
 @dataclass(frozen=True, slots=True)
 class ExampleResult:
     """One-line summary."""
-    time_ps: NDArray[np.float64]
-    values_nm: NDArray[np.float64]
+    time_ps: NDArray[np.floating]
+    values_nm: NDArray[np.floating]
     atom_indices: NDArray[np.int_]
 
     @property
-    def time_ns(self) -> NDArray[np.float64]:
+    def time_ns(self) -> NDArray[np.floating]:
+        """Return frame times in nanoseconds."""
         return self.time_ps / 1000.0
 
     @property
-    def values_angstrom(self) -> NDArray[np.float64]:
+    def values_angstrom(self) -> NDArray[np.floating]:
+        """Return values in Angstrom."""
         return self.values_nm * 10.0
 ```
 
+Use `NDArray[np.floating]` (not `np.float64`) in result fields so the dataclass reflects the actual stored dtype, which defaults to float32.
+
 ## Compute Functions
 
 ```python
+from mdpp._dtype import resolve_dtype
+from mdpp._types import DtypeArg
+from mdpp.core.trajectory import select_atom_indices, trajectory_time_ps
+
 def compute_example(
     traj: md.Trajectory,
     *,
     atom_selection: str = "backbone",
     timestep_ps: float | None = None,
+    dtype: DtypeArg = None,
 ) -> ExampleResult:
     """Compute X from a trajectory.
 
     Args:
         traj: Input trajectory.
         atom_selection: MDTraj selection string.
         timestep_ps: Optional timestep override in ps.
+        dtype: Output float dtype. If ``None``, uses the package default
+            (see :func:`mdpp.set_default_dtype`).
 
     Returns:
         ExampleResult with per-frame values.
     """
+    resolved = resolve_dtype(dtype)
+    atom_indices = select_atom_indices(traj.topology, atom_selection)
+    # ... compute values_nm here ...
+    return ExampleResult(
+        time_ps=trajectory_time_ps(traj, timestep_ps=timestep_ps, dtype=resolved),
+        values_nm=np.asarray(values_nm, dtype=resolved),
+        atom_indices=atom_indices,
+    )
 ```
 
+- First positional arg is `traj: md.Trajectory` (or a feature matrix).
+- All remaining args are keyword-only.
+- `dtype: DtypeArg = None` is the **last** keyword argument.
+- Call `resolve_dtype(dtype)` once at the top, then thread `resolved` through every cast.
 - Import trajectory helpers from `mdpp.core.trajectory`, never from `mdpp.analysis.trajectory`.
 - Validate inputs early (raise `ValueError` with descriptive messages).
-- Cast outputs to explicit dtypes: `np.asarray(..., dtype=np.float64)`.
+- Cast with `np.asarray(value, dtype=resolved)` or `.astype(resolved, copy=False)` -- both are no-copy when the source dtype already matches.
+
+## Multi-Backend Compute Functions
+
+If the function dispatches through a `BackendRegistry`, add `backend: <Kind>Backend = "mdtraj"` (or `"numpy"` if mdtraj has no kernel) and resolve via `compute_fn = <kind>_backends.get(backend)`. Every backend must accept the same call signature; extra kwargs on one backend (e.g. `periodic` on mdtraj) must be silently accepted by all others.

.cursor/rules/shell-scripts.mdc

@@ -6,14 +6,32 @@ alwaysApply: false
 
 # Shell Script Conventions
 
-- All scripts start with `#!/bin/bash` and `set -euo pipefail`.
+- Shebang: **always `#!/usr/bin/env bash`** (never `#!/bin/bash`).
+- Executable bit: every `.sh` and `.sbatch` file must be `chmod +x`.
+- First lines after the shebang: `set -euo pipefail`.
 - Indent with 4 spaces (enforced by shfmt via pre-commit).
 - Pass shellcheck at error severity.
+- ASCII only -- no Unicode arrows, ligatures, emoji, or non-ASCII punctuation.
 - Organize under `scripts/<engine>/<category>/`:
-  - `scripts/gromacs/mdrun/` — production run scripts and MDP files
-  - `scripts/gromacs/analysis/` — gmx analysis commands
-  - `scripts/amber/` — AMBER/AmberTools workflows
-  - `scripts/openfe/` — OpenFE RBFE workflows (quickrun.sh, quickrun.sbatch, runtime/check_status.sh)
-- SLURM batch scripts (`.sbatch`) live alongside `.sh` scripts in the same category directory.
-- OpenFE scripts require >= 1.10.0 for `--resume` checkpoint support.
-- `quickrun.sbatch` starts CUDA MPS for Sherlock's `Exclusive_Process` GPU mode — do not remove the MPS setup block.
+  - `scripts/gromacs/mdrun/` -- production run scripts
+  - `scripts/gromacs/mdps/<ff>/` -- force-field-specific MDP templates
+  - `scripts/gromacs/analysis/` -- gmx analysis commands
+  - `scripts/gromacs/compilation/` -- GROMACS build helpers
+  - `scripts/gromacs/runtime/` -- status / restart / extend / export
+  - `scripts/openfe/quickrun/` -- RBFE SLURM submission
+  - `scripts/openfe/runtime/` -- status + monitor scripts
+- SLURM batch scripts (`.sbatch`) live alongside their `.sh` counterparts in the same category directory.
+- OpenFE scripts require **OpenFE >= 1.10.0** for `--resume` checkpoint support.
+- `quickrun.sbatch` starts CUDA MPS for Sherlock's `Exclusive_Process` GPU mode -- do not remove the MPS setup block.
+
+## Argument Parsing
+
+Scripts that accept flags/options must:
+
+- Use manual `while [[ $# -gt 0 ]]; do case "$1" in ...` loops (not `getopts`) to support both short and long flags.
+- Define a `usage()` function that documents every argument.
+- Always support `-h` / `--help`.
+- Provide short and long forms for every flag (e.g. `-j` / `--jobs`, `-n` / `--dry-run`).
+- Validate required arguments and print clear error messages on invalid input.
+
+Scripts that only accept simple positional arguments (e.g. a single `$1`) do not need this treatment.

AGENTS.md

@@ -70,7 +70,7 @@ Source is under `src/mdpp/` using the src-layout convention:
 | `core/` | Trajectory I/O, file parsers | `load_trajectory`, `load_trajectories`, `read_xvg`, `read_edr` |
 | `constants.py` | Physical constants | `GAS_CONSTANT_KJ_MOL_K`, `DEFAULT_TEMPERATURE_K` |
 | `analysis/` | Compute functions | `compute_*(traj, *, ...) -> FrozenDataclass` |
-| `analysis/_backends/` | Private backend subpackage | `BackendRegistry[F]`, `require_torch/jax/cupy`, `DistanceBackend`/`RMSDBackend` Literals |
+| `analysis/_backends/` | Private backend subpackage | `BackendRegistry[F]`, `require_torch/jax/cupy`, `DistanceBackend`/`RMSDBackend`/`DCCMBackend` Literals, `clean_torch_cache`/`clean_cupy_cache` decorators |
 | `chem/` | Small-molecule cheminformatics | `MolSupplier`, `calc_descs`, `gen_fp`, `calc_sim`, `is_pains` |
 | `plots/` | Visualization (2D, 3D, molecules) | `plot_*(result, *, ax=None) -> Axes`, `draw_mol`, `view_mol_3d` |
 | `prep/` | System preparation | `fix_pdb`, `strip_solvent`, `run_propka`, ligand tools |
@@ -119,6 +119,29 @@ Tests live in `tests/analysis/`, `tests/plots/`, and `tests/chem/`, mirroring th
 - Shell scripts (not packaged): `scripts/<engine>/<category>/<script>.sh`
 - SLURM scripts: `scripts/<engine>/<category>/<script>.sbatch`
 
+## Clustering API
+
+`mdpp.analysis.clustering` exposes seven sklearn-style callable classes:
+
+| Class | Input | Backend / notes |
+|---|---|---|
+| `Gromos` | RMSD matrix | Numba JIT (greedy largest-first, Daura 1999) |
+| `Hierarchical` | RMSD matrix | scipy linkage + fcluster |
+| `DBSCAN` | RMSD matrix | Numba JIT (default) or sklearn `metric="precomputed"` |
+| `HDBSCAN` | RMSD matrix | sklearn `metric="precomputed"` |
+| `KMeans` | Feature matrix | scikit-learn |
+| `MiniBatchKMeans` | Feature matrix | scikit-learn |
+| `RegularSpace` | Feature matrix | deeptime |
+
+Each class is `@dataclass(frozen=True, slots=True)` with parameters at construction and a `__call__(data) -> ClusteringResult | FeatureClusteringResult` invocation.
+
+```python
+result = Gromos(cutoff_nm=0.15)(rmsd_matrix.rmsd_matrix_nm)
+result = KMeans(n_clusters=10)(pca.projections)
+```
+
+Do **not** add the old function-form wrappers (`compute_gromos_clusters`, etc.) -- they were removed and there is no backward-compat shim.
+
 ## Adding a New Analysis
 
 1. Create/extend a file in `src/mdpp/analysis/`.
@@ -130,15 +153,15 @@ Tests live in `tests/analysis/`, `tests/plots/`, and `tests/chem/`, mirroring th
 
 ## Compute Backend Conventions
 
-**Default backend rule**: every public compute function that accepts a `backend=` argument MUST default to `"mdtraj"`. Other backends (`numba`, `torch`, `jax`, `cupy`) are performance options that callers must opt into explicitly.
+**Default backend rule**: every public compute function that accepts a `backend=` argument MUST default to `"mdtraj"` **when mdtraj provides a native kernel for that computation**. Other backends (`numba`, `torch`, `jax`, `cupy`) are performance options that callers must opt into explicitly. The only current exception is `compute_dccm`, which defaults to `"numpy"` because mdtraj has no native covariance kernel -- `numpy`'s BLAS GEMM is multi-threaded and works without any optional dependency.
 
 Reasons:
 
 - Only `mdtraj` supports periodic boundary conditions -- defaulting to anything else would silently drop PBC for users who don't read the backend parameter.
-- All analysis functions sharing the same default keeps API behavior consistent across `compute_distances`, `compute_rmsd_matrix`, `featurize_ca_distances`, etc.
+- All PBC-relevant analysis functions sharing the same default keeps API behavior consistent across `compute_distances`, `compute_rmsd_matrix`, `featurize_ca_distances`, etc.
 - The optional GPU backends (`[gpu]` extra) must never be required for the common path.
 
-When reviewing or writing code, never change a public function's default backend away from `"mdtraj"`.
+When reviewing or writing code, never silently change a public function's default backend away from its current value (`"mdtraj"`, or `"numpy"` for DCCM).
 
 **Uniform signature rule**: every backend registered in a given `BackendRegistry` MUST accept the exact same call signature as the Protocol type parameter on that registry. If one backend needs an extra keyword argument (e.g. `periodic` on mdtraj), every other backend in the same registry MUST also accept that keyword, silently ignoring it if unused (mark `# noqa: ARG001` and document as "accepted for Protocol uniformity, ignored"). This keeps the dispatcher free of per-backend branching and preserves type inference for callers.
 
@@ -182,16 +205,16 @@ For existing multi-backend functions (e.g. `compute_rmsd_matrix`, pairwise dista
 1. Decorate torch/cupy GPU kernels with `@clean_torch_cache` / `@clean_cupy_cache` from `_backends/_imports.py` so pooled memory is released in a `finally` block after the kernel runs. Do **not** apply any cleanup decorator to JAX kernels -- `jax.clear_caches()` trashes JIT compilation caches and forces slow recompiles.
 1. If you introduce a new keyword argument, also retrofit every existing backend in the same registry to accept it (silently ignoring when unused, marked `# noqa: ARG001`).
 1. Register in the module's `BackendRegistry` at the bottom of the file.
-1. Add the backend name to the corresponding `Literal` alias (`DistanceBackend` / `RMSDBackend`) in `_backends/_registry.py`.
+1. Add the backend name to the corresponding `Literal` alias (`DistanceBackend` / `RMSDBackend` / `DCCMBackend`) in `_backends/_registry.py`.
 1. Add agreement tests in `tests/analysis/test_<kind>.py` guarded by the relevant `requires_*` skip marker and `@pytest.mark.gpu` (if GPU-only).
-1. **Do not change the public function's default backend** -- keep it at `"mdtraj"`.
+1. **Do not change the public function's default backend** -- keep `compute_distances` / `compute_rmsd_matrix` / `featurize_ca_distances` defaulting to `"mdtraj"` and `compute_dccm` defaulting to `"numpy"`.
 
 ## Adding a New Backend Registry
 
 To introduce a registry for a new multi-backend compute function:
 
 1. Create `src/mdpp/analysis/_backends/_<kind>.py` with a `Protocol` class defining the shared call signature.
-1. Declare the registry as `<kind>_backends: BackendRegistry[<Kind>BackendFn] = BackendRegistry(default="mdtraj")` -- always parameterise with the Protocol so callers get typed `compute_fn` from `registry.get()`.
+1. Declare the registry as `<kind>_backends: BackendRegistry[<Kind>BackendFn] = BackendRegistry(default="mdtraj")` (or another sensible no-optional-dep default if mdtraj has no kernel for that computation -- e.g. `_dccm.py` uses `default="numpy"`). Always parameterise with the Protocol so callers get typed `compute_fn` from `registry.get()`.
 1. Add a `Literal` alias to `_backends/_registry.py` (`type <Kind>Backend = Literal["mdtraj", "numba", ...]`) and re-export it from `_backends/__init__.py`.
 1. The public wrapper in `src/mdpp/analysis/<kind>.py` imports the registry and delegates via `compute_fn = <kind>_backends.get(backend)`, letting mypy infer the Protocol type at the call site.