atst-tools 2.0.0

Advanced ASE Transition State Tools for ABACUS and Deep-Potential

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

At A Glance

Area	Current 2.0.0 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.0, 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 or Sella.
dimer	ASE Dimer	Single-ended transition-state search.
sella	Sella saddle search	Uses the external sella package.
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.0-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

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, 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. Model files and runtime outputs are intentionally not tracked by git.

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.

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

Validation

The 2.0.0 README badges reflect the current governed project state:

• Version badge: pyproject.toml -> [project].version -> 2.0.0.
• 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 documentation:

• Documentation index
• YAML input governance
• Documentation standards
• ABACUS wrapper guide
• Maintained atst-cli skill
• Refactor stage review
• User experience reinforcement report
• Feature status matrix
• DP validation report
• IRC integration review

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. The YAML config_version is a separate schema-compatibility marker and is also 2.0.0 for this release line.

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.