quantummisaka/atst-tools/atst-cli

ATST CLI Skill

Use this skill for ATST-Tools CLI work in this repository.

Environment

• Work from the repository root.
• Prefer the project environment: conda activate atst-dev.
• If the default Python cannot import ase, run checks with

conda run -n atst-dev <command>.

First Checks

git branch --show-current
git status --short
atst --version
atst banner
atst --help
atst prepare RUN_DIR --workflow neb --init-structure INIT/STRU --final-structure FINAL/STRU -o atst_neb.yaml

Before launching expensive calculations, validate YAML:

atst run --dry-run CONFIG.yaml
atst config validate CONFIG.yaml --print-normalized

Workflow Commands

Use atst run CONFIG.yaml for calculator-backed workflows:

• neb, autoneb
• d2s
• dimer, sella
• relax
• vibration
• irc
• md

ABACUS workflows use calculator.name: abacus and the active abacuslite backend. DP workflows use calculator.name: dp and deepmd.calculator.DP.

On GPU hosts the optional runtime controls bind devices and thread budgets before the scientific stack is imported, and can write a run-evidence sidecar:

atst run CONFIG.yaml --devices 0,1 --threads auto
atst run CONFIG.yaml --telemetry              # adds runtime_evidence.json
python -m atst_tools.api.runner --config CONFIG.yaml --devices 0

--devices counts 0-based indices inside the inherited visible set (never physical renumbering); --binding round_robin maps local_rank onto a verified single-node pool for MPI launches. Without any runtime request the legacy in-process path is unchanged. See docs/user/CONFIG_REFERENCE.md section 4 and docs/user/CLI_REFERENCE.md for the full contract.

Lightweight Commands

These do not launch ABACUS or DP:

atst banner
atst config validate CONFIG.yaml --print-normalized
atst abacus prepare CONFIG.yaml --structure STRUCTURE --output-dir DIR
atst abacus collect RUN_DIR --output abacus_results.json
atst neb make INIT FINAL N_IMAGES -o init_neb_chain.traj --method linear
atst neb post neb.traj --n-max N --vib-analysis
atst neb summary neb.traj --n-max N --tail 5
atst md summary md.traj --tail 5
atst md post md.traj --output-format extxyz --output-prefix md_post
atst dimer make-from-neb neb.traj --n-max N --output-traj dimer_init.traj
atst dimer summary dimer.traj --tail 5
atst relax post relax.traj --output-format traj --output restart.traj
atst relax summary relax.traj --tail 5
atst vibration post config.yaml --output vibration_results.json
atst vibration summary config.yaml
atst vibration validate vibration_results.json --structure frozen_ts.traj
atst d2s summary config.yaml --format json --output d2s_summary.json
atst traj collect frames/*.xyz -o collection.traj --no-calc
atst traj transform collection.traj --format extxyz --output-prefix collection

atst neb make --method accepts IDPP (default) or linear. summary commands are read-only monitors/post-summaries; they do not create calculators or launch ABACUS/DP. In the current 2.3.1 release, atst vibration validate is an explicit read-only screen of saved vibration data and optional frozen structure evidence. It never launches a calculator; missing evidence remains unknown.

ABACUS Wrapper Boundary

ATST-Tools is a layered wrapper:

• It owns YAML validation, workflow orchestration, restart helpers, examples,

and common ABACUS input/output helpers.

• It uses abacuslite as the ABACUS ASE calculator backend.
• It does not replace ABACUS, abacuslite, Slurm, or site-specific job launchers.

Read docs/user/ABACUSLITE_WRAPPER_GUIDE.md before changing this boundary.

Validation

For CLI changes, run targeted tests first:

conda run -n atst-dev pytest tests/unit/test_cli.py -q

Before reporting completion, run:

conda run -n atst-dev pytest tests -q
atst --help
atst config validate examples/06_relax_H2-Au/config.yaml --print-normalized

Update docs when command behavior, config shape, or wrapper boundaries change:

• README.md
• docs/user/CLI_REFERENCE.md
• docs/user/CONFIG_REFERENCE.md
• docs/user/USER_GUIDE_CN.md
• examples/README.md