From 592f9125155fedc1bf72ef3b47159c8722b032ee Mon Sep 17 00:00:00 2001 From: kirk0830 Date: Wed, 25 Feb 2026 17:23:34 +0800 Subject: [PATCH 1/2] Docs: update the documentation of abacuslite --- interfaces/ASE_interface/DEVELOP.md | 90 +++++++++++++++++++ interfaces/ASE_interface/README.md | 1 + .../ASE_interface/examples/metadynamics.py | 10 +++ 3 files changed, 101 insertions(+) create mode 100644 interfaces/ASE_interface/DEVELOP.md diff --git a/interfaces/ASE_interface/DEVELOP.md b/interfaces/ASE_interface/DEVELOP.md new file mode 100644 index 0000000000..acb1f1384b --- /dev/null +++ b/interfaces/ASE_interface/DEVELOP.md @@ -0,0 +1,90 @@ +# Developer Guide + +Abacuslite has the following file structure: +``` +. +├── __init__.py +├── core.py +├── io +│ ├── __init__.py +│ ├── generalio.py +│ ├── latestio.py +│ ├── legacyio.py +│ └── testfiles +├── utils +│ ├── __init__.py +│ └── ksampling.py +└── xtest.sh +``` + +## core.py + +This file contains the implementation of the Atomic Simulation Environment (ASE) calculator. + +## io + +This directory contains the input/output (I/O) functions for extracting information from ABACUS dumped files. A summary is here: + +### Long-term-support (LTS) version + +|Item|Regular expression|Example| +|----|----|----| +|esolver_type|'The esolver type has been set to : (\S+)'|`The esolver type has been set to : ksdft_pw`| +|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`| +|number of bands|'NBANDS\s+=\s+(\d+)'|`NBANDS = 40`| +|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`| +|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`| +|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`| +|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`| +|atomic positions|'^tau[c\|d]_([A-Z][a-z]?)\d+\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)\s+(-?\d+(\.\d+)?)*'|`taud_As1 0.2500000000 0.2500000000 0.2500000000 1.7321 0.0000000000 0.0000000000 0.0000000000`| +|eigenvalues|'\d+/\d+\s+kpoint\s+\(Cartesian\)\s+=\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d\|+)?)\s+\(\d+\s+pws\)'|` 1/1 kpoint (Cartesian) = 0.0000 0.0000 0.0000 (230 pws)`| +|atomic forces|'\s\*TOTAL\-FORCE\s\*\(eV\s*/Angstrom\)'|` TOTAL-FORCE (eV/Angstrom) `| +|total stress|'\s\*TOTAL\-STRESS\s\*\(KBAR\)'|` TOTAL-STRESS (KBAR) `| +|kpoints and weights|'\s\*(IBZ\|KPOINTS)\s+(DIRECT\|CARTESIAN)_X\s+(DIRECT\|CARTESIAN)_Y\s+(DIRECT\|CARTESIAN)_Z\s+WEIGHT(\s+ibz2bz)?'|` KPOINTS DIRECT_X DIRECT_Y DIRECT_Z WEIGHT`| +|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `| +|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `| + +### Latest version + +|Item|Regular expression|Example|Notes| +|----|----|----|----| +|esolver_type|'#ENERGY SOLVER#\s+(\S+)'|` #ENERGY SOLVER# ksdft_pw`|| +|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`|| +|number of bands|||has been removed| +|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`|| +|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`|| +|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`|| +|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`|| +|atomic positions|'atom\s+x\s+y\s+z\s+mag‘|` atom x y z mag`|"tauc/taud" suffix has been removed, therefore the way to read the coordinates changes to find the head of the table, then read the following `number of atoms` lines. On the other hand, if the `calculation` is set to `md`, ABACUS will not dump the atomic positions to running log anymore, instead, will read from the MD_dump file| +|eigenvalues|'spin=(\d)\s+k-point=(\d+)/(\d+)\s+Cartesian=\s*(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d+)?(e-\d+)?)\s+(-?\d(\.\d\|+)?(e-\d+)?)\s+\(\d+\s+plane wave\)'| spin=1 k-point=1/1 Cartesian=0.0000000 0.0000000 0.0000000 (1837 plane wave)|eigenvalues information has been removed from the running log, the file istate.info is renamed as eig_occ.txt, where the eigenvalues are read| +|atomic forces|'#\s\*TOTAL\-FORCE\s*\(eV\s*/Angstrom\)\s\*#'|` #TOTAL-FORCE (eV/Angstrom)#`|| +|total stress|'#\s\*TOTAL\-STRESS\s*\(kbar\)\s\*#'|` #TOTAL-STRESS (kbar)# `|| +|kpoints and weights|'\s*(IBZ\|KPOINTS)\s+(DIRECT\|CARTESIAN)_X\s+(DIRECT\|CARTESIAN)_Y\s+(DIRECT\|CARTESIAN)_Z\s+WEIGHT(\s+ibz2bz)?'|` KPOINTS DIRECT_X DIRECT_Y DIRECT_Z WEIGHT`|| +|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `|| +|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `|| + +Please look at detailed implementations in the following files. + +### generalio.py + +This module contains the general I/O functions for ABACUS. + +### latestio.py + +This module contains the I/O functions for the latest version of ABACUS. + +### legacyio.py + +This module contains the I/O functions for the Long-Term-Support (LTS) version of ABACUS. + +## utils + +This directory contains the utility modules for Abacuslite. + +### ksampling.py + +This module contains the wrapper of k-point sampling functions and helper functions. + +## xtest.sh + +This script can run all the unittests that programmed in all Python source files. \ No newline at end of file diff --git a/interfaces/ASE_interface/README.md b/interfaces/ASE_interface/README.md index e8c62efa5a..824e69900d 100644 --- a/interfaces/ASE_interface/README.md +++ b/interfaces/ASE_interface/README.md @@ -31,6 +31,7 @@ Please refer to the example scripts in the `examples` folder. Recommended learni 6. **md.py** - Molecular dynamics simulation 7. **constraintmd.py** - Constrained molecular dynamics simulation 8. **metadynamics.py** - Metadynamics simulation +9. **neb.py** - Nudged Elastic Band (NEB) calculation More usage examples will be provided in future versions. diff --git a/interfaces/ASE_interface/examples/metadynamics.py b/interfaces/ASE_interface/examples/metadynamics.py index 81142cd0c6..aba1c82e5f 100644 --- a/interfaces/ASE_interface/examples/metadynamics.py +++ b/interfaces/ASE_interface/examples/metadynamics.py @@ -4,6 +4,16 @@ conda install -c conda-forge plumed=2.8.2=mpi_openmpi_hb0545ae_0 conda install -c conda-forge py-plumed +You may be also interested in a newer version of plumed, a possible solution is +to search `plumed` at conda website: +https://anaconda.org/channels/conda-forge/packages/plumed/files +in which, up to 2026/02/25, the latest version is +``` +linux-64/plumed-2.9.2-mpi_openmpi_h02da92d_0.conda, +``` +you can install it with: +conda install -c conda-forge plumed=2.9.2=mpi_openmpi_h02da92d_0 + we do not recommend the default version of plumed installed by conda, which is nompi-labelled, may cause segmentation fault error during the MTD run. From 2be6d2d4250e02897ffb46f407a9ebe24bdff493 Mon Sep 17 00:00:00 2001 From: kirk0830 Date: Wed, 25 Feb 2026 17:50:34 +0800 Subject: [PATCH 2/2] update the online documentation --- docs/advanced/interface/ase.md | 133 ++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 61 deletions(-) diff --git a/docs/advanced/interface/ase.md b/docs/advanced/interface/ase.md index 1ec0b67475..e9b7b06280 100644 --- a/docs/advanced/interface/ase.md +++ b/docs/advanced/interface/ase.md @@ -2,95 +2,106 @@ ## Introduction -[ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment) provides a set of Python tools for setting, running, and analysing atomic simulations. We have developed an ABACUS calculator ([ase-abacus](https://gitlab.com/1041176461/ase-abacus )) to be used together with the ASE tools, which exists as an external project with respect to ASE and is maintained by ABACUS developers. +[ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment) performs as a powerful Pythonic platform for atomistic simulations, in which there are plenty of functionalties supported, such as various geometry optimization algorithms for finding both the minimum energy point and the transition states, including BFGS, BFGSLineSearch, FIRE, NEB, AUTO-NEB, etc, and various molecular dynamics techniques, including thermostats (Langevin, CSVR, Nose-Hoover Chain, etc) and metadynamics (via the interface with Plumed). + +Due to the growing number of softwares and machine-learning forcefields, we turn to maintain the interface with ASE by our own, while a legacy version of ASE interface can still be found at [our GitLab repository of ase-abacus](https://gitlab.com/1041176461/ase-abacus ). ## Installation -```bash -git clone https://gitlab.com/1041176461/ase-abacus.git -cd ase-abacus -pip install . -``` +We strongly recommend you create a virtual environment for the installation of Python packages of abacus, such as `conda` or `venv`, to avoid conflicts with other packages, for example, with the `conda`: -Another direct way: ```bash -pip install git+https://gitlab.com/1041176461/ase-abacus.git +conda create -n abacus python=3.10 +conda activate abacus ``` -## Environment variables - -[ABACUS](http://abacus.ustc.edu.cn) supports two types of basis sets: PW, LCAO. The path of pseudopotential and numerical orbital files can be set throught the environment variables `ABACUS_PP_PATH` and `ABACUS_ORBITAL_PATH`, respectively, e.g.: +Then, install the ASE interface by: ```bash - PP=${HOME}/pseudopotentials - ORB=${HOME}/orbitals - export ABACUS_PP_PATH=${PP} - export ABACUS_ORBITAL_PATH=${ORB} +cd interfaces/ASE_interface +pip install . ``` - -For PW calculations, only `ABACUS_PP_PATH` is needed. For LCAO calculations, both `ABACUS_PP_PATH` and `ABACUS_ORBITAL_PATH` should be set. - -Also, one can manally set the paths of PP and ORB when using ABACUS calculator in ASE. ## ABACUS Calculator -The default initialization command for the ABACUS calculator is +Present calculator implementation requires a "profile" to act as an interface between the Python runtime and the file system. +Instantiate an `AbacusProfile` object with proper settings: ```python -from ase.calculators.abacus import Abacus +from abacuslite import AbacusProfile +aprof = AbacusProfile( + command='mpirun -np 4 abacus', + omp_num_threads=1, + pseudo_dir='/path/to/folder/of/pseudopotentials', + orbital_dir='/path/to/folder/of/orbitals', # OPTIONAL! +) ``` +, by such lines, you build the interface between the computational environment and the Python runtime. +This interface can be reused in multiple calculations. -In order to run a calculation, you have to ensure that at least the following parameters are specified, either in the initialization or as environment variables: - -|keyword |description -|:---------------|:---------------------------------------------------------- -|`pp` |dict of pseudopotentials for involved elememts,
such as `pp={'Al':'Al_ONCV_PBE-1.0.upf',...}`. -|`pseudo_dir` |directory where the pseudopotential are located,
Can also be specified with the `ABACUS_PP_PATH`
environment variable. Default: `pseudo_dir=./`. -|`basis` |dict of orbital files for involved elememts, such as
`basis={'Al':'Al_gga_10au_100Ry_4s4p1d.orb'}`.
It must be set if you want to do LCAO
calculations. But for pw calculations, it can be omitted. -|`basis_dir` |directory where the orbital files are located,
Can also be specified with the `ABACUS_ORBITAL_PATH`
environment variable. Default: `basis_dir=./`. -|`xc` |which exchange-correlation functional is used.
An alternative way to set this parameter is via
seting `dft_functional` which is an ABACUS
parameter used to specify exchange-correlation
functional -|`kpts` |a tuple (or list) of 3 integers `kpts=(int, int, int)`,
it is interpreted as the dimensions of a Monkhorst-Pack
grid, when `kmode` is `Gamma` or `MP`. It is
interpreted as k-points, when `kmode` is `Direct`,
`Cartesian` or `Line`, and `knumber` should also
be set in these modes to denote the number of k-points.
Some other parameters for k-grid settings:
including `koffset` and `kspacing`. - -For more information on pseudopotentials and numerical orbitals, please visit [ABACUS]. The elaboration of input parameters can be found [here](../input_files/input-main.md). +Then, you can instantiate the `Abacus` calculator with the profile by: +```python +from abacuslite import Abacus +abacus = Abacus( + profile=aprof, + directory='/path/to/work/directory', + pseudopotentials={ + 'Si': 'Si_ONCV_PBE-1.0.upf', + }, + basissets={ + 'Si': 'Si_gga_8au_100Ry_2s2p1d.orb', + }, + inp={ + 'calculation': 'scf', + 'nspin': 1, + 'basis_type': 'lcao', + 'ks_solver': 'genelpa', + 'ecutwfc': 100, + 'symmetry': 1, + 'kspacing': 0.1 + } +) +``` +, where except the `directory`, you can focus on the setting of ABACUS itself. In `inp`, you can set everything as you do in INPUT file of ABACUS. The kpoint sampling can also be set by the `kpts` parameter, like: -The input parameters can be set like:: ```python - # for ABACUS calculator - calc = Abacus(profile=profile, - ecutwfc=100, - scf_nmax=100, - smearing_method='gaussian', - smearing_sigma=0.01, - basis_type='pw', - ks_solver='dav', - calculation='scf', - pp=pp, - basis=basis, - kpts=kpts) +abacus = Abacus( + # all other parameters + kpts={ + 'mode': 'mp-sampling', + 'gamma-centered': True, + 'nk': (4, 4, 4), + 'kshift': (0, 0, 0), + } +) ``` -The command to run jobs can be set by specifying `AbacusProfile`:: +If with the `tempfile` module, you can create an abacus instance whose directory will be automatically removed when leaves from the context: ```python - from ase.calculators.abacus import AbacusProfile - # for OpenMP setting inside python env - import os - os.environ("OMP_NUM_THREADS") = 1 - # for MPI setting used in abacus - mpi_num = 4 - # for ABACUS Profile - abacus = '/usr/local/bin/abacus' # specify abacus exec - profile = AbacusProfile(command=f'mpirun -n {mpi_num} {abacus}') # directly the command for running ABACUS +import tempfile +with tempfile.TemporaryDirectory() as tmpdir: + abacus = Abacus( + profile=aprof, + directory=tmpdir, + pseudopotentials={ + 'Si': 'Si_ONCV_PBE-1.0.upf', + }, + basissets={ + 'Si': 'Si_gga_8au_100Ry_2s2p1d.orb', + }, + inp={ + # the rest of input parameters + } + ) ``` -in which `abacus` sets the absolute path of the `abacus` executable. - -## MD Analysis -After molecular dynamics calculations, the log file `running_md.log` can be read. If the 'STRU_MD_*' files are not continuous (e.g. 'STRU_MD_0', 'STRU_MD_5', 'STRU_MD_10'...), the index parameter of read should be as a slice object. For example, when using the command `read('running_md.log', index=slice(0, 15, 5), format='abacus-out')` to parse 'running_md.log', 'STRU_MD_0', 'STRU_MD_5' and 'STRU_MD_10' will be read. +## Perform Calculations -The `MD_dump` file is also supported to be read-in by `read('MD_dump', format='abacus-md')` +In the new implementation, we limit the range of functionalties supported to mainly include the necessary ones, such as the SCF calculation, the energy and force/stress evaluation. The other features, such as starting the molecule dynamics directly in ABACUS from Python, is not supported anymore. Instead, it is encouraged to use the ASE tools to perform the molecule dynamics. +Please read the examples in `interfaces/ASE_interface/examples/` for more details. ## SPAP Analysis