Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion interfaces/ASE_interface/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ abacuslite is a lightweight plugin for ABACUS (Atomic-orbital Based Ab-initio Co
### Key Features

- **Lightweight Design**: Implemented as a plugin, no need to modify ASE core code
- **Version Compatibility**: Supports ASE versions satisfying the package requirement `ase>=3.22`
- **Version Compatibility**: Requires `ase>=3.23`, because ASE 3.22 lacks `ase.calculators.genericfileio`, which this plugin imports
- **ASE Integration**: Uses ASE as the running platform, making ABACUS a callable calculator within it
- **Function Support**: Provides SCF-based energy, force, and stress evaluations through ASE. ASE can use these evaluations for relaxation, molecular dynamics, NEB, band-structure, and density-of-states workflows.
- **Socket Support**: `AbacusSocketIO` provides fixed-cell i-PI socket calculations, with energy always available and forces/stress enabled independently when requested.
Expand Down Expand Up @@ -39,6 +39,55 @@ Please refer to the example scripts in the `examples` folder. Recommended learni

The regular `Abacus` calculator runs one ABACUS calculation for each ASE property evaluation. ASE controls the relaxation, molecular-dynamics, and other workflow steps. The socket calculator reuses one ABACUS process for position updates, while the cell and electronic-structure settings remain fixed for that calculator instance.

## Result collection

SCF results are selected by matching the written STRU to the running-log
structure, including periodic translations and the original ASE atom order.
Unmatched or malformed SCF output raises an error. Native relaxation and MD
continue to use the final frame; native MD uses MD_dump when the running log
does not contain the trajectory. Each calculator retains its own LTS/develop
reader, so calculators for different engine versions can coexist.

Both output readers accept paths or named text streams, using the log filename
to locate companion output files. Caller-owned streams remain open and are read
from their current position; seek to the start before rereading. Returned ASE
positions and cells are Cartesian Angstrom values, with Direct and alat
conversions applied once by the reader. Raw trajectory dictionaries retain
their file-native conventions.

Returned structures represent the simulation box with periodic boundaries in
all directions, including molecules in vacuum and slabs. This changes earlier
SCF output flags; readers do not infer physical isolation from vacuum thickness.
For nonperiodic geometry analysis, make a copy and explicitly set its `pbc`
flags; this does not change the completed calculation's boundary conditions.

The default SCF identity tolerance is **1e-4 Angstrom**, applied to each cell
component and periodic Cartesian position residual with no relative tolerance.
This accommodates common six-significant-digit running-log rounding; the
stricter 1e-5 bound can reject valid LTS output. It is a
structure-identity tolerance, separate from SCF, force and optimization
convergence settings. It is not a universal printing-error bound: larger cells,
non-unit lattice constants and skewed-cell coordinate transformations can
accumulate more error.

Result parsing does **not read abacus.json**. Missing or malformed JSON does not
affect collection. Writing new input leaves existing JSON files untouched.

Both ASE `energy` and `free_energy` retain ABACUS's force-consistent
`E_KohnSham`. When an entropy term is present, `energy_without_entropy` is
provided separately; a missing term remains unknown. Noncollinear vector
moments are retained without modifying ASE's global property definitions.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: the recommended examples/soc.py and tests/magnetic.py still replace ASE’s global magnetic-property definitions. The new handoff no longer needs that workaround; removing it would align these consumers with the documented behavior and avoid rejecting later collinear results in the same process.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 770926e: removed the global ASE magnetic-property mutation from examples/soc.py and tests/magnetic.py. The calculator now handles vector moments locally.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The global magnetic-property mutations remain removed from both examples/soc.py and tests/magnetic.py. This consumer correction is retained in the reduced diff; it is not part of the test-directory removal (329bdf8).

STRU writing preserves representable species masses and converts ASE
velocities to atomic units. Different masses within one ABACUS species are
rejected because one species entry cannot represent them.

The existing inline tests (`abacuslite/xtest.sh`) and engine integration tests
(`tests/xtest.sh`) are run by the ASE plugin workflow. Standalone offline
regressions and recorded output fixtures are maintained in
[QuantumMisaka/abacuslite](https://github.com/QuantumMisaka/abacuslite).
The calculator and parser corrections were adapted from standalone revisions
`39ab1d5` and `5d3da5d`, with follow-up ASE compatibility fixes.

## Authors

- Yuyang Ji
Expand Down
Loading
Loading