Skip to content

Commit 592f912

Browse files
kirk0830kirk0830
committed
Docs: update the documentation of abacuslite
1 parent aec8ec2 commit 592f912

3 files changed

Lines changed: 101 additions & 0 deletions

File tree

‎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)