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 or by an Agent's Python integration instead of one-off scripts. The package also includes a constant-potential development candidate in 2.2.8; its scope and validation boundary are documented separately below and in the feature status matrix.

At A Glance

The 2.2.9 candidate adds the explicit read-only command atst vibration validate and the matching validate_ts API; neither is in the published 2.2.8 package.

What You Can Run

The constant_potential workflow ships in the 2.2.8 package as a development candidate; its presence does not establish production readiness or Paimon/public tool-chain or platform acceptance. 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 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:

After installing the package, obtain the examples separately if you do not already have a checkout. Use the tag matching your installed version:

git clone --branch main https://github.com/QuantumMisaka/atst-tools.git
cd atst-tools
atst config validate examples/06_relax_H2-Au/config.yaml --print-normalized
atst run --dry-run examples/06_relax_H2-Au/config.yaml

Try a local operation without ABACUS, a DP model, or a GPU:

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, not evaluated energies or forces. Configuration validation does not establish backend readiness. Once ABACUS, its data files and suitable resources are available, run a calculation from its example directory. The H2/Au Relax example uses four backend MPI ranks, cusolver, and a one-step optimization limit; adapt it to your environment and inspect convergence separately. The Chinese guide walks through that run, its outputs, and common problems.

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"])

CLI/YAML and the Agent Python API consume the same ASE transition-state workflows. Use CLI/YAML for interactive or scheduled calculations; use the API when an Agent or Python application needs structured results or caller-owned calculator integration. A calculation reports execution and available optimizer facts; it does not automatically establish transition-state validity or launch IRC. Transition-state screening is a separate explicit read-only operation: In 2.2.9, atst vibration validate or the additive validate_ts API consumes saved vibration and optional frozen structure evidence. The Python API reference defines the result, MPI, artifact, and calculator boundaries.

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 and writes atst-api-result-v1 only from root rank. ATST does not allocate resources or start the outer Python MPI launch; a configured calculator command may launch its own ABACUS MPI process. 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

Start with the source architecture guide to understand package responsibilities, the shared CLI/API execution path, the purpose of runtime and bench, and where to make changes.

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:

• 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.