Add atst examples in ASE interfaces examples by QuantumMisaka · Pull Request #7608 · deepmodeling/abacus-develop

QuantumMisaka · 2026-07-07T12:42:24Z

Reminder

I have read AGENTS.md and docs/developers_guide/agent_governance.md.
I have linked an issue or explained why this PR does not need one.
I have added adequate unit tests and/or case tests, or explained why not.
I have listed the exact verification commands run and their results.
I have described user-visible behavior changes, including INPUT parameter changes.
I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
No governance exception is requested.

Linked Issue

No linked issue. This PR only adds optional ATST-Tools workflow examples and a short README entry under the ASE interface examples.

Unit Tests and/or Case Tests for my changes

git diff --check -- interfaces/ASE_interface/README.md interfaces/ASE_interface/examples/atst_tools: passed.
Conflict-marker scan over interfaces/ASE_interface/README.md interfaces/ASE_interface/examples/atst_tools: passed.
conda run -n atst-dev atst config validate ... --print-normalized for all added YAML configs: passed.
conda run -n atst-dev atst run --dry-run ... for all added workflow configs: passed.
conda run -n atst-dev atst abacus prepare ... and atst abacus collect ... for the helper workflow: passed.
No upstream ABACUS case test is added because ATST-Tools remains an optional external workflow layer and no ABACUS core behavior is changed.

Exact Verification Performed

Commands run:
- git diff --check -- interfaces/ASE_interface/README.md interfaces/ASE_interface/examples/atst_tools
- conflict-marker scan over interfaces/ASE_interface/README.md interfaces/ASE_interface/examples/atst_tools
- generated inputs with each added make_inputs.py
- conda run -n atst-dev atst config validate <config> --print-normalized for relax_si, neb_si, sella_h2, ccqn_h2, both md_si configs, and abacus_helper
- conda run -n atst-dev atst run --dry-run <config> for relax_si, neb_si, sella_h2, ccqn_h2, and both md_si configs
- conda run -n atst-dev atst abacus prepare config.yaml --structure inputs/init.extxyz --output-dir prepared_abacus --force
- conda run -n atst-dev atst abacus collect prepared_abacus --output abacus_results.json
Result summary: all listed checks completed successfully in the installed atst-tools environment.
Checks not run, with reason: full ABACUS numerical runs were not launched in CI because these examples are optional external workflow examples and require a configured ABACUS runtime environment.

What's changed?

Adds optional ATST-Tools examples for relax, NEB, Sella, CCQN, MD, and ABACUS input preparation under interfaces/ASE_interface/examples/atst_tools/.
Documents ATST-Tools as an optional workflow layer on top of abacuslite.
Does not add ATST-Tools as an abacuslite dependency and does not change ABACUS runtime behavior.

Governance Checklist

Global dependencies: no GlobalV, GlobalC, or PARAM code references are added.
Default parameters: no existing interface default arguments are changed.
Headers: no header dependencies are changed.
Line endings: changed text files use LF.
Build linkage: no new ABACUS source files are added, so no CMakeLists.txt update is needed.
Documentation: the ASE interface README and the new example README document the optional workflow usage.
CodeRabbit: automatic review can be requested by maintainers if needed.

INPUT Parameter Changes

Parameters added/removed/changed: none.
docs/parameters.yaml updated: not applicable.
docs/advanced/input_files/input-main.md updated: not applicable.
No INPUT documentation update is required because this PR only adds optional example YAML files for ATST-Tools and does not change ABACUS INPUT semantics.

Core Module Impact

Affected core modules: none.
Risk summary: examples and documentation only; no source/ files are changed.
Compatibility or performance impact: none expected for ABACUS core modules.

Governance Exception

Rule: none.
Reason: no exception is requested.
Scope: not applicable.
User or maintenance risk: not applicable.
Why the normal rule cannot be followed now: not applicable.
Follow-up cleanup plan: not applicable.
Requested approver: not applicable.

kirk0830

this PR tries to show the usage to interface with the ATST-Tools, which is the package collects some sophisticated algorithms that can widen the scope of ABACUS usage. However, the introduced dependency is unacceptable, the change proposed on the file structure is also to be corrected.

kirk0830 · 2026-07-08T14:22:28Z

 7. **constraintmd.py** - Constrained molecular dynamics simulation
 8. **metadynamics.py** - Metadynamics simulation
 9. **neb.py** - Nudged Elastic Band (NEB) calculation
+10. **examples/atst_tools/README.md** - optional ATST-Tools workflow examples that use abacuslite for relax, NEB, Sella, CCQN, MD, and ABACUS input helpers


This may mess up the hierarchy of the file tree... I would suggest place two or at most three examples directly in this folder, illustrate the cooperative use with ATST-tools, rather than an individual directory...

kirk0830 · 2026-07-08T14:23:40Z

+
+| Case | Workflow | Purpose |
+| --- | --- | --- |
+| `relax_si` | `calculation.type: relax` | Basic geometry optimization through `atst run`. |


the atst run usage is beyond the scope of abacuslite which is the interface with ASE

kirk0830 · 2026-07-08T14:26:04Z

+| `sella_h2` | `calculation.type: sella` | Standalone single-ended saddle search syntax. |
+| `ccqn_h2` | `calculation.type: ccqn` | CCQN with an explicit reactive bond. |
+| `md_si` | `calculation.type: md` | ASE-driven MD and ABACUS-native MD templates. |
+| `abacus_helper` | `atst abacus prepare/collect` | INPUT/KPT/STRU preparation and conservative output collection. |


this is not quite a relevant example because it is not about the extension of functionalities of ABACUS, although it is a good infrastructure and must be helpful for cases, but not suitable here. I would suggest remove it

kirk0830 · 2026-07-08T14:26:56Z

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


again, the CLI usage of ATST-Tools is beyond the scope of the interface to ASE

kirk0830 · 2026-07-08T14:30:47Z

+atst run config.yaml
+```
+
+For SAI GPU runs, keep the same YAML structure but change


The commercial supercomputer is not planned to be specially discussed and treated in any place of ABACUS code, as far as I remember. @mohanchen

kirk0830 · 2026-07-08T14:32:30Z

+atst abacus prepare config.yaml --structure inputs/init.extxyz --output-dir prepared_abacus --force
+atst abacus collect prepared_abacus --output abacus_results.json


likewise, this would be better place into the manual of ATST-Tools itself, rather than in ABACUS, like there is no instruction of an air conditioner in the house when you buy it.

kirk0830 · 2026-07-08T14:33:39Z

please do not contain the files relevant with the CLI usage of ATST-Tools in ABACUS repository, this introduces the dependency on ATST-Tools into ABACUS.

kirk0830 · 2026-07-08T14:34:28Z

what's the significance of this file?

kirk0830 · 2026-07-08T14:35:44Z

please do not contain the input script of ATST-Tools, this brings about the unnecessary dependency on external software to ABACUS

docs: add optional atst-tools examples

27b2775

QuantumMisaka force-pushed the feat/atst_example branch from b2f56f4 to 27b2775 Compare July 7, 2026 12:44

QuantumMisaka marked this pull request as draft July 7, 2026 15:09

QuantumMisaka requested a review from kirk0830 July 7, 2026 15:09

QuantumMisaka marked this pull request as ready for review July 7, 2026 15:09

QuantumMisaka changed the title ~~feat/atst_example~~ Add atst examples in ASE interfaces examples Jul 7, 2026

QuantumMisaka added the Interfaces Interfaces with other packages label Jul 7, 2026

kirk0830 suggested changes Jul 8, 2026

View reviewed changes

Merge branch 'develop' into feat/atst_example

549ff13

QuantumMisaka marked this pull request as draft July 8, 2026 14:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add atst examples in ASE interfaces examples#7608

Add atst examples in ASE interfaces examples#7608
QuantumMisaka wants to merge 2 commits into
deepmodeling:developfrom
QuantumMisaka:feat/atst_example

QuantumMisaka commented Jul 7, 2026 •

edited

Loading

Uh oh!

kirk0830 left a comment

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

kirk0830 Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		atst abacus prepare config.yaml --structure inputs/init.extxyz --output-dir prepared_abacus --force
		atst abacus collect prepared_abacus --output abacus_results.json

Uh oh!

Conversation

QuantumMisaka commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reminder

Linked Issue

Unit Tests and/or Case Tests for my changes

Exact Verification Performed

What's changed?

Governance Checklist

INPUT Parameter Changes

Core Module Impact

Governance Exception

Uh oh!

kirk0830 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

QuantumMisaka commented Jul 7, 2026 •

edited

Loading