Docs: update the documentation of abacuslite

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, <br> such as `pp={'Al':'Al_ONCV_PBE-1.0.upf',...}`.
-|`pseudo_dir`    |directory where the pseudopotential are located, <br> Can also be specified with the `ABACUS_PP_PATH` <br> environment variable. Default: `pseudo_dir=./`.
-|`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.
-|`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=./`.
-|`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
-|`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`.
-
-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
 

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.

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.
 

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.