Skip to content

Commit e69de94

Browse files
kirk0830kirk0830
authored
Docs: update the documentation of abacuslite (#6984)
* Docs: update the documentation of abacuslite * update the online documentation
1 parent aec8ec2 commit e69de94

File tree

4 files changed

+173
-61
lines changed

4 files changed

+173
-61
lines changed

‎docs/advanced/interface/ase.md‎

Lines changed: 72 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -2,95 +2,106 @@
22

33
## Introduction
44

5-
[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.
5+
[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).
6+
7+
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 ).
68

79
## Installation
810

9-
```bash
10-
git clone https://gitlab.com/1041176461/ase-abacus.git
11-
cd ase-abacus
12-
pip install .
13-
```
11+
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`:
1412

15-
Another direct way:
1613
```bash
17-
pip install git+https://gitlab.com/1041176461/ase-abacus.git
14+
conda create -n abacus python=3.10
15+
conda activate abacus
1816
```
1917

20-
## Environment variables
21-
22-
[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.:
18+
Then, install the ASE interface by:
2319

2420
```bash
25-
PP=${HOME}/pseudopotentials
26-
ORB=${HOME}/orbitals
27-
export ABACUS_PP_PATH=${PP}
28-
export ABACUS_ORBITAL_PATH=${ORB}
21+
cd interfaces/ASE_interface
22+
pip install .
2923
```
30-
31-
For PW calculations, only `ABACUS_PP_PATH` is needed. For LCAO calculations, both `ABACUS_PP_PATH` and `ABACUS_ORBITAL_PATH` should be set.
32-
33-
Also, one can manally set the paths of PP and ORB when using ABACUS calculator in ASE.
3424

3525
## ABACUS Calculator
3626

37-
The default initialization command for the ABACUS calculator is
27+
Present calculator implementation requires a "profile" to act as an interface between the Python runtime and the file system.
28+
Instantiate an `AbacusProfile` object with proper settings:
3829

3930
```python
40-
from ase.calculators.abacus import Abacus
31+
from abacuslite import AbacusProfile
32+
aprof = AbacusProfile(
33+
command='mpirun -np 4 abacus',
34+
omp_num_threads=1,
35+
pseudo_dir='/path/to/folder/of/pseudopotentials',
36+
orbital_dir='/path/to/folder/of/orbitals', # OPTIONAL!
37+
)
4138
```
39+
, by such lines, you build the interface between the computational environment and the Python runtime.
40+
This interface can be reused in multiple calculations.
4241

43-
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:
44-
45-
|keyword |description
46-
|:---------------|:----------------------------------------------------------
47-
|`pp` |dict of pseudopotentials for involved elememts, <br> such as `pp={'Al':'Al_ONCV_PBE-1.0.upf',...}`.
48-
|`pseudo_dir` |directory where the pseudopotential are located, <br> Can also be specified with the `ABACUS_PP_PATH` <br> environment variable. Default: `pseudo_dir=./`.
49-
|`basis` |dict of orbital files for involved elememts, such as <br> `basis={'Al':'Al_gga_10au_100Ry_4s4p1d.orb'}`.<br> It must be set if you want to do LCAO <br> calculations. But for pw calculations, it can be omitted.
50-
|`basis_dir` |directory where the orbital files are located, <br> Can also be specified with the `ABACUS_ORBITAL_PATH`<br> environment variable. Default: `basis_dir=./`.
51-
|`xc` |which exchange-correlation functional is used.<br> An alternative way to set this parameter is via <br> seting `dft_functional` which is an ABACUS <br> parameter used to specify exchange-correlation <br> functional
52-
|`kpts` |a tuple (or list) of 3 integers `kpts=(int, int, int)`, <br>it is interpreted as the dimensions of a Monkhorst-Pack <br> grid, when `kmode` is `Gamma` or `MP`. It is <br> interpreted as k-points, when `kmode` is `Direct`,<br> `Cartesian` or `Line`, and `knumber` should also<br> be set in these modes to denote the number of k-points.<br> Some other parameters for k-grid settings:<br> including `koffset` and `kspacing`.
53-
54-
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).
42+
Then, you can instantiate the `Abacus` calculator with the profile by:
5543

44+
```python
45+
from abacuslite import Abacus
46+
abacus = Abacus(
47+
profile=aprof,
48+
directory='/path/to/work/directory',
49+
pseudopotentials={
50+
'Si': 'Si_ONCV_PBE-1.0.upf',
51+
},
52+
basissets={
53+
'Si': 'Si_gga_8au_100Ry_2s2p1d.orb',
54+
},
55+
inp={
56+
'calculation': 'scf',
57+
'nspin': 1,
58+
'basis_type': 'lcao',
59+
'ks_solver': 'genelpa',
60+
'ecutwfc': 100,
61+
'symmetry': 1,
62+
'kspacing': 0.1
63+
}
64+
)
65+
```
66+
, 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:
5667

57-
The input parameters can be set like::
5868
```python
59-
# for ABACUS calculator
60-
calc = Abacus(profile=profile,
61-
ecutwfc=100,
62-
scf_nmax=100,
63-
smearing_method='gaussian',
64-
smearing_sigma=0.01,
65-
basis_type='pw',
66-
ks_solver='dav',
67-
calculation='scf',
68-
pp=pp,
69-
basis=basis,
70-
kpts=kpts)
69+
abacus = Abacus(
70+
# all other parameters
71+
kpts={
72+
'mode': 'mp-sampling',
73+
'gamma-centered': True,
74+
'nk': (4, 4, 4),
75+
'kshift': (0, 0, 0),
76+
}
77+
)
7178
```
7279

73-
The command to run jobs can be set by specifying `AbacusProfile`::
80+
If with the `tempfile` module, you can create an abacus instance whose directory will be automatically removed when leaves from the context:
7481

7582
```python
76-
from ase.calculators.abacus import AbacusProfile
77-
# for OpenMP setting inside python env
78-
import os
79-
os.environ("OMP_NUM_THREADS") = 1
80-
# for MPI setting used in abacus
81-
mpi_num = 4
82-
# for ABACUS Profile
83-
abacus = '/usr/local/bin/abacus' # specify abacus exec
84-
profile = AbacusProfile(command=f'mpirun -n {mpi_num} {abacus}') # directly the command for running ABACUS
83+
import tempfile
84+
with tempfile.TemporaryDirectory() as tmpdir:
85+
abacus = Abacus(
86+
profile=aprof,
87+
directory=tmpdir,
88+
pseudopotentials={
89+
'Si': 'Si_ONCV_PBE-1.0.upf',
90+
},
91+
basissets={
92+
'Si': 'Si_gga_8au_100Ry_2s2p1d.orb',
93+
},
94+
inp={
95+
# the rest of input parameters
96+
}
97+
)
8598
```
8699

87-
in which `abacus` sets the absolute path of the `abacus` executable.
88-
89-
## MD Analysis
90-
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.
100+
## Perform Calculations
91101

92-
The `MD_dump` file is also supported to be read-in by `read('MD_dump', format='abacus-md')`
102+
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.
93103

104+
Please read the examples in `interfaces/ASE_interface/examples/` for more details.
94105

95106
## SPAP Analysis
96107

‎interfaces/ASE_interface/DEVELOP.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Developer Guide
2+
3+
Abacuslite has the following file structure:
4+
```
5+
.
6+
├── __init__.py
7+
├── core.py
8+
├── io
9+
│ ├── __init__.py
10+
│ ├── generalio.py
11+
│ ├── latestio.py
12+
│ ├── legacyio.py
13+
│ └── testfiles
14+
├── utils
15+
│ ├── __init__.py
16+
│ └── ksampling.py
17+
└── xtest.sh
18+
```
19+
20+
## core.py
21+
22+
This file contains the implementation of the Atomic Simulation Environment (ASE) calculator.
23+
24+
## io
25+
26+
This directory contains the input/output (I/O) functions for extracting information from ABACUS dumped files. A summary is here:
27+
28+
### Long-term-support (LTS) version
29+
30+
|Item|Regular expression|Example|
31+
|----|----|----|
32+
|esolver_type|'The esolver type has been set to : (\S+)'|`The esolver type has been set to : ksdft_pw`|
33+
|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`|
34+
|number of bands|'NBANDS\s+=\s+(\d+)'|`NBANDS = 40`|
35+
|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`|
36+
|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`|
37+
|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`|
38+
|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`|
39+
|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`|
40+
|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)`|
41+
|atomic forces|'\s\*TOTAL\-FORCE\s\*\(eV\s*/Angstrom\)'|` TOTAL-FORCE (eV/Angstrom) `|
42+
|total stress|'\s\*TOTAL\-STRESS\s\*\(KBAR\)'|` TOTAL-STRESS (KBAR) `|
43+
|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`|
44+
|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `|
45+
|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `|
46+
47+
### Latest version
48+
49+
|Item|Regular expression|Example|Notes|
50+
|----|----|----|----|
51+
|esolver_type|'#ENERGY SOLVER#\s+(\S+)'|` #ENERGY SOLVER# ksdft_pw`||
52+
|nspin|'nspin\s+=\s+(\d+)'|`nspin = 4`||
53+
|number of bands|||has been removed|
54+
|number of atoms|'TOTAL ATOM NUMBER\s*=\s*(\d+)'|`TOTAL ATOM NUMBER = 2`||
55+
|lattice constant|'lattice constant \(Angstrom\)\s*=\s*(-?\d+(\.\d+)?)'|`lattice constant (Angstrom) = 0.529177`||
56+
|lattice vectors|'^Lattice vectors: \(Cartesian coordinate: in unit of a_0\)$'|` Lattice vectors: (Cartesian coordinate: in unit of a_0)`||
57+
|coordinate system|'^(DIRECT\|CARTESIAN) COORDINATES'|`DIRECT COORDINATES`||
58+
|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|
59+
|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|
60+
|atomic forces|'#\s\*TOTAL\-FORCE\s*\(eV\s*/Angstrom\)\s\*#'|` #TOTAL-FORCE (eV/Angstrom)#`||
61+
|total stress|'#\s\*TOTAL\-STRESS\s*\(kbar\)\s\*#'|` #TOTAL-STRESS (kbar)# `||
62+
|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`||
63+
|energy|'\s*ENERGY\s+Rydberg\s+eV'|` Energy Rydberg eV `||
64+
|total magnetism|'\s\*Total\sMagnetism\s\(uB\)(\s+x\s+y\s+z)?\s\*'|` Total Magnetism (uB) `||
65+
66+
Please look at detailed implementations in the following files.
67+
68+
### generalio.py
69+
70+
This module contains the general I/O functions for ABACUS.
71+
72+
### latestio.py
73+
74+
This module contains the I/O functions for the latest version of ABACUS.
75+
76+
### legacyio.py
77+
78+
This module contains the I/O functions for the Long-Term-Support (LTS) version of ABACUS.
79+
80+
## utils
81+
82+
This directory contains the utility modules for Abacuslite.
83+
84+
### ksampling.py
85+
86+
This module contains the wrapper of k-point sampling functions and helper functions.
87+
88+
## xtest.sh
89+
90+
This script can run all the unittests that programmed in all Python source files.

‎interfaces/ASE_interface/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ Please refer to the example scripts in the `examples` folder. Recommended learni
3131
6. **md.py** - Molecular dynamics simulation
3232
7. **constraintmd.py** - Constrained molecular dynamics simulation
3333
8. **metadynamics.py** - Metadynamics simulation
34+
9. **neb.py** - Nudged Elastic Band (NEB) calculation
3435

3536
More usage examples will be provided in future versions.
3637

‎interfaces/ASE_interface/examples/metadynamics.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@
44
conda install -c conda-forge plumed=2.8.2=mpi_openmpi_hb0545ae_0
55
conda install -c conda-forge py-plumed
66
7+
You may be also interested in a newer version of plumed, a possible solution is
8+
to search `plumed` at conda website:
9+
https://anaconda.org/channels/conda-forge/packages/plumed/files
10+
in which, up to 2026/02/25, the latest version is
11+
```
12+
linux-64/plumed-2.9.2-mpi_openmpi_h02da92d_0.conda,
13+
```
14+
you can install it with:
15+
conda install -c conda-forge plumed=2.9.2=mpi_openmpi_h02da92d_0
16+
717
we do not recommend the default version of plumed installed by conda, which
818
is nompi-labelled, may cause segmentation fault error during the MTD run.
919

0 commit comments

Comments
 (0)