Merge pull request #33 from alchem0x2A/master

Various powerups
alchem0x2A · Sep 28, 2023 · 8a60d8b · 8a60d8b
2 parents e146aee + f6bbdc0
commit 8a60d8b
Show file tree

Hide file tree

Showing 54 changed files with 3,766 additions and 416 deletions.
diff --git a/.github/workflows/installation_test.yml b/.github/workflows/installation_test.yml
@@ -30,22 +30,29 @@ jobs:
     - name: Install dependencies
       run: |
         # mamba install -c conda-forge ase>=3.22 pymatgen flake8 pytest
-        mamba install -c alchem0x2a sparc
+        mamba install -c conda-forge sparc-x
         # pip install pyfakefs
     - name: Install package
       run: |
         pip install -e ".[test]"
         # Download the external psp data
         python -m sparc.download_data
+    - name: Download SPARC output files to SPARC-master
+      run: |
+        wget https://github.com/SPARC-X/SPARC/archive/refs/heads/master.zip
+        unzip master.zip
     - name: Test with pytest
       run: |
         # python -m pytest -svv tests/ --cov=sparc --cov-report=json --cov-report=html
+        export SPARC_TESTS_DIR="./SPARC-master/tests"
+        export ASE_SPARC_COMMAND="mpirun -n 1 sparc"
         coverage run -a -m pytest -svv tests/
         coverage json --omit="tests/*.py"
         coverage html --omit="tests/*.py"
         COVERAGE=`cat coverage.json | jq .totals.percent_covered | xargs printf '%.*f' 0`
         echo "Current coverage is $COVERAGE"
         echo "COVPERCENT=$COVERAGE" >> $GITHUB_ENV
+        
     - name: Lint with flake8
       run: |
         echo $CONDA_PREFIX
@@ -58,8 +65,8 @@ jobs:
         # A coverage test badge
         anybadge --value=$COVPERCENT --file=badges/coverage.svg coverage
         # A version badge
-        PIPVER=`pip show sparc-dft-api | grep Version | cut -d ' ' -f2`
-        anybadge --value=$PIPVER --file=badges/package.svg -l sparc-dft-api
+        PIPVER=`pip show sparc-x-api | grep Version | cut -d ' ' -f2`
+        anybadge --value=$PIPVER --file=badges/package.svg -l sparc-x-api
     - name: Manually add git badges
       run: |
         # Assuming a badges branch already exists!

diff --git a/.gitignore b/.gitignore
@@ -771,3 +771,5 @@ ex0-*/
 al-eos-sparc.traj
 */ex1-sparc/
 examples/ex1-ase/
+/SPARC-master/
+/master.zip
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
-# `sparc-dft-api`: A Python API for the SPARC DFT Code
+# `SPARC-X-API`: A Python API for the SPARC-X DFT Code
 [![Package](https://raw.githubusercontent.com/alchem0x2A/sparc-dft-api/badges/badges/package.svg)](https://raw.githubusercontent.com/alchem0x2A/sparc-dft-api/badges/badges/package.svg)
 [![Coverage](https://raw.githubusercontent.com/alchem0x2A/sparc-dft-api/badges/badges/coverage.svg)](https://raw.githubusercontent.com/alchem0x2A/sparc-dft-api/badges/badges/coverage.svg)
 [![Unit tests](https://github.com/alchem0x2A/sparc-dft-api/actions/workflows/installation_test.yml/badge.svg)](https://github.com/alchem0x2A/sparc-dft-api/actions/workflows/installation_test.yml)
 
-`sparc-dft-api` is an [ASE](https://wiki.fysik.dtu.dk/ase/)-compatible Python API for the density functional theory (DFT) code [SPARC](https://github.com/SPARC-X/SPARC). It offers:
+`SPARC-X-API` is an [ASE](https://wiki.fysik.dtu.dk/ase/)-compatible Python API for the density functional theory (DFT) code [SPARC](https://github.com/SPARC-X/SPARC). It offers:
 
 1. ASE-compatible I/O format for SPARC files
 2. A JSON API interfacing with SPARC's C-code for parameter validation and conversion
@@ -23,7 +23,7 @@ which includes the pseudopotential files:
 # Change 'sparc-env' to your desired name if needed
 conda create -n sparc-env
 conda activate sparc-env
-conda install -c alchem0x2a sparc-dft-api
+conda install -c alchem0x2a sparc-x-api
 ```
 
 On Linux platforms (x86_64, aarch64), you can also install the
@@ -34,13 +34,13 @@ conda install -c alchem0x2a sparc
 conda activate sparc-env   # Re-activate to have the env variables effective
 ```
 
-*Note: Packaging of sparc-dft-api on conda-forge is in progress.*
+*Note: Packaging of SPARC-X-API on conda-forge is in progress.*
 
 ### 2. Manual installation from source with `pip`
 
 
 ```bash
-python -m pip install git+https://github.com/SPARC-X/sparc-dft-api
+python -m pip install git+https://github.com/SPARC-X/SPARC-X-API
 ```
 
 Optionally, you can download the latest SPMS pseudopotentials and unpacks the pseudopotential files into `<python-lib-root>/site-packages/sparc/psp`:
@@ -64,7 +64,7 @@ python -m sparc.quicktest
 
 A proper setup will display the following sections at the output's conclusion:
 
-<img width="500" alt="image" src="https://github.com/alchem0x2A/sparc-dft-api/assets/6829706/95cb712e-4c77-4b14-8130-4961e3c50278">
+<img width="500" alt="image" src="https://github.com/alchem0x2A/SPARC-X-API/assets/6829706/95cb712e-4c77-4b14-8130-4961e3c50278">
 
 For using the API to parse SPARC input and output files, it's
 essential that the "Import" and "JSON API" tests are successful. For
@@ -76,7 +76,7 @@ configuring the environment variables. If you run into further problems, consult
 [Trouble Shooting](doc/troubleshooting.md).
 
 ## Setting up the environment
-`sparc-dft-api` is designed to automate the discovery of
+`SPARC-X-API` is designed to automate the discovery of
 pseudopotential files, the JSON API, and the SPARC binary. However,
 you can exert fine-grained control over their setup:
 
@@ -87,7 +87,7 @@ order:
 1) Via the `psp_dir` argument passed to the `sparc.SPARC` calculator.
 2) Through the environment variables `$SPARC_PSP_PATH` or `$SPARC_PP_PATH` (this is the
  method employed by [`conda` installation](#1-via-anaconda-or-miniconda-recommended)).
-3) By using `psp8` files bundled with the sparc-dft-api installation (see the
+3) By using `psp8` files bundled with the SPARC-X-API installation (see the
 [manual installation](#2-manual-installation-from-source-with-pip)).
 
 To specify a custom path for your psp8 files, set the `$SPARC_PSP_PATH` or `$SPARC_PP_PATH` variable as follows:
@@ -101,7 +101,7 @@ python -c "from sparc.common import psp_dir; print(psp_dir)"
 ```
 
 ### B) JSON schema
-`sparc-dft-api` is engineered for compatibility with the SPARC
+`SPARC-X-API` is engineered for compatibility with the SPARC
 C-code. It achieves this by loading a JSON schema for
 parameter validation and unit conversion. You can review the default
 schema used by the API at sparc.sparc_json_api.default_json_api
@@ -121,7 +121,7 @@ schema used by the API at sparc.sparc_json_api.default_json_api
 ```
 
 The schema file is generated from SPARC's LaTeX documentation.  In
-upcoming releases of `sparc-dft-api`, we're aiming to provide users
+upcoming releases of `SPARC-X-API`, we're aiming to provide users
 the flexibility to use their own custom schema files. This would be
 particularly useful for those who might be testing a development
 branch of SPARC.
@@ -132,7 +132,7 @@ The command to execute SPARC calculations is determined based on the following p
 
 1) The command argument provided directly to the `sparc.SPARC` calculator.
 2) The environment variable `$ASE_SPARC_COMMAND`
-3) If neither of the above is defined, `sparc-dft-api` looks for the SPARC binary under current `$PATH` and combine with the suitable `mpi` command prefix.
+3) If neither of the above is defined, `SPARC-X-API` looks for the SPARC binary under current `$PATH` and combine with the suitable `mpi` command prefix.
 
 Example:
 ```bash
@@ -146,7 +146,7 @@ export ASE_SPARC_COMMAND="mpirun -n 8 /path/to/sparc -name PREFIX"
 ### 1. Read / write SPARC files
 
 In contrast to many other DFT codes, where the ASE I/O formats refer
-to a single file, `sparc-dft-api` operates on the whole calculation
+to a single file, `SPARC-X-API` operates on the whole calculation
 directory, also known as a "SPARC bundle". This API integrates
 seamlessly with ASE, allowing for the automatic detection of the SPARC
 file format:
@@ -177,9 +177,9 @@ For a deeper dive into the bundle I/O format, see [Advanced Topics](doc/advanced
 A recurring challenge of Python interfaces to DFT codes it the
 inconsistencies between low-level codes (Fortran/C/C++) and outdated
 upper-level APIs regarding parameter sets and default values. To
-address this issue, `sparc-dft-api` handles DFT parameters through a
+address this issue, `SPARC-X-API` handles DFT parameters through a
 JSON schema translated from SPARC's LaTeX documentation.  Each release
-of `sparc-dft-api` is linked with a specific version of the SPARC
+of `SPARC-X-API` is linked with a specific version of the SPARC
 source code, ensuring compatibility and consistency with the default
 parameter set. The main driver of this feature is the
 `sparc.api.SparcAPI` class.
@@ -198,7 +198,7 @@ Topics](doc/advanced_topics.md).
 
 ### 3. Calculator interface
 
-`sparc-dft-api` offers a calculator interface that aligns with many
+`SPARC-X-API` offers a calculator interface that aligns with many
 other ASE calculators.  If you've worked with ASE modules like `Vasp`,
 `QuantumEspresso`, or `GPAW`, you'll find this package intuitive,
 as shown in the following examples:
@@ -252,7 +252,7 @@ If you want to extract more information about the MD simulation steps, take a lo
 
 4. Geometric optimization using ASE's optimizers
 
-The power of `sparc-dft-api` is to combine single point `SPARC` calculations with advanced ASE optimizers, such as BFGS, FIRE or GPMin. Example 2 can be re-written as:
+The power of `SPARC-X-API` is to combine single point `SPARC` calculations with advanced ASE optimizers, such as BFGS, FIRE or GPMin. Example 2 can be re-written as:
 
 ```python
 from sparc.calculator import SPARC
@@ -267,7 +267,7 @@ opt.run(fmax=0.02)
 
 ### 4. Command-line tools
 
-`sparc-dft-api` provides a simple command wrapper `sparc-ase` to add
+`SPARC-X-API` provides a simple command wrapper `sparc-ase` to add
 support of SPARC file formats to the `ase` cli tools. Simple
 replace `ase [subcommand] [args]` with `sparc-ase [subcommand] [args]`
 to access your SPARC bundle files as you would use for other file
@@ -279,9 +279,9 @@ images.
 Below is a screenshot showing the usage of `sparc-ase gui` to visualize a
 short [MD trajectory](tests/outputs/NH3_sort_lbfgs_opt.sparc).
 
-<img width="1200" alt="image" src="https://github.com/alchem0x2A/sparc-dft-api/assets/6829706/e72329ff-7194-4819-94f8-486ef2218844">
+<img width="1200" alt="image" src="https://github.com/alchem0x2A/SPARC-X-API/assets/6829706/e72329ff-7194-4819-94f8-486ef2218844">
 
-### 5. Units used in `sparc-dft-api`
+### 5. Units used in `SPARC-X-API`
 
 In the SPARC DFT code, all input parameters conventionally employ atomic units, such as Hartree and Bohr. Conversely, ASE objects (like `Atoms.positions`, `Atoms.cell`, `Atoms.get_potential_energy()`) utilize eV/Angstrom units.
 
@@ -291,7 +291,63 @@ atoms.calc = SPARC(h=0.25, REFERENCE_CUTOFF=0.5, EXX_RANGE_PBE=0.16, **params)
 ```
 inputs following ASE's convention (e.g., `h`) adopt eV/Angstrom units (thus the same setting can be applied to other DFT calculators),
 On the other hand, all SPARC-specific parameters, which can often be recognized by their capitalized format (like `REFERENCE_CUTOFF`, `EXX_RANGE_PBE`), retain their original values consistent with their representation in the `.inpt` files.
-The reasoning and details about unit conversion can be found in the [Rules for Input Parameters](https://github.com/alchem0x2A/sparc-dft-api/blob/master/doc/advanced_topics.md#rules-for-input-parameters-in-sparcsparc-calculator)  in Advanced Topics.
+The reasoning and details about unit conversion can be found in the [Rules for Input Parameters](https://github.com/alchem0x2A/SPARC-X-API/blob/master/doc/advanced_topics.md#rules-for-input-parameters-in-sparcsparc-calculator)  in Advanced Topics.
+
+
+In order for `SPARC-X-API` to be compatible with other ASE-based DFT calculators,
+there is a list of special parameters consistent with the ASE convention and uses Å / eV / GPa / fs 
+unit system:
+
+| parameter name | meaning                         | example        | equivalent `SPARC` input |
+|----------------|---------------------------------|----------------|--------------------------|
+| `xc`           | Exchange-correlation functional | `xc=pbe` | `EXCHANGE_CORRELATION: GGA_PBE` |
+|                |                                 | `xc=lda` | `EXCHANGE_CORRELATION: LDA_PZ` |
+|                |                                 | `xc=rpbe` | `EXCHANGE_CORRELATION: GGA_RPBE` |
+|                |                                 | `xc=pbesol` | `EXCHANGE_CORRELATION: GGA_PBEsol` |
+|                |                                 | `xc=pbe0` | `EXCHANGE_CORRELATION: PBE0` |
+|                |                                 | `xc=hf` | `EXCHANGE_CORRELATION: HF` |
+|                |                                 | `xc=hse` or `xc=hse03` | `EXCHANGE_CORRELATION: HSE` |
+|                |                                 | `xc=vdwdf1` or `xc=vdw-df` | `EXCHANGE_CORRELATION: vdWDF1` |
+|                |                                 | `xc=vdwdf2` or `xc=vdw-df2` | `EXCHANGE_CORRELATION: vdWDF2` |
+|                |                                 | `xc=scan` | `EXCHANGE_CORRELATION: SCAN` |
+| `h`            | Real grid spacing    (Å)           | `h=0.2`        | `FD_GRID: Nx Ny Nz`  (nearest int value)         |
+| `gpts`         | Explicit grid points |   `gpts=[10, 10, 10]` | `FD_GRID: 10 10 10` |
+| `kpts`         | Kpoint mesh          |   `kpts=[3, 3, 3]`    | `KPOINT_GRID: 3 3 3` |
+| `convergence`  | Dict of convergence criteria (see below) |  | |
+|                | `energy`  eV/atom         | `convergence={"energy": 1e-4}` | `TOL_SCF: 3e-6` |
+|                | `relax` (forces)  eV/Å            | `convergence={"relax": 1e-2}` | `TOL_RELAX: 2e-4` |
+|                | `density` e/atom          | `convergence={`density`: 1e-6}`| `TOL_PSEUDOCHARGE: 1e-6` |
+
+Users from other DFT codes can easily port their ASE codes to `SPARC-X-API` using the special parameters with minimal modification:
+
+Example 1: VASP vs SPARC
+
+```python
+# Using VASP
+from ase.calculators.vasp import Vasp
+calc = Vasp(xc="rpbe", kpts=(9, 9, 9), directory="vasp-calc")
+```
+vs
+```python
+# Using SPARC
+from sparc.calculator import SPARC
+calc = SPARC(xc="rpbe", kpts=(9, 9, 9), directory="sparc-calc.sparc")
+```
+
+Example 2: GPAW (another real-space DFT code) vs SPARC
+```python
+# Using GPAW
+from gpaw import GPAW
+calc = GPAW(xc="PBE", kpts=(9, 9, 9), h=0.25, directory="vasp-calc", convergence={"energy": 1.e-4})
+```
+vs
+```python
+# Using SPARC
+from sparc.calculator import SPARC
+calc = SPARC(xc="PBE", kpts=(9, 9, 9), h=0.25, directory="sparc-calc.sparc", convergence={"energy": 1.e-4})
+```
+
+
 
 ## Troubleshooting
 Please refer to the [troubleshooting](doc/troubleshooting.md) guidelines
@@ -300,7 +356,7 @@ Please refer to the [troubleshooting](doc/troubleshooting.md) guidelines
 A detailed description about how the API works can be found [here](doc/advanced_topics.md)
 
 ## API changes
-The API changes compared to the older release ([v0.1](https://github.com/SPARC-X/sparc-dft-api/tree/eac557f214b402122a506f88f38c7a8767283503)) are summarized [here](doc/changes_v0.1.md)
+The API changes compared to the older release ([v0.1](https://github.com/SPARC-X/SPARC-X-API/tree/eac557f214b402122a506f88f38c7a8767283503)) are summarized [here](doc/changes_v0.1.md)
 
 ## How to contribute
 Please refer to our [guidelines for contributors](doc/contribution_guideline.md)
diff --git a/doc/advanced_topics.md b/doc/advanced_topics.md
@@ -93,24 +93,6 @@ old_atoms.get_potential_energy()
 ```
 
 
-### Special inputs for `sparc.SPARC` calculator
-
-The following input parameters have special meaning in `sparc.SPARC` calculator,
-they are consistent with definitions in other ASE calculators and uses Å / eV / GPa / fs 
-unit system:
-
-| parameter name | meaning                         | example        | equivalent `SPARC` input |
-|----------------|---------------------------------|----------------|--------------------------|
-| `xc`           | Exchange-correlation functional | `xc=pbe` | `EXCHANGE_CORRELATION: GGA_PBE` |
-| `h`            | Real grid spacing    (Å)           | `h=0.2`        | `FD_GRID: Nx Ny Nz`  (calculated values)         |
-| `gpts`         | Explicit grid points |   `gpts=[10, 10, 10]` | `FD_GRID: 10 10 10` |
-| `kpts`         | Kpoint mesh          |   `kpts=[3, 3, 3]`    | `KPOINT_GRID: 3 3 3` |
-| `convergence`  | Dict of convergence criteria (see below) |  | |
-|                | `energy`  eV/atom         | `convergence={"energy": 1e-4}` | `SCF_ENERGY_ACC: 3e-6` |
-|                | `forces`  eV/Å            | `convergence={"forces": 1e-2}` | `TOL_RELAX: 2e-4` |
-|                | `density` e/atom          | `convergence={`density`: 1e-6}`| `TOL_PSEUDOCHARGE: 1e-6` |
-
-*WIP*: support more advanced settings like D3, HSE and DFT+U in `xc` settings
 
 ### Rules for input parameters in `sparc.SPARC` calculator
 

diff --git a/doc/changes_v0.1.md b/doc/changes_v0.1.md
@@ -1,20 +1,20 @@
 ## Major changes from `sparc-dft-api` [v0.1](https://github.com/SPARC-X/sparc-dft-api/tree/eac557f214b402122a506f88f38c7a8767283503)
 
-`sparc-dft-api` has been heavily refactored in v0.2. If you're using legacy Python codes
+`sparc-dft-api` has been heavily refactored in v1.0. If you're using legacy Python codes
 that are written under v0.1 API, there are a few major changes that require your attention:
 
 1. Support for single `.ion` file format is deprecated. Instead, `v0.2` API treats the whole SPARC directory as a bundle format. Please use `read_sparc` and `write_sparc` methods for basic file I/O instead.
 Nevertheless, reading calculation results generated by a v0.1 API code will not be affected.
 
-2. v0.2 API uses a different mapping scheme for the sorting of ASE atoms objects (similar to `Vasp`), add a comment section in `.ion` file similar to follows:
+2. v1.0 API uses a different mapping scheme for the sorting of ASE atoms objects (similar to `Vasp`), add a comment section in `.ion` file similar to follows:
 ```python
 # ASE-SORT:
 # 3 2 1 0
 # END ASE-SORT
 ```
 which maps atoms 3, 2, 1, 0 from the SPARC .ion file order to atoms 0, 1, 2, 3 in ASE order. This is useful for systems that are constructed by ASE's `add_adsorbate` method.
 
-3. v0.2 API accepts all SPARC internal parameters (i.e. **CAPITALIZED**) in *atomic units* for consistency reason. 
+3. v1.0 API accepts all SPARC internal parameters (i.e. **CAPITALIZED**) in *atomic units* for consistency reason. 
 However, we also keep a list of "special input params" that are conventionally used in other ASE calculators, that use Å / eV / GPa / fs unit system.
 
 4. Defining `LATVEC`, `LATVEC_SCALE`, or `CELL` via the calculator parameters is no longer encouraged. Instead, all structure changes should be made to the `Atoms` object.
@@ -24,7 +24,7 @@ For more discussion please see [Advanced Topic] section.
 Below are a list of v0.1 method of the `SPARC` calculator and their current status in v0.2 API. 
 `calc` is an instance of `sparc.SPARC`.
 
-|  old methods           | status in v0.2 API |     alternatives                   |
+|  old methods           | status in v1.0 API |     alternatives                   |
 |------------------------|--------------------|------------------------------------|
 | `interpret_grid_input` | <span style="color:red">deprecated</span>         | `calc.set(fd_grid=[20, 20, 20])`   |
 | `interpret_kpoint_input` | <span style="color:red">deprecated</span>         | `calc.set(kpts=[3, 3, 3])`   |
@@ -47,4 +47,4 @@ Below are a list of v0.1 method of the `SPARC` calculator and their current stat
 | `parse_input_args` | <span style="color:red">deprecated</span> | `calc.set(**kwargs)` |
 | `recover_index_order_from_ion_file` | <span style="color:red">deprecated</span> | Use `calc.sort` and `calc.resort` |
 | `atoms_dict` | <span style="color:red">deprecated</span> | Use third party library like `bson` |
-| `dict_atoms` | <span style="color:red">deprecated</span> | Use third party library like `bson` |
+| `dict_atoms` | <span style="color:red">deprecated</span> | Use third party library like `bson` |
diff --git a/examples/ex0-eos.py b/examples/ex0-eos.py
@@ -15,9 +15,7 @@ def main():
     calc = SPARC(h=0.25, kpts=(3, 3, 3), xc="pbe", directory="ex0-eos")
     vol = atoms.get_volume()
     atoms.calc = calc
-    eos = calculate_eos(
-        atoms, npoints=5, eps=0.05, trajectory="al-eos-sparc.traj"
-    )
+    eos = calculate_eos(atoms, npoints=5, eps=0.05, trajectory="al-eos-sparc.traj")
     print("Original volume: Ang^3", vol)
     v, e, B = eos.fit()
     print("Fitted volume (Ang^3), energy (eV), modulus (eV/Ang^3)")

diff --git a/examples/ex1-ase-optimize.py b/examples/ex1-ase-optimize.py
@@ -50,7 +50,7 @@ def optimize_ase_lbfgs():
     )
     atoms.calc = calc
     opt = BFGS(atoms)
-    #breakpoint()
+    # breakpoint()
     opt.run(fmax=0.02)
     e_fin = atoms.get_potential_energy()
     f_fin = atoms.get_forces()