ATST-Tools

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, or IRC calculations driven by YAML instead of one-off Python scripts.

At A Glance

Area	Current 2.0.1 status
Package	Installable Python package with the atst console command.
Main interface	atst run CONFIG.yaml for all calculator-backed workflows.
Lightweight tools	atst config, atst abacus, atst neb, atst traj, atst dimer, atst relax, atst vibration.
Calculators	ABACUS through abacuslite; DeePMD-kit through deepmd.calculator.DP.
Configuration	Pydantic-governed YAML schema with generated user documentation.
Validation	Unit tests, example dry-runs, SAI ABACUS evidence, and DP/DPA smoke validation.
Release	2.0.1, documented in release notes.

What You Can Run

calculation.type	Workflow	Notes
neb	NEB / DyNEB	Endpoint single-point governance is enabled by default.
autoneb	AutoNEB	Adaptive image insertion plus final-chain post-processing.
d2s	Double-ended to single-ended TS search	Rough NEB followed by Dimer, Sella, or CCQN.
dimer	ASE Dimer	Single-ended transition-state search.
sella	Sella saddle search	Uses the external sella package.
ccqn	CCQN saddle search	Cone-shaped constrained quasi-Newton TS optimization.
relax	Structure optimization	ASE optimizer based relaxation.
vibration	Vibrations and thermochemistry	Harmonic and ideal-gas helpers.
irc	Sella IRC	Sella-backed IRC orchestration with controlled boundary diagnostics.

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

Development Install

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

Wheel Install

Build a local release artifact:

python -m build
pip install dist/atst_tools-2.0.1-py3-none-any.whl

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: a working DeePMD-kit Python installation and a model file outside git-tracked paths.

Quick Start

Choose the path that matches what you need:

Need	Start here
Run a workflow in 10 minutes	Chinese user guide
Pick an example	Examples overview
Check supported features	Feature status matrix
Look up YAML semantics	Configuration reference
Look up every schema field	YAML input variables
Use CLI helper commands	CLI reference
Browse all documentation paths	Documentation index

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

Print a schema-governed template:

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

List available workflow types:

atst run --list-types

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

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 Slurm jobs.

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:

Directory	Workflow focus
examples/01_neb_Li-Si	Quick NEB smoke case.
examples/02_neb_H2-Au	Surface NEB example.
examples/03_autoneb_Cy-Pt	AutoNEB workflow.
examples/04_dimer_CO-Pt	Dimer transition-state search.
examples/05_sella_H2-Au	Sella saddle search.
examples/06_relax_H2-Au	Geometry relaxation.
examples/07_vibration_H2-Au	Surface vibration analysis.
examples/08_d2s_Cy-Pt	Rough NEB plus single-ended TS search.
examples/09_lightweight_cli	Local helper command examples.
examples/10_irc_H2	IRC YAML examples.
examples/11_vibration_ideal_gas_H2	Ideal-gas thermochemistry example.
examples/12_ccqn_H2-Au	CCQN single-ended saddle search.
examples/13_neb_parallel_Cy-Pt	SAI NEB image-parallel example.
examples/14_autoneb_parallel_Cy-Pt	SAI AutoNEB image-parallel example.

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

Validation

The 2.0.1 README badges reflect the current governed project state:

• Version badge: pyproject.toml -> [project].version -> 2.0.1.
• Unit test coverage badge: measured with coverage run --source=src/atst_tools -m pytest tests -q, then reported with coverage report --omit='src/atst_tools/external/*'.
• Current first-party unit test coverage: 66%.
• Full source-tree coverage including the vendored abacuslite snapshot: 43%.

The vendored src/atst_tools/external/ASE_interface tree is kept for ABACUS backend reproducibility and is not treated as first-party ATST-Tools coverage.

For Developers

The main extension points are deliberately small:

Task	Start here
Add or change YAML inputs	src/atst_tools/utils/config_schema.py
Regenerate YAML docs	python -m atst_tools.utils.config_docs
Add a calculator backend	src/atst_tools/calculators/
Add an atst run workflow	src/atst_tools/scripts/main.py and src/atst_tools/workflows/
Add lightweight CLI commands	src/atst_tools/scripts/cli.py plus focused command modules
Add examples	examples/<case>/config.yaml and curated inputs/

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

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.

License

LGPL-v3 License.