atst-tools 2.3.0__tar.gz → 2.3.2__tar.gz

atst_tools-2.3.2/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: atst-tools
+Version: 2.3.2
+Summary: Advanced ASE Transition State Tools for ABACUS and Deep-Potential
+License-Expression: LGPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: COPYING
+Requires-Dist: abacuslite<2,>=1.2.1
+Requires-Dist: ase>=3.28.0
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.13
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: ruamel.yaml<0.20,>=0.18
+Requires-Dist: seekpath<3,>=2.2
+Requires-Dist: sella<3,>=2.5
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.9; extra == "plot"
+Provides-Extra: dp
+Requires-Dist: deepmd-kit>=3.1.3; extra == "dp"
+Provides-Extra: parallel
+Requires-Dist: mpi4py>=4.1.2; extra == "parallel"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8.4; extra == "test"
+Requires-Dist: tomli<3,>=2.0; extra == "test"
+Provides-Extra: release
+Requires-Dist: build<2,>=1.5; extra == "release"
+Requires-Dist: twine<7,>=6.2; extra == "release"
+Requires-Dist: tomli<3,>=2.0; extra == "release"
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8.4; extra == "dev"
+Requires-Dist: build<2,>=1.5; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+Requires-Dist: tomli<3,>=2.0; extra == "dev"
+Dynamic: license-file
+
+# ATST-Tools
+
+[![Version](https://img.shields.io/badge/version-2.3.2-blue)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-LGPL--v3-blue)](#license)
+
+ATST-Tools is an **ASE transition-state workflow toolkit** for ABACUS and
+DeePMD-kit. Run calculations from YAML with the `atst` command, or use the
+[Python API](docs/user/PYTHON_API_REFERENCE.md) to integrate the same workflows
+into another program.
+
+```bash
+atst run config.yaml
+```
+
+Chinese guide: [中文 · GitHub](https://github.com/QuantumMisaka/atst-tools/blob/main/docs/user/USER_GUIDE_CN.md)
+· [Gitee](https://gitee.com/jamesmisaka/atst-tools/blob/main/docs/user/USER_GUIDE_CN.md).
+Examples: [GitHub](https://github.com/QuantumMisaka/atst-tools/tree/main/examples)
+· [Gitee](https://gitee.com/jamesmisaka/atst-tools/tree/main/examples).
+
+## What You Can Run
+
+| Workflow | `calculation.type` |
+| :--- | :--- |
+| NEB / DyNEB and adaptive-image NEB | `neb`, `autoneb` |
+| Dimer, Sella and CCQN saddle searches | `dimer`, `sella`, `ccqn` |
+| Double-ended to single-ended TS search | `d2s` |
+| Structure relaxation | `relax` |
+| Vibrations and thermochemistry | `vibration` |
+| Intrinsic reaction coordinates | `irc` |
+| ASE-driven or ABACUS-native molecular dynamics | `md` |
+| Experimental Direct MaxFlux path search | `dmf` |
+| Experimental ABACUS constant-potential single points and serial scans | `constant_potential` |
+
+Experimental constant-potential fixed-cell relaxation, NEB and ASE-driven MD
+use the explicit `compensated_gate` boundary. See the
+[configuration reference](docs/user/CONFIG_REFERENCE.md#211-constant-potential-evaluation-development-candidate)
+for setup and supported boundaries.
+
+Local commands prepare paths and ABACUS inputs, inspect trajectories, and
+summarize existing results. See the [CLI reference](docs/user/CLI_REFERENCE.md).
+A transition-state candidate can be screened with `atst vibration validate`
+using saved vibration results; workflow completion alone does not establish a
+validated TS. Current support and experimental limits are summarized in the
+[feature matrix](docs/reports/FEATURE_STATUS_MATRIX.md).
+
+## Installation
+
+Requires Python 3.10 or later:
+
+```bash
+pip install atst-tools
+atst --version
+```
+
+| Use | Installation |
+| :--- | :--- |
+| Serial workflows, including serial NEB/AutoNEB | `pip install atst-tools` |
+| DeePMD-kit calculator | `pip install "atst-tools[dp]"` |
+| Image-parallel NEB/AutoNEB | `pip install "atst-tools[parallel]"` |
+
+The default installation includes `abacuslite>=1.2.1,<2` and Sella; it does not
+install `mpi4py`. ABACUS calculations also need an ABACUS executable and the
+pseudopotential/orbital files referenced by the configuration. DP calculations
+need a compatible model. Image-parallel runs require a matching MPI runtime;
+DMF additionally requires `cyipopt` and IPOPT. See the
+[MPI setup guide](docs/user/ABACUSLITE_WRAPPER_GUIDE.md#neb-image-level-mpi) for
+image-parallel setup and the [examples guide](examples/README.md#usage) for
+backend inputs.
+
+## Quick Start
+
+Obtain examples at the tag matching your installed version (shown for 2.3.2):
+
+```bash
+git clone --branch v2.3.2 https://github.com/QuantumMisaka/atst-tools.git
+cd atst-tools
+```
+
+First try a local path-preparation command; it needs no ABACUS, DP model or GPU:
+
+```bash
+cd examples/09_lightweight_cli
+atst neb make inputs/init.xyz inputs/final.xyz 3 -o first_chain.traj --method linear
+atst neb summary inputs/neb_result.extxyz --n-max 1 --tail 5
+cd ../..
+```
+
+`first_chain.traj` contains five initial-guess frames. To inspect a calculation
+configuration, enter its example directory so relative input paths resolve:
+
+```bash
+cd examples/06_relax_H2-Au
+atst config validate config.yaml --print-normalized
+atst run --dry-run config.yaml
+# After configuring the ABACUS runtime and compute resources:
+atst run config.yaml
+```
+
+This example uses four ABACUS MPI ranks, the GPU `cusolver` solver and a
+one-step optimization limit. Validation and dry-run do not launch ABACUS;
+check the resulting convergence status separately. Follow the
+[examples guide](examples/README.md#usage) to inspect results and choose other
+methods or DP variants. A complete walkthrough is also available in the
+[Chinese guide](docs/user/USER_GUIDE_CN.md#3-10-分钟快速上手).
+
+## Documentation
+
+| Task | Reference |
+| :--- | :--- |
+| Configure a calculation | [Configuration reference](docs/user/CONFIG_REFERENCE.md) · [All YAML fields](docs/user/YAML_INPUT_VARIABLES.md) |
+| Use CLI commands | [CLI reference](docs/user/CLI_REFERENCE.md) |
+| Configure ABACUS input/output and parallelism | [ABACUS wrapper guide](docs/user/ABACUSLITE_WRAPPER_GUIDE.md) |
+| Embed workflows or use the JSON process runner | [Python API](docs/user/PYTHON_API_REFERENCE.md) |
+| Check support and releases | [Feature matrix](docs/reports/FEATURE_STATUS_MATRIX.md) · [2.3.2 release notes](docs/releases/RELEASE_NOTES_2.3.2.md) |
+| Contribute | [Developer handover](docs/developer/HANDOVER.md) · [Source architecture](src/atst_tools/README.md) |
+
+The primary documentation is in English, with a [Chinese user guide](docs/user/USER_GUIDE_CN.md).
+The [documentation index](docs/index.md) organizes user, developer and project
+status material. GitHub is the development source; Gitee is a manually updated
+mirror. PyPI distributes the Python package; obtain examples from the repository.
+
+## References
+
+If you publish work that uses the transition-state workflows in ATST-Tools,
+please cite the underlying methods alongside ATST-Tools itself:
+
+- ATST-Tools and the double-to-single (D2S) transition-state workflow:
+  Liu, Z.-Q.; Deng, Z.; Zhao, H.; Wang, H.; Chen, M.; Jiang, H.
+  *FT²DP: Large Atomic Model Fine-Tuned Machine Learning Potential for
+  Accelerating Atomistic Simulation of Iron-Based Fischer–Tropsch Synthesis.*
+  J. Mater. Inform. **5** (2), 27 (2025).
+  <https://doi.org/10.20517/jmi.2024.105>
+- Sella saddle-point search:
+  Hermes, E. D.; Sargsyan, K.; Najm, H. N.; Zádor, J.
+  *Sella, an Open-Source Automation-Friendly Molecular Saddle Point Optimizer.*
+  J. Chem. Theory Comput. **18** (11), 6974-6988 (2022).
+  <https://doi.org/10.1021/acs.jctc.2c00395>
+- CCQN (cone-shaped constrained quasi-Newton) transition-state optimization:
+  Wu, Y.; Wang, H. *Cone-Shaped Constrained Quasi-Newton Method: Efficient
+  and Robust Single-Ended Transition State Optimization Algorithm.*
+  J. Chem. Theory Comput. **21** (18), 9054-9065 (2025).
+  <https://doi.org/10.1021/acs.jctc.5c01015>
+
+## License
+
+LGPL-v3 License.

atst_tools-2.3.2/README.md

@@ -0,0 +1,147 @@
+# ATST-Tools
+
+[![Version](https://img.shields.io/badge/version-2.3.2-blue)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-LGPL--v3-blue)](#license)
+
+ATST-Tools is an **ASE transition-state workflow toolkit** for ABACUS and
+DeePMD-kit. Run calculations from YAML with the `atst` command, or use the
+[Python API](docs/user/PYTHON_API_REFERENCE.md) to integrate the same workflows
+into another program.
+
+```bash
+atst run config.yaml
+```
+
+Chinese guide: [中文 · GitHub](https://github.com/QuantumMisaka/atst-tools/blob/main/docs/user/USER_GUIDE_CN.md)
+· [Gitee](https://gitee.com/jamesmisaka/atst-tools/blob/main/docs/user/USER_GUIDE_CN.md).
+Examples: [GitHub](https://github.com/QuantumMisaka/atst-tools/tree/main/examples)
+· [Gitee](https://gitee.com/jamesmisaka/atst-tools/tree/main/examples).
+
+## What You Can Run
+
+| Workflow | `calculation.type` |
+| :--- | :--- |
+| NEB / DyNEB and adaptive-image NEB | `neb`, `autoneb` |
+| Dimer, Sella and CCQN saddle searches | `dimer`, `sella`, `ccqn` |
+| Double-ended to single-ended TS search | `d2s` |
+| Structure relaxation | `relax` |
+| Vibrations and thermochemistry | `vibration` |
+| Intrinsic reaction coordinates | `irc` |
+| ASE-driven or ABACUS-native molecular dynamics | `md` |
+| Experimental Direct MaxFlux path search | `dmf` |
+| Experimental ABACUS constant-potential single points and serial scans | `constant_potential` |
+
+Experimental constant-potential fixed-cell relaxation, NEB and ASE-driven MD
+use the explicit `compensated_gate` boundary. See the
+[configuration reference](docs/user/CONFIG_REFERENCE.md#211-constant-potential-evaluation-development-candidate)
+for setup and supported boundaries.
+
+Local commands prepare paths and ABACUS inputs, inspect trajectories, and
+summarize existing results. See the [CLI reference](docs/user/CLI_REFERENCE.md).
+A transition-state candidate can be screened with `atst vibration validate`
+using saved vibration results; workflow completion alone does not establish a
+validated TS. Current support and experimental limits are summarized in the
+[feature matrix](docs/reports/FEATURE_STATUS_MATRIX.md).
+
+## Installation
+
+Requires Python 3.10 or later:
+
+```bash
+pip install atst-tools
+atst --version
+```
+
+| Use | Installation |
+| :--- | :--- |
+| Serial workflows, including serial NEB/AutoNEB | `pip install atst-tools` |
+| DeePMD-kit calculator | `pip install "atst-tools[dp]"` |
+| Image-parallel NEB/AutoNEB | `pip install "atst-tools[parallel]"` |
+
+The default installation includes `abacuslite>=1.2.1,<2` and Sella; it does not
+install `mpi4py`. ABACUS calculations also need an ABACUS executable and the
+pseudopotential/orbital files referenced by the configuration. DP calculations
+need a compatible model. Image-parallel runs require a matching MPI runtime;
+DMF additionally requires `cyipopt` and IPOPT. See the
+[MPI setup guide](docs/user/ABACUSLITE_WRAPPER_GUIDE.md#neb-image-level-mpi) for
+image-parallel setup and the [examples guide](examples/README.md#usage) for
+backend inputs.
+
+## Quick Start
+
+Obtain examples at the tag matching your installed version (shown for 2.3.2):
+
+```bash
+git clone --branch v2.3.2 https://github.com/QuantumMisaka/atst-tools.git
+cd atst-tools
+```
+
+First try a local path-preparation command; it needs no ABACUS, DP model or GPU:
+
+```bash
+cd examples/09_lightweight_cli
+atst neb make inputs/init.xyz inputs/final.xyz 3 -o first_chain.traj --method linear
+atst neb summary inputs/neb_result.extxyz --n-max 1 --tail 5
+cd ../..
+```
+
+`first_chain.traj` contains five initial-guess frames. To inspect a calculation
+configuration, enter its example directory so relative input paths resolve:
+
+```bash
+cd examples/06_relax_H2-Au
+atst config validate config.yaml --print-normalized
+atst run --dry-run config.yaml
+# After configuring the ABACUS runtime and compute resources:
+atst run config.yaml
+```
+
+This example uses four ABACUS MPI ranks, the GPU `cusolver` solver and a
+one-step optimization limit. Validation and dry-run do not launch ABACUS;
+check the resulting convergence status separately. Follow the
+[examples guide](examples/README.md#usage) to inspect results and choose other
+methods or DP variants. A complete walkthrough is also available in the
+[Chinese guide](docs/user/USER_GUIDE_CN.md#3-10-分钟快速上手).
+
+## Documentation
+
+| Task | Reference |
+| :--- | :--- |
+| Configure a calculation | [Configuration reference](docs/user/CONFIG_REFERENCE.md) · [All YAML fields](docs/user/YAML_INPUT_VARIABLES.md) |
+| Use CLI commands | [CLI reference](docs/user/CLI_REFERENCE.md) |
+| Configure ABACUS input/output and parallelism | [ABACUS wrapper guide](docs/user/ABACUSLITE_WRAPPER_GUIDE.md) |
+| Embed workflows or use the JSON process runner | [Python API](docs/user/PYTHON_API_REFERENCE.md) |
+| Check support and releases | [Feature matrix](docs/reports/FEATURE_STATUS_MATRIX.md) · [2.3.2 release notes](docs/releases/RELEASE_NOTES_2.3.2.md) |
+| Contribute | [Developer handover](docs/developer/HANDOVER.md) · [Source architecture](src/atst_tools/README.md) |
+
+The primary documentation is in English, with a [Chinese user guide](docs/user/USER_GUIDE_CN.md).
+The [documentation index](docs/index.md) organizes user, developer and project
+status material. GitHub is the development source; Gitee is a manually updated
+mirror. PyPI distributes the Python package; obtain examples from the repository.
+
+## References
+
+If you publish work that uses the transition-state workflows in ATST-Tools,
+please cite the underlying methods alongside ATST-Tools itself:
+
+- ATST-Tools and the double-to-single (D2S) transition-state workflow:
+  Liu, Z.-Q.; Deng, Z.; Zhao, H.; Wang, H.; Chen, M.; Jiang, H.
+  *FT²DP: Large Atomic Model Fine-Tuned Machine Learning Potential for
+  Accelerating Atomistic Simulation of Iron-Based Fischer–Tropsch Synthesis.*
+  J. Mater. Inform. **5** (2), 27 (2025).
+  <https://doi.org/10.20517/jmi.2024.105>
+- Sella saddle-point search:
+  Hermes, E. D.; Sargsyan, K.; Najm, H. N.; Zádor, J.
+  *Sella, an Open-Source Automation-Friendly Molecular Saddle Point Optimizer.*
+  J. Chem. Theory Comput. **18** (11), 6974-6988 (2022).
+  <https://doi.org/10.1021/acs.jctc.2c00395>
+- CCQN (cone-shaped constrained quasi-Newton) transition-state optimization:
+  Wu, Y.; Wang, H. *Cone-Shaped Constrained Quasi-Newton Method: Efficient
+  and Robust Single-Ended Transition State Optimization Algorithm.*
+  J. Chem. Theory Comput. **21** (18), 9054-9065 (2025).
+  <https://doi.org/10.1021/acs.jctc.5c01015>
+
+## License
+
+LGPL-v3 License.

{atst_tools-2.3.0 → atst_tools-2.3.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atst-tools"
-version = "2.3.0"
+version = "2.3.2"
 description = "Advanced ASE Transition State Tools for ABACUS and Deep-Potential"
 readme = "README.md"
 license = "LGPL-3.0-or-later"
 requires-python = ">=3.10"
 dependencies = [
-    "abacuslite>=1.2.0,<2",
+    "abacuslite>=1.2.1,<2",
     "ase>=3.28.0",
     "numpy>=1.26,<3",
     "scipy>=1.13,<2",

{atst_tools-2.3.0 → atst_tools-2.3.2}/src/atst_tools/calculators/abacuslite_backend.py

@@ -17,7 +17,7 @@ BackendSource = Literal["external"]
 def _load_abacuslite_backend():
     if find_spec("abacuslite") is None:
         raise ModuleNotFoundError(
-            "abacuslite is required by ATST-Tools; install abacuslite>=1.2.0,<2",
+            "abacuslite is required by ATST-Tools; install abacuslite>=1.2.1,<2",
             name="abacuslite",
         )
     from abacuslite import Abacus, AbacusProfile

{atst_tools-2.3.0 → atst_tools-2.3.2}/src/atst_tools/calculators/constant_potential.py

@@ -1074,6 +1074,14 @@ class ConstantPotentialCalculator(Calculator):
             identity["fixed_hamiltonian"] = copy.deepcopy(self._fixed_hamiltonian_identity)
         return identity
 
+    def stage_initial_electrons(self, nelec: float) -> None:
+        """Stage a validated next-solve guess without clearing current results.
+
+        This is for sequential CP MD evaluations. The electron count is only
+        an initial guess; the next geometry still runs the complete CP loop.
+        """
+        self.initial_electrons = self._validate_candidate(_finite(nelec, "initial_electrons"))
+
     def set(self, **kwargs: Any) -> dict[str, Any]:
         """Update CP parameters and invalidate cached ASE results."""
         changed = super().set(**kwargs)
@@ -1254,8 +1262,12 @@ class ConstantPotentialCalculator(Calculator):
             # consumes the published CP result.  Suppress them on this private
             # probe so Hookean/constraint energy and force contributions are
             # not applied a second time inside the electronic loop.
-            energy = float(probe.get_potential_energy(force_consistent=False, apply_constraint=False))
-            free_energy = float(probe.get_potential_energy(force_consistent=True, apply_constraint=False))
+            kohn_sham_energy = float(
+                probe.get_potential_energy(force_consistent=False, apply_constraint=False)
+            )
+            force_consistent_energy = float(
+                probe.get_potential_energy(force_consistent=True, apply_constraint=False)
+            )
             forces = np.asarray(probe.get_forces(apply_constraint=False), dtype=float)
         except ConstantPotentialError:
             raise
@@ -1274,12 +1286,17 @@ class ConstantPotentialCalculator(Calculator):
             raise ConstantPotentialEvaluationError(
                 f"fixed-electron evaluation at nelec={nelec} returned invalid forces"
             )
+        # Preserve the backend's ASE energy keys for the compensated boundary.
+        # The reference-only FCP convention uses the explicit no-entropy
+        # energy, without changing the force-consistent free energy.
         raw_energy = _first_finite(raw_results, ("energy",))
         raw_free_energy = _first_finite(raw_results, ("free_energy",))
         if raw_energy is None:
-            raw_energy = _finite(energy, "raw energy")
+            raw_energy = _finite(kohn_sham_energy, "raw energy")
         if raw_free_energy is None:
-            raw_free_energy = _finite(free_energy, "raw free energy")
+            raw_free_energy = _finite(force_consistent_energy, "raw free energy")
+        if self.energy_boundary == "reference_fcp" and "energy_without_entropy" in raw_results:
+            raw_energy = _finite(raw_results["energy_without_entropy"], "energy without entropy")
         efermi = _backend_efermi(inner, raw_results)
         if efermi is None:
             raise ConstantPotentialEvaluationError(
@@ -1534,6 +1551,7 @@ class ConstantPotentialCalculator(Calculator):
             "scf_converged": True,
             "cp_converged": True,
             "cp_iterations": int(final["evaluation_index"]),
+            "capacitance_e_per_V": float(capacitance),
             "cp_history": self._jsonable(self.evaluation_history),
             "cp_identity": self.constant_potential_identity,
         }

{atst_tools-2.3.0 → atst_tools-2.3.2}/src/atst_tools/calculators/factory.py

@@ -22,6 +22,10 @@ from atst_tools.calculators.constant_potential import (
 from atst_tools.calculators.dp import DeepPotentialFactory
 from atst_tools.runtime import counters as runtime_counters
 from atst_tools.runtime import launch as runtime_launch
+from atst_tools.utils.config_schema import (
+    ConstantPotentialConfig,
+    validate_constant_potential_md_scope,
+)
 from atst_tools.utils.mpi import mpi_launcher_detected
 
 
@@ -228,14 +232,18 @@ def _constant_potential_calculator(
     config: Dict[str, Any], cp_config: Dict[str, Any], kwargs: Dict[str, Any]
 ) -> ConstantPotentialCalculator:
     """Build one CP decorator around fresh, unwrapped ABACUS calculators."""
-    supported_workflows = {"constant_potential", "relax", "neb"}
-    workflow = config.get("calculation", {}).get("type") if isinstance(config.get("calculation"), dict) else None
+    supported_workflows = {"constant_potential", "relax", "neb", "md"}
+    calculation = config.get("calculation", {})
+    workflow = calculation.get("type") if isinstance(calculation, dict) else None
     if workflow is not None and workflow not in supported_workflows:
         raise ValueError(
             "calculator.constant_potential is supported only for calculation.type in "
             f"{sorted(supported_workflows)}; got {workflow!r}"
         )
     options = dict(cp_config)
+    if workflow == "md":
+        validate_constant_potential_md_scope(calculation, options)
+        options = ConstantPotentialConfig.model_validate(options).model_dump(mode="python")
     energy_boundary = str(options.get("energy_boundary", "reference_fcp"))
     if energy_boundary not in {"reference_fcp", "compensated_gate"}:
         raise ValueError("calculator.constant_potential.energy_boundary is unsupported")

{atst_tools-2.3.0 → atst_tools-2.3.2}/src/atst_tools/utils/config_schema.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import math
 from types import UnionType
-from typing import Annotated, Any, Dict, Literal, Union, get_args, get_origin
+from typing import Annotated, Any, Dict, Literal, Mapping, Union, get_args, get_origin
 
 from pydantic import (
     AliasChoices,
@@ -144,7 +144,7 @@ class ConstantPotentialConfig(StrictConfig):
     target_mu_ev: float | None = Field(
         default=None,
         allow_inf_nan=False,
-        description="Target conjugate electron chemical potential in eV for compensated_gate.",
+        description="Scalar target chemical potential in eV for compensated_gate; required for CP MD.",
     )
     target_mu_values_ev: list[float] | None = Field(
         default=None,
@@ -868,8 +868,12 @@ class MDCalculation(StrictConfig):
     )
     init_structure: str = Field(description="Initial structure file.")
     steps: int = Field(default=100, gt=0, description="Number of MD steps.")
-    ensemble: Literal["nve", "nvt", "npt"] = Field(default="nvt", description="ASE MD ensemble.")
-    algorithm: str = Field(default="bussi", description="ASE MD algorithm.")
+    ensemble: Literal["nve", "nvt", "npt"] = Field(
+        default="nvt", description="ASE MD ensemble; CP MD supports fixed-cell nve and nvt only."
+    )
+    algorithm: str = Field(
+        default="bussi", description="ASE MD algorithm; CP MD supports velocityverlet, bussi, langevin and nvtberendsen."
+    )
     timestep_fs: float = Field(default=1.0, gt=0, description="ASE MD timestep in fs.")
     temperature_K: float = Field(default=300.0, gt=0, description="Target or initial temperature in K.")
     seed: int | None = Field(default=None, description="Random seed for initial velocities.")
@@ -911,6 +915,46 @@ class MDCalculation(StrictConfig):
         return self
 
 
+def validate_constant_potential_md_scope(
+    calculation: Mapping[str, Any], constant_potential: Mapping[str, Any]
+) -> None:
+    """Reject MD/CP combinations outside the fixed-cell ASE contract.
+
+    Args:
+        calculation: Raw or normalized MD calculation settings.
+        constant_potential: Raw or normalized CP decorator settings.
+
+    Raises:
+        ValueError: If the MD driver, integrator, or electronic boundary is unsupported.
+    """
+    if calculation.get("driver", "ase") != "ase":
+        raise ValueError("constant-potential MD requires calculation.driver=ase")
+    ensemble = calculation.get("ensemble", "nvt")
+    if ensemble not in {"nve", "nvt"}:
+        raise ValueError("constant-potential MD requires a fixed-cell nve or nvt ensemble")
+    algorithm = str(calculation.get("algorithm", "bussi")).lower()
+    allowed = {"nve": {"velocityverlet"}, "nvt": {"bussi", "langevin", "nvtberendsen"}}
+    if algorithm not in allowed[ensemble]:
+        raise ValueError(
+            f"calculation.algorithm={algorithm!r} is not supported for constant-potential MD ensemble={ensemble!r}"
+        )
+    if constant_potential.get("energy_boundary") != "compensated_gate":
+        raise ValueError("constant-potential MD requires energy_boundary=compensated_gate")
+    if str(constant_potential.get("reference_electrode", "SHE")).strip().lower() != "custom":
+        raise ValueError("constant-potential MD requires reference_electrode=custom")
+    target = constant_potential.get("target_mu_ev")
+    if constant_potential.get("target_mu_values_ev") is not None or constant_potential.get("potentials_v") is not None:
+        raise ValueError("constant-potential MD requires one scalar target_mu_ev, not a target list")
+    if target is None or isinstance(target, (bool, list, tuple, dict)):
+        raise ValueError("constant-potential MD requires one scalar target_mu_ev")
+    try:
+        finite_target = math.isfinite(float(target))
+    except (TypeError, ValueError):
+        finite_target = False
+    if not finite_target:
+        raise ValueError("constant-potential MD requires one finite scalar target_mu_ev")
+
+
 CalculationConfig = Annotated[
     Union[
         ConstantPotentialCalculation,
@@ -1075,7 +1119,7 @@ class CalculatorConfig(StrictConfig):
     dp: DPConfig | None = Field(default=None, description="DeepMD-kit calculator settings.")
     constant_potential: ConstantPotentialConfig | None = Field(
         default=None,
-        description="Optional strict constant-potential decorator settings.",
+        description="Optional strict constant-potential decorator settings; MD requires ASE fixed-cell compensated_gate with one scalar target.",
     )
 
     @model_validator(mode="after")
@@ -1233,10 +1277,14 @@ class ATSTConfig(StrictConfig):
                 if merged_parameters.get("two_fermi"):
                     raise ValueError("calculator.constant_potential does not support two_fermi")
             workflow = self.calculation.type
-            if workflow not in {"constant_potential", "relax", "neb"}:
+            if workflow not in {"constant_potential", "relax", "neb", "md"}:
                 raise ValueError(
                     "calculator.constant_potential is supported only for calculation.type="
-                    "constant_potential, relax, or neb"
+                    "constant_potential, relax, neb, or md"
+                )
+            if workflow == "md":
+                validate_constant_potential_md_scope(
+                    self.calculation.model_dump(mode="python"), cp.model_dump(mode="python")
                 )
             if workflow in {"relax", "neb"} and (
                 cp.potentials_v is not None or cp.target_mu_values_ev is not None

{atst_tools-2.3.0 → atst_tools-2.3.2}/src/atst_tools/utils/md_post.py

@@ -2,12 +2,18 @@
 
 from __future__ import annotations
 
+import math
 from pathlib import Path
 from typing import Any
 
 import numpy as np
 from ase.io import read, write
 
+from atst_tools.calculators.constant_potential import (
+    CP_FACTS_INFO_KEY,
+    CP_IDENTITY_INFO_KEY,
+    read_constant_potential_facts,
+)
 from atst_tools.utils.summary import max_force, energy, write_summary_json
 
 
@@ -36,6 +42,70 @@ def _write_md_summary(summary: dict[str, Any], output: str | Path) -> None:
     write_summary_json(summary, output)
 
 
+def _saved_step_time(atoms: Any, frame_index: int) -> dict[str, Any]:
+    """Return saved MD progress, falling back to frame index for old trajectories."""
+    step_key = "atst_md_step"
+    time_key = "atst_md_time_fs"
+    has_step = step_key in atoms.info
+    has_time = time_key in atoms.info
+    if not has_step and not has_time:
+        return {"step": frame_index}
+    if not has_step:
+        raise ValueError(f"saved MD frame is missing {step_key}")
+    if not has_time:
+        raise ValueError(f"saved MD frame is missing {time_key}")
+    step = atoms.info[step_key]
+    if isinstance(step, (bool, np.bool_)) or not isinstance(step, (int, np.integer)) or step < 0:
+        raise ValueError(f"saved MD frame has invalid {step_key}")
+    time_fs = atoms.info[time_key]
+    if (
+        isinstance(time_fs, (bool, np.bool_))
+        or not isinstance(time_fs, (int, float, np.integer, np.floating))
+        or not math.isfinite(float(time_fs))
+        or time_fs < 0
+    ):
+        raise ValueError(f"saved MD frame has invalid {time_key}")
+    return {"step": int(step), "time_fs": float(time_fs)}
+
+
+def _saved_constant_potential(atoms: Any) -> dict[str, Any] | None:
+    """Summarize only a complete CP facts envelope for the saved geometry."""
+    if CP_FACTS_INFO_KEY not in atoms.info and CP_IDENTITY_INFO_KEY not in atoms.info:
+        return None
+    payload = read_constant_potential_facts(atoms)
+    if payload is None:
+        raise ValueError("saved MD frame has malformed or stale constant-potential facts")
+    facts = payload["facts"]
+    return {
+        "energy_boundary": facts["energy_boundary"],
+        "energy_definition": payload["identity"]["energy_definition"],
+        "nelec": float(facts["nelec"]),
+        "mu_target_ev": float(facts["mu_target"]),
+        "mu_calc_ev": float(facts["mu_calc"]),
+        "residual_mu_ev": float(facts["residual_mu"]),
+        "cp_iterations": int(facts["cp_iterations"]),
+        "raw_energy_eV": float(facts["raw_energy"]),
+        "raw_free_energy_eV": float(facts["raw_free_energy"]),
+        "grand_potential_eV": float(facts["energy"]),
+        "grand_potential_free_energy_eV": float(facts["free_energy"]),
+    }
+
+
+def _frame_summary(atoms: Any, frame_index: int) -> dict[str, Any]:
+    """Return one trajectory frame summary from saved nuclear and CP state."""
+    progress = _saved_step_time(atoms, frame_index)
+    cp = _saved_constant_potential(atoms)
+    summary = {
+        **progress,
+        "energy_eV": energy(atoms),
+        "temperature_K": _temperature(atoms),
+        "max_force_eV_per_A": max_force(atoms),
+    }
+    if cp is not None:
+        summary["constant_potential"] = cp
+    return summary
+
+
 def summarize_md_trajectory(
     traj_file: str | Path,
     *,
@@ -44,15 +114,7 @@ def summarize_md_trajectory(
 ) -> dict[str, Any]:
     """Read and summarize an MD trajectory."""
     frames = read(str(traj_file), index=":")
-    frame_summaries = [
-        {
-            "step": index,
-            "energy_eV": energy(atoms),
-            "temperature_K": _temperature(atoms),
-            "max_force_eV_per_A": max_force(atoms),
-        }
-        for index, atoms in enumerate(frames)
-    ]
+    frame_summaries = [_frame_summary(atoms, index) for index, atoms in enumerate(frames)]
     selected = frame_summaries[-tail:] if tail and tail > 0 else frame_summaries
     latest = dict(frame_summaries[-1]) if frame_summaries else {}
     return {