ATST-Tools

用户文档与示例： GitHub 用户指南 · Gitee 用户指南 · GitHub 示例 · Gitee 示例

协作与规范源在 GitHub；Gitee 是维护者从 GitHub 手动拉取的同内容只读镜像；PyPI 仅发布 Python 包。

ATST-Tools is a pip-installable ASE transition-state workflow toolkit for ABACUS and DeePMD-kit calculators. It turns the project's legacy script collection into one governed command-line interface:

atst run CONFIG.yaml

Use it when you want repeatable NEB, AutoNEB, Dimer, Sella, CCQN, D2S, relaxation, vibration, IRC, MD, or experimental DMF calculations driven by YAML instead of one-off Python scripts. The development tree also contains an unreleased constant-potential candidate; its scope and validation boundary are documented separately below and in the feature status matrix.

At A Glance

What You Can Run

The constant_potential workflow is a development candidate shipped with the 2.2.7 line; it carries no Paimon/public tool-chain or platform acceptance claim. The current ATST scope is ABACUS-only fixed-geometry single-point/serial scans plus fixed-cell relax/neb with the explicit compensated_gate boundary. The legacy reference_fcp boundary is reference-only and is rejected for optimization workflows; no Paimon/public tool-chain or package-release acceptance is implied. See the configuration reference before using it.

Local pre/post-processing commands are intentionally lightweight. They do not construct calculators or submit expensive calculations:

atst neb make ...
atst neb post ...
atst traj collect ...
atst traj transform ...
atst dimer make-from-neb ...
atst relax post ...
atst vibration post ...
atst config validate ...
atst abacus prepare ...
atst abacus collect ...

Installation

From PyPI (Recommended)

pip install atst-tools

Without a version pin, this installs the version currently published on PyPI; it installs the current published release.

ATST-Tools requires Python 3.10 or newer. Sella-backed workflows install sella>=2.5 with the default package because Sella is a first-class workflow backend.

安装 profile：

• Serial（默认）：pip install atst-tools；不安装也不需要 mpi4py，可运行全部非 image-parallel 工作流和串行 NEB/AutoNEB。
• DP：pip install "atst-tools[dp]"；仅 DeePMD-kit calculator 工作流需要。
• Image-parallel NEB/AutoNEB：pip install "atst-tools[parallel]"；仅当通过外部 mpirun/srun 启动一个 Python rank 对应一个活动 image 时需要。

From Source

git clone https://github.com/QuantumMisaka/atst-tools.git
cd atst-tools
pip install .

Maintainers who need development installs, release artifacts, or validation operations should use the developer handover and the example validation operations guide.

ATST-Tools itself installs the Python workflow layer. Real calculations also need the selected calculator runtime:

• ABACUS: an executable ABACUS installation plus pseudopotential/orbital files referenced by YAML.
• DP / DeePMD-kit: install atst-tools[dp] or provide a compatible DeePMD-kit Python installation, plus a model file outside git-tracked paths.
• MPI image parallelism: install atst-tools[parallel] in an MPI-compatible Python environment and launch ATST with one Python rank per active image.
• DMF: ATST-Tools vendors PyDMF, but runtime still requires cyipopt and IPOPT, for example from conda-forge.

Quick Start

Choose the path that matches what you need:

Run a small relaxation example:

cd examples/06_relax_H2-Au
atst run config.yaml

Validate an input without launching the calculation:

atst run --dry-run examples/06_relax_H2-Au/config.yaml
atst config validate examples/06_relax_H2-Au/config.yaml --print-normalized

Embed the same schema validation from Python when a calling program needs a structured result rather than terminal output:

from atst_tools.api import validate_config

config = validate_config("examples/06_relax_H2-Au/config.yaml")
print(config["calculation"]["type"])

Use CLI/YAML for normal interactive or scheduled calculations; use the API for embedding. The stable Python API reference defines result ownership, MPI, artifacts, and calculator delegation.

For an external process host that needs a stable JSON handoff without parsing terminal output, use the installed API runner:

python -m atst_tools.api.runner --config config.yaml --workdir run --result-json atst_api_result.json

It invokes the same configuration-driven API, writes atst-api-result-v1 only from root rank, and never launches Slurm or MPI. See the Python API reference for flags, exit codes, and artifact ownership.

Print a schema-governed template:

atst run --show-template neb --calculator abacus
atst run --show-template neb --calculator dp
atst run --show-template dmf --calculator dp

List available workflow types:

atst run --list-types

Print the project banner and contributor credits:

atst banner

Minimal YAML Shape

Every production workflow uses the same top-level structure:

calculation:
  type: neb
  init_chain: inputs/init_neb_chain.traj
  fmax: 0.05
  max_steps: 100
  climb: true
  two_stage: true
  stage1_steps: 20
  stage1_fmax: 0.20

calculator:
  name: abacus
  abacus:
    command: abacus
    mpi: 4
    omp: 1
    directory: run_neb
    kpts: [2, 2, 2]
    parameters:
      calculation: scf
      ecutwfc: 100
      basis_type: lcao

The governed schema defines defaults, types, and descriptions for user-facing inputs. See YAML input variables for the generated reference and configuration reference for hand-written guidance.

Calculator Backends

ABACUS

ABACUS is integrated through abacuslite. ATST-Tools first tries an installed abacuslite package and then falls back to the vendored snapshot under src/atst_tools/external/ASE_interface/abacuslite.

Typical example files use:

calculator:
  name: abacus
  abacus:
    command: abacus
    mpi: 4
    omp: 1
    pseudo_dir: ../data
    orbital_dir: ../data

ATST-Tools is a layered abacuslite wrapper. Calculator-backed workflows such as NEB, D2S, Dimer, Sella, CCQN, Relax, Vibration, and IRC still run through atst run CONFIG.yaml; local ABACUS helpers support safe input preparation and result collection:

atst abacus prepare config.yaml --structure inputs/init.stru --output-dir abacus_input
atst abacus collect run_neb --output abacus_results.json

These helper commands do not run ABACUS and do not submit scheduler work.

DeePMD-kit / DP

DP support uses the official ASE calculator entry point, deepmd.calculator.DP. DeePMD-kit detects the model backend from the model file. Multi-head DPA/DPA3 models are configured through calculator.dp.head.

calculator:
  name: dp
  dp:
    model: ../../temp_repos/dp_model/DPA-3.1-3M.pt
    head: Omat24
    omp: 4
    share_calculator: true

The 2.0.0 DP validation used DPA-3.1-3M with the Omat24 head. The pinned download source, checksum, expected size, and local path are recorded in examples/dp_model_manifest.json. Model files and runtime outputs are intentionally not tracked by git.

python scripts/download_dp_model.py
python scripts/download_dp_model.py --check-only

Examples

The examples directory is the fastest way to learn the project:

Each calculation example uses config.yaml for ABACUS and, where available, config_dp.yaml for DP.

For Developers

The main extension points are deliberately small:

Developer governance starts from these maintained entry points:

• Documentation index
• Handover checklist
• YAML input governance
• Documentation standards
• Documentation architecture
• ABACUS wrapper guide
• Maintained atst-cli skill
• Release readiness gate

Project status and validation entry points:

• Feature status matrix
• Documentation governance report
• DP validation report
• Issue #25 AutoNEB fmax fix report
• MPI image-level NEB parallel summary

Version Governance

The package version has one source of truth:

pyproject.toml -> [project].version

Runtime entry points read that governed package version through atst_tools.package_version(). Source-tree runs read pyproject.toml, while installed-package runs use distribution metadata generated from the same field. There is no YAML-level config_version; user YAML is governed directly by the installed package schema, and unknown top-level fields are rejected.

Project Boundary

ATST-Tools owns workflow orchestration, YAML validation, calculator construction, trajectory naming, restart handling, ABACUS input/output helpers, examples, and documentation. Numerical engines remain external:

• ABACUS owns first-principles electronic-structure calculations.
• DeePMD-kit owns DP model loading and inference.
• ASE owns the core optimizer and transition-state method implementations.
• Sella owns its saddle-search and IRC algorithms.

References

If you publish work that uses the transition-state workflows in ATST-Tools, please cite the underlying methods alongside ATST-Tools itself:

• Sella saddle-point search: Ásgeirsson, V.; Birgisson, B. O.; Bjornsson, R.; Becker, U.; Neese, F.; Jónsson, H. Sella, an Open-Source Chemical Kinetics Environment. J. Chem. Theory Comput. 18 (8), 4914-4930 (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. (2025). https://doi.org/10.1021/acs.jctc.5c01015

License

LGPL-v3 License.