diff --git a/docs/databases.md b/docs/databases.md
index 07e90fb5..a41b295b 100644
--- a/docs/databases.md
+++ b/docs/databases.md
@@ -1,170 +1,180 @@
# Databases
-## [FigShare](https://figshare.com/authors/Kamal_Choudhary/4445539) based databases
-
-[![Open in Colab]](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Analyzing_data_in_the_JARVIS_DFT_dataset.ipynb)
-[![Open in SLMat]](https://deepmaterials.github.io/slmat/lab?fromURL=https://raw.githubusercontent.com/deepmaterials/slmat/main/content/Database_analysis.ipynb)
-
-### JARVIS databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------------------------------------------------|
-| [`dft_3d`](https://doi.org/10.6084/m9.figshare.6815699) | 75993 | Various 3D materials properties in JARVIS-DFT database computed with OptB88vdW and TBmBJ methods |
-| [`dft_2d`](https://doi.org/10.6084/m9.figshare.6815705) | 1109 | Various 2D materials properties in JARVIS-DFT database computed with OptB88vdW |
-| [`dft_3d_2021`](https://doi.org/10.6084/m9.figshare.6815699) | 55723 | Various 3D materials properties in JARVIS-DFT database computed with OptB88vdW and TBmBJ methods (2021 version) |
-| [`dft_2d_2021`](https://doi.org/10.6084/m9.figshare.6815705) | 1079 | Various 2D materials properties in JARVIS-DFT database computed with OptB88vdW (2021 version) |
-| [`cfid_3d`](https://doi.org/10.6084/m9.figshare.6815699) | 55723 | Various 3D materials properties in JARVIS-DFT database computed with OptB88vdW and TBmBJ methods with CFID |
-| [`jff`](https://doi.org/10.6084/m9.figshare.14213522) | 2538 | Various 3D materials properties in JARVIS-FF database computed with several force-fields |
-| [`alignn_ff_db`](https://doi.org/10.6084/m9.figshare.21667874) | 307113 | Energy per atom, forces and stresses for ALIGNN-FF training for 75k materials |
-| [`edos_pdos`](https://doi.org/10.6084/m9.figshare.14745327) | 48469 | Normalized electron and phonon density of states with interpolated values and fixed number of bins |
-| [`qe_tb`](https://doi.org/10.6084/m9.figshare.15127788) | 829574 | Various 3D materials properties in JARVIS-QETB database |
-| [`supercon_3d`](https://doi.org/10.6084/m9.figshare.21370572) | 1058 | 3D superconductor DFT dataset |
-| [`supercon_2d`](https://doi.org/10.6084/m9.figshare.21370572) | 161 | 2D superconductor DFT dataset |
-| [`vacancydb`](https://doi.org/10.6084/m9.figshare.23000573) | 464 | Vacancy formation energy dataset |
-| [`surfacedb`](https://doi.org/10.6084/m9.figshare.25832614) | 607 | Surface property dataset |
-| [`interfacedb`](https://doi.org/10.6084/m9.figshare.25832614) | 593 | Interface property dataset |
-| [`ramandb`](https://doi.org/10.6084/m9.figshare.29458907) | 5000 | Raman spectra dataset |
-| [`raw_files`](https://doi.org/10.6084/m9.figshare.13154159) | 144895 | Figshare links to download raw calculations VASP files from JARVIS-DFT |
-| `stm` | 1132 | 2D materials STM images in JARVIS-STM database |
-| `wtbh_electron` | 1440 | 3D and 2D materials Wannier tight-binding Hamiltonian database for electrons with spin-orbit coupling in JARVIS-WTB (Keyword: 'WANN') |
-| `wtbh_phonon` | 15502 | 3D and 2D materials Wannier tight-binding Hamiltonian for phonons at Gamma with finite difference (Keyword: FD-ELAST) |
-
-### Alexandria databases
-
-| Database name | Number of data-points | Description |
-|----------------------|-----------------------|----------------------------------------------------------------|
-| [`alex_pbe_hull`](https://doi.org/10.6084/m9.figshare.27174897) | 116k | Alexandria DB convex hull stable materials with PBE functional |
-| [`alex_pbe_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 5 million | Alexandria DB all 3D materials with PBE |
-| [`alex_pbe_2d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 200k | Alexandria DB all 2D materials with PBE |
-| [`alex_pbe_1d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 100k | Alexandria DB all 1D materials with PBE |
-| [`alex_scan_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 500k | Alexandria DB all 3D materials with SCAN |
-| [`alex_pbesol_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 500k | Alexandria DB all 3D materials with PBEsol |
-| [`alex_supercon`](https://doi.org/10.6084/m9.figshare.27174897) | 8253 | Alexandria superconductor database |
-
-### RRUFF databases
-
-| Database name | Number of data-points | Description |
-|------------------------|-----------------------|------------------------------|
-| [`rruff_powder_xrd`](https://doi.org/10.6084/m9.figshare.31817977) | 1362 | RRUFF powder XRD dataset |
-| [`rruff_raman_excellent`](https://doi.org/10.6084/m9.figshare.31817977)| 7688 | RRUFF Raman spectra dataset |
-| [`rruff_ir`](https://doi.org/10.6084/m9.figshare.31817977) | 824 | RRUFF IR spectra dataset |
-
-### Materials Project databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------------------------------------------------|
-| `mp_3d_2020` | 127k | CFID descriptors for materials project (2020) |
-| [`mp_3d`](https://doi.org/10.6084/m9.figshare.13054247) | 84k | CFID descriptors for 84k materials project |
-| [`megnet`](https://doi.org/10.6084/m9.figshare.14177630) | 69239 | Formation energy and bandgaps of 3D materials properties in Materials project database as on 2018, used in megnet |
-| [`megnet2`](https://doi.org/10.6084/m9.figshare.14745435) | 133k | 133k materials and their formation energy in MP |
-| [`m3gnet_mpf`](https://doi.org/10.6084/m9.figshare.23267852) | 168k | 168k structures and their energy, forces and stresses in MP |
-| [`m3gnet_mpf_1.5mil`](https://doi.org/10.6084/m9.figshare.23267852) | 1.5 million | 1.5 million structures and their energy, forces and stresses in MP |
-
-### OQMD databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| [`oqmd_3d`](https://doi.org/10.6084/m9.figshare.13055333) | 460k | CFID descriptors for 460k materials in OQMD |
-| [`oqmd_3d_no_cfid`](https://doi.org/10.6084/m9.figshare.14206169) | 817636 | Formation energies and bandgaps of 3D materials from OQMD database |
-
-### Open Catalyst databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| [`ocp_all`](https://doi.org/10.6084/m9.figshare.23250629) | 510214 | Open Catalyst 460328 training, rest validation and test dataset |
-| [`ocp100k`](https://doi.org/10.6084/m9.figshare.23206193) | 149886 | Open Catalyst 100000 training, rest validation and test dataset |
-| [`ocp10k`](https://doi.org/10.6084/m9.figshare.22817633) | 59886 | Open Catalyst 10000 training, rest validation and test dataset |
-
-### Catalyst databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| [`AGRA_O`](https://doi.org/10.6084/m9.figshare.23909478) | 1000 | AGRA Oxygen catalyst dataset |
-| [`AGRA_OH`](https://doi.org/10.6084/m9.figshare.23909478) | 875 | AGRA OH catalyst dataset |
-| [`AGRA_COOH`](https://doi.org/10.6084/m9.figshare.23909478) | 280 | AGRA COOH catalyst dataset |
-| [`AGRA_CHO`](https://doi.org/10.6084/m9.figshare.23909478) | 214 | AGRA CHO catalyst dataset |
-| [`AGRA_CO`](https://doi.org/10.6084/m9.figshare.23909478) | 193 | AGRA CO catalyst dataset |
-| [`tinnet_N`](https://doi.org/10.6084/m9.figshare.23225687) | 329 | TinNet Nitrogen catalyst dataset |
-| [`tinnet_O`](https://doi.org/10.6084/m9.figshare.23254151) | 747 | TinNet Oxygen catalyst dataset |
-| [`tinnet_OH`](https://doi.org/10.6084/m9.figshare.23254154) | 748 | TinNet OH group catalyst dataset |
-
-### QM9 and molecular databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| `qm9_std_jctc` | 130829 | Various properties of molecules in QM9 database (standardized) |
-| [`qm9_dgl`](https://doi.org/10.6084/m9.figshare.14827584) | 130829 | Various properties of molecules in QM9 dgl database |
-| `qm9` | 134k | Various properties of molecules in QM9 database with CFID |
-| `hopv` | 4855 | Various properties of molecules in HOPV15 dataset |
-| [`pdbbind`](https://doi.org/10.6084/m9.figshare.14812038) | 11189 | Bio-molecular complexes database from PDBBind v2015 |
-| `pdbbind_core` | 195 | Bio-molecular complexes database from PDBBind core |
-| [`cccbdb`](https://doi.org/10.6084/m9.figshare.26117998) | 1333 | NIST CCCBDB computational chemistry dataset |
-
-### MOF databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| [`qmof`](https://doi.org/10.6084/m9.figshare.14812044) | 20425 | Bandgaps and total energies of metal organic frameworks in QMOF database |
-| [`hmof`](https://doi.org/10.6084/m9.figshare.15127758) | 137651 | Hypothetical MOF database |
-
-### 2D materials databases (external)
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| `c2db` | 3514 | Various properties in C2DB database |
-| [`twod_matpd`](https://doi.org/10.6084/m9.figshare.14205083) | 6351 | Formation energy and bandgaps of 2D materials properties in 2DMatPedia database |
-| [`mxene275`](https://doi.org/10.6084/m9.figshare.23531523) | 275 | MXene dataset |
-
-### Other materials databases
-
-| Database name | Number of data-points | Description |
-|-----------------------------|-----------------------|----------------------------------------------------------------|
-| [`aflow2`](https://doi.org/10.6084/m9.figshare.13215308) | 400k | AFLOW dataset |
-| [`cod`](https://doi.org/10.6084/m9.figshare.14912820.v1) | 431778 | Atomic structures from crystallographic open database |
-| [`cod_200`](https://doi.org/10.6084/m9.figshare.14912820.v1) | 237k | Atomic structures from crystallographic open database (2025) |
-| [`snumat`](https://doi.org/10.6084/m9.figshare.21713885) | 10481 | Bandgaps with hybrid functional |
-| [`polymer_genome`](https://doi.org/10.6084/m9.figshare.14213603) | 1073 | Electronic bandgap and dielectric constants of crystalline polymers in polymer genome database |
-| [`omdb`](https://doi.org/10.6084/m9.figshare.14812050) | 12500 | Bandgaps for organic polymers in OMDB database |
-| [`halide_peroskites`](https://doi.org/10.6084/m9.figshare.25256236) | 229 | Halide perovskite dataset |
-| [`supercon_chem`](https://doi.org/10.6084/m9.figshare.22975787) | 16414 | Superconductor chemical formula dataset |
-| [`mag2d_chem`](https://doi.org/10.6084/m9.figshare.22976285) | 226 | Magnetic 2D materials chemical formula dataset |
-| [`ssub`](https://doi.org/10.6084/m9.figshare.22583677) | 1726 | SSUB formation energy for chemical formula dataset |
-| [`mlearn`](https://doi.org/10.6084/m9.figshare.22721047) | 1730 | Machine learning force-field for elements datasets |
-| [`foundry_ml_exp_bandgaps`](https://doi.org/10.6084/m9.figshare.22814318) | 2069 | Foundry ML experimental bandgaps dataset |
-
-### Text and NLP databases
-
-| Database name | Number of data-points | Description |
-|-------------------|-----------------------|----------------------------------------------------------------|
-| [`arXiv`](https://doi.org/10.6084/m9.figshare.14211860) | 1796911 | arXiv dataset 1.8 million title, abstract and id dataset |
-| [`arxiv_summary`](https://doi.org/10.6084/m9.figshare.22817651) | 137927 | arXiv summary dataset (cond-mat) |
-| [`cord19`](https://doi.org/10.6084/m9.figshare.14211857) | 223k | CORD-19 COVID-19 research articles dataset |
-
-
-All these datasets can be obtained using jarvis-tools as follows,
-exception to `stm`, `wtbh_electron`, `wtbh_phonon` which have their own
-modules in `jarvis.db.figshare`:
-
-``` python
+JARVIS-Tools provides one-line access to a large collection of curated
+materials datasets — JARVIS-DFT, JARVIS-FF, JARVIS-ML, and mirrors of
+external sets such as Materials Project, OQMD, AFLOW, Alexandria, the
+Open Catalyst Project, QM9, and others. Most are hosted on Figshare and
+fetched lazily into a local cache the first time they are requested.
+
+[](https://colab.research.google.com/github/knc6/jarvis-tools-notebooks/blob/master/jarvis-tools-notebooks/Analyzing_data_in_the_JARVIS_DFT_dataset.ipynb)
+[](https://deepmaterials.github.io/slmat/lab?fromURL=https://raw.githubusercontent.com/deepmaterials/slmat/main/content/Database_analysis.ipynb)
+
+## Quickstart
+
+Every dataset listed below — except `stm`, `wtbh_electron`, and
+`wtbh_phonon`, which have dedicated helpers in `jarvis.db.figshare` —
+can be loaded with the same call:
+
+```python
from jarvis.db.figshare import data
-d = data('dft_3d') #choose a name of dataset from above
-# See available keys
-print (d[0].keys())
-# Dataset size
-print(len(d))
-# Visualize an atoms object
+d = data("dft_3d") # pick any dataset name from the tables below
+print(len(d)) # number of records
+print(d[0].keys()) # available fields per record
+```
+
+Each record is a plain Python dict. Atomic structures are stored under
+the `"atoms"` key as a serialized `Atoms` dict:
+
+```python
from jarvis.core.atoms import Atoms
-a = Atoms.from_dict(d[0]['atoms'])
-#You can visualize this in VESTA or other similar packages
-print(a)
-# If pandas framework needed
+a = Atoms.from_dict(d[0]["atoms"])
+print(a) # POSCAR-style printout, viewable in VESTA
+```
+
+Convert any dataset into a pandas `DataFrame` for filtering and joins:
+
+```python
import pandas as pd
+
df = pd.DataFrame(d)
-print(df)
+df.head()
```
-[Open in SLMat]: https://img.shields.io/badge/Open-SLMat-blue
-
-[Open in Colab]: https://colab.research.google.com/assets/colab-badge.svg
+---
+
+## JARVIS databases
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`dft_3d`](https://doi.org/10.6084/m9.figshare.6815699) | 75,993 | 3D materials in JARVIS-DFT, OptB88vdW + TBmBJ |
+| [`dft_2d`](https://doi.org/10.6084/m9.figshare.6815705) | 1,109 | 2D materials in JARVIS-DFT, OptB88vdW |
+| [`dft_3d_2021`](https://doi.org/10.6084/m9.figshare.6815699) | 55,723 | 3D materials, 2021 snapshot |
+| [`dft_2d_2021`](https://doi.org/10.6084/m9.figshare.6815705) | 1,079 | 2D materials, 2021 snapshot |
+| [`cfid_3d`](https://doi.org/10.6084/m9.figshare.6815699) | 55,723 | JARVIS-DFT 3D + CFID descriptors |
+| [`jff`](https://doi.org/10.6084/m9.figshare.14213522) | 2,538 | JARVIS-FF: classical force-field properties |
+| [`alignn_ff_db`](https://doi.org/10.6084/m9.figshare.21667874) | 307,113 | ALIGNN-FF training set: energies, forces, stresses |
+| [`edos_pdos`](https://doi.org/10.6084/m9.figshare.14745327) | 48,469 | Normalized electron + phonon DOS, fixed-bin |
+| [`qe_tb`](https://doi.org/10.6084/m9.figshare.15127788) | 829,574 | JARVIS-QETB three-body tight-binding properties |
+| [`supercon_3d`](https://doi.org/10.6084/m9.figshare.21370572) | 1,058 | 3D superconductor DFT dataset |
+| [`supercon_2d`](https://doi.org/10.6084/m9.figshare.21370572) | 161 | 2D superconductor DFT dataset |
+| [`vacancydb`](https://doi.org/10.6084/m9.figshare.23000573) | 464 | Vacancy formation energies |
+| [`surfacedb`](https://doi.org/10.6084/m9.figshare.25832614) | 607 | Surface properties |
+| [`interfacedb`](https://doi.org/10.6084/m9.figshare.25832614) | 593 | Interface properties |
+| [`ramandb`](https://doi.org/10.6084/m9.figshare.29458907) | 5,000 | Raman spectra |
+| [`raw_files`](https://doi.org/10.6084/m9.figshare.13154159) | 144,895 | Figshare links to raw VASP outputs for JARVIS-DFT |
+| `stm` | 1,132 | 2D-material STM images (JARVIS-STM) |
+| `wtbh_electron` | 1,440 | Wannier tight-binding Hamiltonians, electrons + SOC (keyword `WANN`) |
+| `wtbh_phonon` | 15,502 | Wannier tight-binding Hamiltonians, phonons at Γ (keyword `FD-ELAST`) |
+
+## Alexandria
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`alex_pbe_hull`](https://doi.org/10.6084/m9.figshare.27174897) | 116k | Convex-hull-stable materials, PBE |
+| [`alex_pbe_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 5M | All 3D materials, PBE |
+| [`alex_pbe_2d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 200k | All 2D materials, PBE |
+| [`alex_pbe_1d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 100k | All 1D materials, PBE |
+| [`alex_scan_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 500k | All 3D materials, SCAN |
+| [`alex_pbesol_3d_all`](https://doi.org/10.6084/m9.figshare.27174897) | 500k | All 3D materials, PBEsol |
+| [`alex_supercon`](https://doi.org/10.6084/m9.figshare.27174897) | 8,253 | Superconductor subset |
+
+## RRUFF (experimental spectra)
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`rruff_powder_xrd`](https://doi.org/10.6084/m9.figshare.31817977) | 1,362 | Powder XRD |
+| [`rruff_raman_excellent`](https://doi.org/10.6084/m9.figshare.31817977) | 7,688 | Raman spectra (excellent-quality subset) |
+| [`rruff_ir`](https://doi.org/10.6084/m9.figshare.31817977) | 824 | IR spectra |
+
+## Materials Project mirrors
+
+| Name | Records | Description |
+|------|---------|-------------|
+| `mp_3d_2020` | 127k | CFID descriptors for MP (2020 snapshot) |
+| [`mp_3d`](https://doi.org/10.6084/m9.figshare.13054247) | 84k | CFID descriptors for 84k MP entries |
+| [`megnet`](https://doi.org/10.6084/m9.figshare.14177630) | 69,239 | Formation energies and band gaps (MEGNet 2018) |
+| [`megnet2`](https://doi.org/10.6084/m9.figshare.14745435) | 133k | 133k MP entries with formation energies |
+| [`m3gnet_mpf`](https://doi.org/10.6084/m9.figshare.23267852) | 168k | Energies, forces, stresses (M3GNet) |
+| [`m3gnet_mpf_1.5mil`](https://doi.org/10.6084/m9.figshare.23267852) | 1.5M | Extended M3GNet training set |
+
+## OQMD
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`oqmd_3d`](https://doi.org/10.6084/m9.figshare.13055333) | 460k | CFID descriptors for OQMD |
+| [`oqmd_3d_no_cfid`](https://doi.org/10.6084/m9.figshare.14206169) | 817,636 | Formation energies and band gaps |
+
+## Open Catalyst Project
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`ocp_all`](https://doi.org/10.6084/m9.figshare.23250629) | 510,214 | Train (460,328) + val + test |
+| [`ocp100k`](https://doi.org/10.6084/m9.figshare.23206193) | 149,886 | Train (100k) + val + test |
+| [`ocp10k`](https://doi.org/10.6084/m9.figshare.22817633) | 59,886 | Train (10k) + val + test |
+
+## Catalyst (AGRA, TinNet)
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`AGRA_O`](https://doi.org/10.6084/m9.figshare.23909478) | 1,000 | AGRA O catalysts |
+| [`AGRA_OH`](https://doi.org/10.6084/m9.figshare.23909478) | 875 | AGRA OH catalysts |
+| [`AGRA_COOH`](https://doi.org/10.6084/m9.figshare.23909478) | 280 | AGRA COOH catalysts |
+| [`AGRA_CHO`](https://doi.org/10.6084/m9.figshare.23909478) | 214 | AGRA CHO catalysts |
+| [`AGRA_CO`](https://doi.org/10.6084/m9.figshare.23909478) | 193 | AGRA CO catalysts |
+| [`tinnet_N`](https://doi.org/10.6084/m9.figshare.23225687) | 329 | TinNet N catalysts |
+| [`tinnet_O`](https://doi.org/10.6084/m9.figshare.23254151) | 747 | TinNet O catalysts |
+| [`tinnet_OH`](https://doi.org/10.6084/m9.figshare.23254154) | 748 | TinNet OH catalysts |
+
+## QM9 and molecular
+
+| Name | Records | Description |
+|------|---------|-------------|
+| `qm9_std_jctc` | 130,829 | QM9 (standardized) |
+| [`qm9_dgl`](https://doi.org/10.6084/m9.figshare.14827584) | 130,829 | QM9 prepared for DGL |
+| `qm9` | 134k | QM9 + CFID descriptors |
+| `hopv` | 4,855 | HOPV15 photovoltaic molecules |
+| [`pdbbind`](https://doi.org/10.6084/m9.figshare.14812038) | 11,189 | Bio-molecular complexes (PDBBind v2015) |
+| `pdbbind_core` | 195 | PDBBind core set |
+| [`cccbdb`](https://doi.org/10.6084/m9.figshare.26117998) | 1,333 | NIST CCCBDB computational chemistry data |
+
+## MOFs
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`qmof`](https://doi.org/10.6084/m9.figshare.14812044) | 20,425 | QMOF band gaps and total energies |
+| [`hmof`](https://doi.org/10.6084/m9.figshare.15127758) | 137,651 | Hypothetical MOFs |
+
+## 2D materials (external)
+
+| Name | Records | Description |
+|------|---------|-------------|
+| `c2db` | 3,514 | C2DB properties |
+| [`twod_matpd`](https://doi.org/10.6084/m9.figshare.14205083) | 6,351 | 2DMatPedia formation energies + band gaps |
+| [`mxene275`](https://doi.org/10.6084/m9.figshare.23531523) | 275 | MXenes |
+
+## Other
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`aflow2`](https://doi.org/10.6084/m9.figshare.13215308) | 400k | AFLOW |
+| [`cod`](https://doi.org/10.6084/m9.figshare.14912820.v1) | 431,778 | Crystallography Open Database |
+| [`cod_200`](https://doi.org/10.6084/m9.figshare.14912820.v1) | 237k | COD (2025 snapshot) |
+| [`snumat`](https://doi.org/10.6084/m9.figshare.21713885) | 10,481 | Hybrid-functional band gaps |
+| [`polymer_genome`](https://doi.org/10.6084/m9.figshare.14213603) | 1,073 | Crystalline polymer band gaps + dielectric constants |
+| [`omdb`](https://doi.org/10.6084/m9.figshare.14812050) | 12,500 | OMDB organic-polymer band gaps |
+| [`halide_peroskites`](https://doi.org/10.6084/m9.figshare.25256236) | 229 | Halide perovskites |
+| [`supercon_chem`](https://doi.org/10.6084/m9.figshare.22975787) | 16,414 | Superconductor chemical formulae |
+| [`mag2d_chem`](https://doi.org/10.6084/m9.figshare.22976285) | 226 | Magnetic 2D-material chemical formulae |
+| [`ssub`](https://doi.org/10.6084/m9.figshare.22583677) | 1,726 | SSUB formation energies |
+| [`mlearn`](https://doi.org/10.6084/m9.figshare.22721047) | 1,730 | ML force-field per-element datasets |
+| [`foundry_ml_exp_bandgaps`](https://doi.org/10.6084/m9.figshare.22814318) | 2,069 | Experimental band gaps via Foundry-ML |
+
+## Text and NLP
+
+| Name | Records | Description |
+|------|---------|-------------|
+| [`arXiv`](https://doi.org/10.6084/m9.figshare.14211860) | 1,796,911 | arXiv title + abstract + ID |
+| [`arxiv_summary`](https://doi.org/10.6084/m9.figshare.22817651) | 137,927 | arXiv summaries (cond-mat) |
+| [`cord19`](https://doi.org/10.6084/m9.figshare.14211857) | 223k | CORD-19 COVID-19 research articles |
diff --git a/docs/index.md b/docs/index.md
index de5361c4..27d72386 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,409 +1,218 @@
-# Table of Contents
-* [Introduction](#intro)
-* [Documentation](#doc)
-* [Capabilities](#cap)
-* [Installation](#install)
-* [Example function](#example)
-* [Citation](#cite)
-* [References](#refs)
-* [How to contribute](#contrib)
-* [Correspondence](#corres)
-* [Funding support](#fund)
-* [Code of conduct](#conduct)
-* [Module structure](#module)
-
-
-# JARVIS-Tools (Introduction)
-
-The JARVIS-Tools is an open-access software package for atomistic
-data-driven materials design. JARVIS-Tools can be used for a) setting up
-calculations, b) analysis and informatics, c) plotting, d) database
-development and e) web-page development.
-
-JARVIS-Tools empowers NIST-JARVIS (Joint Automated Repository for
-Various Integrated Simulations) repository which is an integrated
-framework for computational science using density functional theory,
-classical force-field/molecular dynamics and machine-learning. The
-NIST-JARVIS official website is: . This
-project is a part of the Materials Genome Initiative (MGI) at NIST
-().
-
-For more details, checkout our latest articles: [The joint automated
-repository for various integrated simulations (JARVIS) for data-driven
-materials design](https://www.nature.com/articles/s41524-020-00440-1), [Recent progress in the JARVIS infrastructure for next-generation data-driven materials design](https://pubs.aip.org/aip/apr/article/10/4/041302/2917416), [other publications](https://scholar.google.com/citations?user=3w6ej94AAAAJ) and [YouTube
-videos](https://www.youtube.com/watch?v=P0ZcHXOC6W0&feature=emb_title&ab_channel=JARVIS-repository)
-
+# JARVIS-Tools
+
+[](https://pypi.org/project/jarvis-tools/)
+[](https://anaconda.org/conda-forge/jarvis-tools)
+[](https://github.com/atomgptlab/jarvis-tools)
+[](https://github.com/atomgptlab/jarvis-tools)
+[](https://github.com/atomgptlab/jarvis-tools)
+[](https://codecov.io/gh/knc6/jarvis)
+[](https://pepy.tech/badge/jarvis-tools)
+[](https://doi.org/10.5281/zenodo.3903515)
+[](https://atomgptlab.github.io/jarvis-tools/)
+[](https://github.com/atomgptlab/jarvis-tools-notebooks)
+
+JARVIS-Tools is an open-access Python package for atomistic, data-driven
+materials design. It provides building blocks for:
+
+- setting up first-principles and classical simulations,
+- analysis and informatics on the resulting data,
+- plotting and visualization,
+- building and querying materials databases,
+- powering web interfaces.
+
+It is the engine behind [NIST-JARVIS](https://jarvis.nist.gov) (Joint
+Automated Repository for Various Integrated Simulations), an integrated
+framework spanning density functional theory, classical
+force-fields/molecular dynamics, and machine learning. The project is
+part of the [Materials Genome Initiative at NIST](https://mgi.nist.gov/).
+
+For background, see the JARVIS overview papers
+([npj Comput. Mater. 2020](https://www.nature.com/articles/s41524-020-00440-1),
+[Appl. Phys. Rev. 2023](https://pubs.aip.org/aip/apr/article/10/4/041302/2917416)),
+the [full publication list](https://scholar.google.com/citations?user=3w6ej94AAAAJ),
+and the [introductory video](https://www.youtube.com/watch?v=P0ZcHXOC6W0).
- 
+
+---
-
-
-[](https://pypi.org/project/jarvis-tools/)
-[](https://anaconda.org/conda-forge/jarvis-tools)
-[](https://github.com/atomgptlab/jarvis-tools)
-[](https://ci.appveyor.com/project/knc6/jarvis-63tl9)
-[](https://github.com/atomgptlab/jarvis-tools)
-[](https://github.com/atomgptlab/jarvis-tools)
-[](https://codecov.io/gh/knc6/jarvis)
-[](https://img.shields.io/pypi/dm/jarvis-tools.svg)
-[](https://pepy.tech/badge/jarvis-tools)
-[](https://doi.org/10.5281/zenodo.3903515)
-[](https://github.com/atomgptlab/jarvis-tools)
-[](https://github.com/atomgptlab/jarvis-tools)
-[](https://figshare.com/authors/Kamal_Choudhary/4445539)
-[](https://atomgptlab.github.io/jarvis-tools/)
-[](https://github.com/atomgptlab/jarvis-tools-notebooks)
-
-
-
-------------------------------------------------------------------------
-
-
-
-
-## Documentation
-
->
-
-
## Capabilities
-- **Software workflow tasks for preprcessing, executing and
- post-processing**: VASP, Quantum Espresso, Wien2k BoltzTrap,
- Wannier90, LAMMPS, Scikit-learn, TensorFlow, LightGBM, Qiskit,
- Tequila, Pennylane, DGL, PyTorch.
-- **Several examples**: Notebooks and test scripts to explain the
- package.
-- **Several analysis tools**: Atomic structure, Electronic structure,
- Spacegroup, Diffraction, 2D materials and other vdW bonded systems,
- Mechanical, Optoelectronic, Topological, Solar-cell, Thermoelectric,
- Piezoelectric, Dielectric, STM, Phonon, Dark matter, Wannier tight
- binding models, Point defects, Heterostructures, Magnetic ordering,
- Images, Spectrum etc.
-- **Database upload and download**: Download JARVIS databases such as
- JARVIS-DFT, FF, ML, WannierTB, Solar, STM and also external
- databases such as Materials project, OQMD, AFLOW etc.
-- **Access raw input/output files**: Download input/ouput files for
- JARVIS-databases to enhance reproducibility.
-- **Train machine learning models**: Use different descriptors, graphs
- and datasets for training machine learning models.
-- **HPC clusters**: Torque/PBS and SLURM.
-- **Available datasets**: [Summary of several
- datasets](https://atomgptlab.github.io/jarvis-tools/databases/)
- .
-
+- **Simulation workflows** — pre/post-processing for VASP, Quantum
+ ESPRESSO, Wien2k, BoltzTraP, Wannier90, LAMMPS, and ML/QC frameworks
+ (scikit-learn, TensorFlow, LightGBM, PyTorch, DGL, Qiskit, Tequila,
+ PennyLane).
+- **Analysis tools** — atomic and electronic structure, space groups,
+ diffraction, 2D/vdW systems, mechanical, optoelectronic, topological,
+ solar-cell, thermoelectric, piezoelectric, dielectric, STM, phonons,
+ dark-matter detection, Wannier tight-binding models, point defects,
+ heterostructures, magnetic ordering, image and spectrum processing.
+- **Database access** — download JARVIS datasets (DFT, FF, ML,
+ WannierTB, Solar, STM) and external sets (Materials Project, OQMD,
+ AFLOW). See the [datasets summary](https://atomgptlab.github.io/jarvis-tools/databases/).
+- **Reproducibility** — fetch raw input/output files for entries in the
+ JARVIS databases.
+- **Machine learning** — descriptors, graphs, and curated datasets for
+ model training.
+- **HPC integration** — job submission for Torque/PBS and SLURM.
+
## Installation
-- We recommend installing miniconda environment from
- :
+We recommend an isolated conda environment. Install
+[Miniconda](https://conda.io/miniconda.html), then:
- bash Miniconda3-latest-Linux-x86_64.sh (for linux)
- bash Miniconda3-latest-MacOSX-x86_64.sh (for Mac)
- Download 32/64 bit python 3.10 miniconda exe and install (for windows)
- Now, let's make a conda environment just for JARVIS::
- conda create --name my_jarvis python=3.10
- source activate my_jarvis
+```bash
+conda create -n my_jarvis python=3.10 -y
+conda activate my_jarvis
+```
-- Method-1: Installation using pip:
+Then pick one of the following install methods.
- pip install -U jarvis-tools
+**pip (recommended):**
-- Method-2: Installation using conda:
+```bash
+pip install -U jarvis-tools
+```
- conda install -c conda-forge jarvis-tools
+**conda-forge:**
-- Method-3: Installation using setup.py:
+```bash
+conda install -c conda-forge jarvis-tools
+```
- pip install numpy scipy matplotlib
- git clone https://github.com/usnistgov/jarvis.git
- cd jarvis
- python setup.py develop
+**From source:**
-- Method-4: Note on installing additional dependencies (for developers):
+```bash
+git clone https://github.com/atomgptlab/jarvis-tools.git
+cd jarvis-tools
+pip install -e .
+```
- conda env create --name my_jarvis -f environment.yml
- conda activate my_jarvis
- conda install pytest coverage codecov
- git clone https://github.com/usnistgov/jarvis.git
- cd jarvis
- git checkout develop
- python setup.py develop
- coverage run -m pytest
-
+**Developer setup** (with the dev environment file and tests):
+
+```bash
+git clone https://github.com/atomgptlab/jarvis-tools.git
+cd jarvis-tools
+git checkout develop
+conda env create -n my_jarvis -f environment.yml
+conda activate my_jarvis
+pip install -e .
+pip install pytest coverage codecov
+coverage run -m pytest
+```
+
+## Quick example
-
-## Example function
+Build a silicon structure and compute its density:
-``` python
+```python
from jarvis.core.atoms import Atoms
+
box = [[2.715, 2.715, 0], [0, 2.715, 2.715], [2.715, 0, 2.715]]
coords = [[0, 0, 0], [0.25, 0.25, 0.25]]
elements = ["Si", "Si"]
-Si = Atoms(lattice_mat=box, coords=coords, elements=elements)
-density = round(Si.density,2)
-print (density)
-2.33
-
-from jarvis.db.figshare import data
-dft_3d = data(dataset='dft_3d')
-print (len(dft_3d))
-75993
+si = Atoms(lattice_mat=box, coords=coords, elements=elements)
+print(round(si.density, 2)) # 2.33
+```
+Download the JARVIS-DFT 3D dataset and write each structure as a POSCAR:
+```python
+from jarvis.core.atoms import Atoms
+from jarvis.db.figshare import data
from jarvis.io.vasp.inputs import Poscar
-for i in dft_3d:
- atoms = Atoms.from_dict(i['atoms'])
- poscar = Poscar(atoms)
- jid = i['jid']
- filename = 'POSCAR-'+jid+'.vasp'
- poscar.write_file(filename)
-dft_2d = data(dataset='dft_2d')
-print (len(dft_2d))
-1109
-
-for i in dft_2d:
- atoms = Atoms.from_dict(i['atoms'])
- poscar = Poscar(atoms)
- jid = i['jid']
- filename = 'POSCAR-'+jid+'.vasp'
- poscar.write_file(filename)
-# Example to parse DOS data from JARVIS-DFT webpages
-from jarvis.db.webpages import Webpage
-from jarvis.core.spectrum import Spectrum
-import numpy as np
-new_dist=np.arange(-5, 10, 0.05)
-all_atoms = []
-all_dos_up = []
-all_jids = []
-for ii,i in enumerate(dft_3d):
- all_jids.append(i['jid'])
- try:
- w = Webpage(jid=i['jid'])
- edos_data = w.get_dft_electron_dos()
- ens = np.array(edos_data['edos_energies'].strip("'").split(','),dtype='float')
- tot_dos_up = np.array(edos_data['total_edos_up'].strip("'").split(','),dtype='float')
- s = Spectrum(x=ens,y=tot_dos_up)
- interp = s.get_interpolated_values(new_dist=new_dist)
- atoms=Atoms.from_dict(i['atoms'])
- ase_atoms=atoms.ase_converter()
- all_dos_up.append(interp)
- all_atoms.append(atoms)
- all_jids.append(i['jid'])
- filename=i['jid']+'.cif'
- atoms.write_cif(filename)
- break
- except Exception as exp :
- print (exp,i['jid'])
- pass
-```
-Find more examples at
+dft_3d = data(dataset="dft_3d")
+print(len(dft_3d)) # ~75993
-> 1.
-> 2.
-> 3.
-
-
-## Citing
+for entry in dft_3d:
+ atoms = Atoms.from_dict(entry["atoms"])
+ Poscar(atoms).write_file(f"POSCAR-{entry['jid']}.vasp")
+```
-Please cite the following if you happen to use JARVIS-Tools for a
-publication.
+Pull electronic density-of-states data from the JARVIS-DFT web pages and
+interpolate onto a common energy grid:
-
+```python
+import numpy as np
+from jarvis.core.atoms import Atoms
+from jarvis.core.spectrum import Spectrum
+from jarvis.db.figshare import data
+from jarvis.db.webpages import Webpage
-> Choudhary, K. et al. The joint automated repository for various
-> integrated simulations (JARVIS) for data-driven materials design. npj
-> Computational Materials, 6(1), 1-13 (2020).
+energy_grid = np.arange(-5, 10, 0.05)
+dft_3d = data(dataset="dft_3d")
+
+for entry in dft_3d[:10]:
+ try:
+ edos = Webpage(jid=entry["jid"]).get_dft_electron_dos()
+ ens = np.fromstring(edos["edos_energies"].strip("'"), sep=",")
+ dos_up = np.fromstring(edos["total_edos_up"].strip("'"), sep=",")
+ interp = Spectrum(x=ens, y=dos_up).get_interpolated_values(new_dist=energy_grid)
+ Atoms.from_dict(entry["atoms"]).write_cif(f"{entry['jid']}.cif")
+ except Exception as exc:
+ print(f"skip {entry['jid']}: {exc}")
+```
-
-## References
+More examples:
-Please see [Publications related to
-JARVIS-Tools](https://scholar.google.com/citations?user=3w6ej94AAAAJ)
+- [Tutorials](https://atomgptlab.github.io/jarvis-tools/tutorials/)
+- [Notebook gallery](https://github.com/JARVIS-Materials-Design/jarvis-tools-notebooks)
+- [Reference test files](https://atomgptlab.github.io/jarvis-tools/jarvis/tests/testfiles)
-
-## How to contribute
+## Citing
-[](http://makeapullrequest.com)
+If JARVIS-Tools contributes to a publication, please cite:
-For detailed instructions, please see [Contribution
-instructions](https://github.com/usnistgov/jarvis/blob/master/Contribution.rst)
+> Choudhary, K. *et al.* The joint automated repository for various
+> integrated simulations (JARVIS) for data-driven materials design.
+> *npj Computational Materials* **6**, 173 (2020).
+>
-
-## Correspondence
+For a broader list, see the
+[JARVIS publications on Google Scholar](https://scholar.google.com/citations?user=3w6ej94AAAAJ).
-Please report bugs as Github issues
-() or email to
-.
+## Contributing
-
-## Funding support
+[](http://makeapullrequest.com)
-NIST-MGI ().
+See the [contribution guide](https://github.com/atomgptlab/jarvis-tools/blob/master/Contribution.rst)
+and the [code of conduct](https://github.com/atomgptlab/jarvis-tools/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and feature requests go to
+[GitHub issues](https://github.com/atomgptlab/jarvis-tools/issues);
+direct correspondence: .
-Note: this repo has been migrated from https://github.com/usnistgov/jarvis
+## Funding
-
-## Code of conduct
+Developed under the [NIST Materials Genome Initiative](https://www.nist.gov/mgi).
-Please see [Code of
-conduct](https://github.com/usnistgov/jarvis/blob/master/CODE_OF_CONDUCT.md)
+> Note: this repository was migrated from
+> to
+> .
-
## Module structure
- jarvis/
- ├── ai
- │ ├── descriptors
- │ │ ├── cfid.py
- │ │ ├── coulomb.py
- │ ├── gcn
- │ ├── pkgs
- │ │ ├── lgbm
- │ │ │ ├── classification.py
- │ │ │ └── regression.py
- │ │ ├── sklearn
- │ │ │ ├── classification.py
- │ │ │ ├── hyper_params.py
- │ │ │ └── regression.py
- │ │ └── utils.py
- │ ├── uncertainty
- │ │ └── lgbm_quantile_uncertainty.py
- ├── analysis
- │ ├── darkmatter
- │ │ └── metrics.py
- │ ├── defects
- │ │ ├── surface.py
- │ │ └── vacancy.py
- │ ├── diffraction
- │ │ └── xrd.py
- │ ├── elastic
- │ │ └── tensor.py
- │ ├── interface
- │ │ └── zur.py
- │ ├── magnetism
- │ │ └── magmom_setup.py
- │ ├── periodic
- │ │ └── ptable.py
- │ ├── phonon
- │ │ ├── force_constants.py
- │ │ └── ir.py
- │ ├── solarefficiency
- │ │ └── solar.py
- │ ├── stm
- │ │ └── tersoff_hamann.py
- │ ├── structure
- │ │ ├── neighbors.py
- │ │ ├── spacegroup.py
- │ ├── thermodynamics
- │ │ ├── energetics.py
- │ ├── topological
- │ │ └── spillage.py
- ├── core
- │ ├── atoms.py
- │ ├── composition.py
- │ ├── graphs.py
- │ ├── image.py
- │ ├── kpoints.py
- │ ├── lattice.py
- │ ├── pdb_atoms.py
- │ ├── specie.py
- │ ├── spectrum.py
- │ └── utils.py
- ├── db
- │ ├── figshare.py
- │ ├── jsonutils.py
- │ ├── lammps_to_xml.py
- │ ├── restapi.py
- │ ├── vasp_to_xml.py
- │ └── webpages.py
- ├── examples
- │ ├── lammps
- │ │ ├── jff_test.py
- │ │ ├── Al03.eam.alloy_nist.tgz
- │ ├── vasp
- │ │ ├── dft_test.py
- │ │ ├── SiOptb88.tgz
- ├── io
- │ ├── boltztrap
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── calphad
- │ │ └── write_decorated_poscar.py
- │ ├── lammps
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── pennylane
- │ │ ├── inputs.py
- │ ├── phonopy
- │ │ ├── fcmat2hr.py
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── qe
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── qiskit
- │ │ ├── inputs.py
- │ ├── tequile
- │ │ ├── inputs.py
- │ ├── vasp
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── wannier
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── wanniertools
- │ │ ├── inputs.py
- │ │ └── outputs.py
- │ ├── wien2k
- │ │ ├── inputs.py
- │ │ ├── outputs.py
- ├── tasks
- │ ├── boltztrap
- │ │ └── run.py
- │ ├── lammps
- │ │ ├── templates
- │ │ └── lammps.py
- │ ├── phonopy
- │ │ └── run.py
- │ ├── vasp
- │ │ └── vasp.py
- │ ├── queue_jobs.py
- ├── tests
- │ ├── testfiles
- │ │ ├── ai
- │ │ ├── analysis
- │ │ │ ├── darkmatter
- │ │ │ ├── defects
- │ │ │ ├── elastic
- │ │ │ ├── interface
- │ │ │ ├── magnetism
- │ │ │ ├── periodic
- │ │ │ ├── phonon
- │ │ │ ├── solar
- │ │ │ ├── stm
- │ │ │ ├── structure
- │ │ │ ├── thermodynamics
- │ │ │ ├── topological
- │ │ ├── core
- │ │ ├── db
- │ │ ├── io
- │ │ │ ├── boltztrap
- │ │ │ ├── calphad
- │ │ │ ├── lammps
- │ │ │ ├── pennylane
- │ │ │ ├── phonopy
- │ │ │ ├── qiskit
- │ │ │ ├── qe
- │ │ │ ├── tequila
- │ │ │ ├── vasp
- │ │ │ ├── wannier
- │ │ │ ├── wanniertools
- │ │ │ ├── wien2k
- │ │ ├── tasks
- │ │ │ ├── test_lammps.py
- │ │ │ └── test_vasp.py
- └── README.rst
+```text
+jarvis/
+├── ai/ # ML descriptors, models, uncertainty
+│ ├── descriptors/ # CFID, Coulomb matrix, ...
+│ ├── gcn/ # graph convolutional networks
+│ ├── pkgs/ # scikit-learn, LightGBM wrappers
+│ └── uncertainty/
+├── analysis/ # property-specific analyses
+│ ├── darkmatter/ defects/ diffraction/ elastic/
+│ ├── interface/ magnetism/ periodic/ phonon/
+│ ├── solarefficiency/ stm/ structure/
+│ ├── thermodynamics/ topological/
+├── core/ # Atoms, Composition, Lattice, Spectrum, ...
+├── db/ # Figshare downloads, REST API, web scraping
+├── examples/ # runnable LAMMPS / VASP examples
+├── io/ # parsers/writers per code
+│ ├── boltztrap/ calphad/ lammps/ pennylane/ phonopy/
+│ ├── qe/ qiskit/ tequila/ vasp/ wannier/ wanniertools/ wien2k/
+├── tasks/ # workflow drivers + queue submission
+│ ├── boltztrap/ lammps/ phonopy/ vasp/ queue_jobs.py
+└── tests/ # unit tests + reference files under testfiles/
+```
diff --git a/docs/publications.md b/docs/publications.md
index 73d387a2..2e6c02a8 100644
--- a/docs/publications.md
+++ b/docs/publications.md
@@ -1,186 +1,65 @@
# Publications
-## JARVIS-Overview
-
-\[1. The joint automated repository for various integrated simulations
-(JARVIS) for data-driven materials design, npj Computational Materials
-6, 173 (2020).\]()
-
-\[2. Recent progress in the JARVIS infrastructure for next-generation
-data-driven materials design, arXiv
-(2023).\]()
-
-\[3. Large Scale Benchmark of Materials Design Methods,
-arXiv(2023).\]()
-
-## JARVIS-FF
-
-\[4. Evaluation and comparison of classical interatomic potentials
-through a user-friendly interactive web-interface, Nature: Sci Data. 4,
-160125 (2017).\]()
-
-\[5. High-throughput assessment of vacancy formation and surface
-energies of materials using classical force-fields, J. Phys. Cond. Matt.
-30,
-395901(2018).\]()
-
-## JARVIS-DFT related
-
-\[6. High-throughput Identification and Characterization of
-Two-dimensional Materials using Density functional theory, Scientific
-Reports 7, 5179
-(2017).\]()
-
-\[7. Computational Screening of High-performance Optoelectronic
-Materials using OptB88vdW and TBmBJ Formalisms, Scientific Data 5,
-180082 (2018).\]()
-
-\[8. Elastic properties of bulk and low-dimensional materials using van
-der Waals density functional, Phys. Rev. B, 98, 014107
-(2018).\]()
-
-\[9. High-throughput Discovery of Topologically Non-trivial Materials
-using Spin-orbit Spillage, Nature: Sci. Rep. 9,
-8534,(2019).\]()
-
-\[10. Computational Search for Magnetic and Non-magnetic 2D Topological
-Materials using Unified Spin-orbit Spillage Screening, npj Comp. Mat.,
-6, 49 (2020).\]()
-
-\[11. Density Functional Theory based Electric Field Gradient Database,
-Sci. Data 7, 362
-(2020).\]()
-
-\[12. Computational scanning tunneling microscope image database, Sci.
-Data, 8, 57
-(2021).\]()
-
-\[13. Database of Wannier Tight-binding Hamiltonians using
-High-throughput Density Functional Theory, Sci.
-Data\]()
-
-\[14. Predicting Anomalous Quantum Confinement Effect in van der Waals
-Materials, Phys. Rev.
-Mat.\]()
-
-\[15. High-throughput search for magnetic topological materials using
-spin-orbit spillage, machine-learning and experiments, Phys. Rev.
-B\]()
-
-\[16. Density functional theory-based electric field gradient database,
-Sci. Data\]()
-
-\[17. High-throughput DFT-based discovery of next generation
-two-dimensional (2D)
-superconductors\]()
-
-\[18. A systematic DFT+U and Quantum Monte Carlo benchmark of magnetic
-two-dimensional (2D) CrX (X = I, Br, Cl,
-F)\]()
-
-## JARVIS-ML related
-
-\[19. Machine learning with force-field inspired descriptors for
-materials: fast screening and mapping energy landscape, Phys. Rev. Mat.,
-2, 083801
-(2018).\]()
-
-\[28. Convergence and machine learning predictions of Monkhorst-Pack
-k-points and plane-wave cut-off in high-throughput DFT calculations,
-Comp. Mat. Sci. 161, 300
-(2019).\]()
-
-\[21. Materials science in the artificial intelligence age:
-high-throughput library generation, machine learning, and a pathway from
-correlations to the underpinning physics, MRS Comm., 1-18,
-2019.\]()
-
-\[22. Enhancing materials property prediction by leveraging
-computational and experimental data using deep transfer learning, Nature
-Comm., 10, 1,
-(2019).\]()
-
-\[23. Accelerated Discovery of Efficient Solar-cell Materials using
-Quantum and Machine-learning Methods, Chem. Mater., 31, 5900
-(2019).\]()
-
-\[24. High-throughput Density Functional Perturbation Theory and Machine
-Learning Predictions of Infrared, Piezoelectric and Dielectric
-Responses, npj Computational Materials 6, 64
-(2020).\]()
-
-\[25. Data-driven Discovery of 3D and 2D Thermoelectric Materials, J.
-Phys.: Cond.
-Matt.\]()
-
-\[26. Efficient Computational Design of 2D van der Waals
-Heterostructures: Band-Alignment, Lattice-Mismatch, Web-app Generation
-and Machine-learning.\]()
-
-\[27. Enhancing materials property prediction by leveraging
-computational and experimental data using deep transfer learning, Nature
-Commun.\]()
-
-\[28. Atomistic Line Graph Neural Network for Improved Materials
-Property Predictions, npj Computational Materials 7, 1
-(2021)\]()
-
-\[29. Recent advances and applications of deep learning methods in
-materials science, npj Computational Materials 8, 1
-(2022)\]()
-
-\[30. Graph neural network predictions of metal organic framework CO2
-adsorption properties, Comp. Mat. Sci., 210, 111388
-(2022)\]()
-
-\[31. Data-Driven Multi-Scale Modeling and Optimization for Elastic
-Properties of Cubic
-Microstructures\]()
-
-\[32. Uncertainty Prediction for Machine Learning Models of Material
-Properties\]()
-
-\[33. Cross-property deep transfer learning framework for enhanced
-predictive analytics on small materials
-data\]()
-
-\[34. Prediction of the Electron Density of States for Crystalline
-Compounds with Atomistic Line Graph Neural Networks
-(ALIGNN)\]()
-
-\[35. Designing High-Tc Superconductors with BCS-inspired Screening,
-Density Functional Theory and
-Deep-learning\]()
-
-\[36. Rapid Prediction of Phonon Structure and Properties using an
-Atomistic Line Graph Neural Network
-(ALIGNN)\]()
-
-\[37. Unified Graph Neural Network Force-field for the Periodic
-Table\]()
-
-\[38. AtomVision: A machine vision library for atomistic
-images\]()
-
-\[39. ChemNLP: A Natural Language Processing based Library for Materials
-Chemistry Text Data\]()
-
-\[40. A critical examination of robustness and generalizability of
-machine learning prediction of materials
-properties\]()
-
-\[41. Inverse design of next-generation superconductors using
-data-driven deep generative
-models\]()
-
-## JARVIS-QC related
-
-\[42. Quantum Computation for Predicting Electron and Phonon Properties
-of Solids., J. Phys.: Cond.
-Matt.\]()
-
-## JARVIS-QETB related
-
-\[43. Fast and Accurate Prediction of Material Properties with
-Three-Body Tight-Binding Model for the Periodic
-Table\]()
+A curated list of peer-reviewed and preprint publications that describe
+JARVIS, use it as core infrastructure, or report results that depend on
+it. Grouped by sub-project. For the full, continually updated list, see
+[Kamal Choudhary's Google Scholar](https://scholar.google.com/citations?user=3w6ej94AAAAJ).
+
+## JARVIS overview
+
+1. [The joint automated repository for various integrated simulations (JARVIS) for data-driven materials design](https://www.nature.com/articles/s41524-020-00440-1) — *npj Computational Materials* **6**, 173 (2020).
+2. [Recent progress in the JARVIS infrastructure for next-generation data-driven materials design](https://arxiv.org/abs/2305.11842) — arXiv (2023).
+3. [Large-scale benchmark of materials design methods](https://arxiv.org/abs/2306.11688) — arXiv (2023).
+
+## JARVIS-FF (force fields)
+
+4. [Evaluation and comparison of classical interatomic potentials through a user-friendly interactive web interface](https://www.nature.com/articles/sdata2016125) — *Scientific Data* **4**, 160125 (2017).
+5. [High-throughput assessment of vacancy formation and surface energies of materials using classical force fields](http://iopscience.iop.org/article/10.1088/1361-648X/aadaff/meta) — *J. Phys. Condens. Matter* **30**, 395901 (2018).
+
+## JARVIS-DFT
+
+6. [High-throughput identification and characterization of two-dimensional materials using density functional theory](https://www.nature.com/articles/s41598-017-05402-0) — *Sci. Rep.* **7**, 5179 (2017).
+7. [Computational screening of high-performance optoelectronic materials using OptB88vdW and TBmBJ formalisms](https://www.nature.com/articles/sdata201882) — *Sci. Data* **5**, 180082 (2018).
+8. [Elastic properties of bulk and low-dimensional materials using van der Waals density functional](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.98.014107) — *Phys. Rev. B* **98**, 014107 (2018).
+9. [High-throughput discovery of topologically non-trivial materials using spin-orbit spillage](https://www.nature.com/articles/s41598-019-45028-y) — *Sci. Rep.* **9**, 8534 (2019).
+10. [Computational search for magnetic and non-magnetic 2D topological materials using unified spin-orbit spillage screening](https://www.nature.com/articles/s41524-020-0319-4) — *npj Comput. Mater.* **6**, 49 (2020).
+11. [Density functional theory based electric field gradient database](https://www.nature.com/articles/s41597-020-00707-8) — *Sci. Data* **7**, 362 (2020).
+12. [Computational scanning tunneling microscope image database](https://www.nature.com/articles/s41597-021-00824-y) — *Sci. Data* **8**, 57 (2021).
+13. [Database of Wannier tight-binding Hamiltonians using high-throughput density functional theory](https://www.nature.com/articles/s41597-021-00885-z) — *Sci. Data*.
+14. [Predicting anomalous quantum confinement effect in van der Waals materials](https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.5.054602) — *Phys. Rev. Mater.*
+15. [High-throughput search for magnetic topological materials using spin-orbit spillage, machine learning, and experiments](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.103.155131) — *Phys. Rev. B*.
+16. [High-throughput DFT-based discovery of next-generation two-dimensional (2D) superconductors](https://pubs.acs.org/doi/full/10.1021/acs.nanolett.2c04420) — *Nano Lett.*
+17. [A systematic DFT+U and Quantum Monte Carlo benchmark of magnetic two-dimensional CrX (X = I, Br, Cl, F)](https://pubs.acs.org/doi/abs/10.1021/acs.jpcc.2c06733) — *J. Phys. Chem. C*.
+
+## JARVIS-ML
+
+18. [Machine learning with force-field inspired descriptors for materials: fast screening and mapping energy landscape](https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.2.083801) — *Phys. Rev. Mater.* **2**, 083801 (2018).
+19. [Convergence and machine-learning predictions of Monkhorst-Pack k-points and plane-wave cutoff in high-throughput DFT](https://www.sciencedirect.com/science/article/pii/S0927025619300813) — *Comput. Mater. Sci.* **161**, 300 (2019).
+20. [Materials science in the AI age: high-throughput library generation, machine learning, and a pathway from correlations to underpinning physics](https://doi.org/10.1557/mrc.2019.95) — *MRS Commun.* (2019).
+21. [Enhancing materials property prediction by leveraging computational and experimental data using deep transfer learning](https://www.nature.com/articles/s41467-019-13297-w) — *Nat. Commun.* **10** (2019).
+22. [Accelerated discovery of efficient solar cell materials using quantum and machine-learning methods](https://pubs.acs.org/doi/10.1021/acs.chemmater.9b02166) — *Chem. Mater.* **31**, 5900 (2019).
+23. [High-throughput density functional perturbation theory and machine learning predictions of infrared, piezoelectric, and dielectric responses](https://www.nature.com/articles/s41524-020-0337-2) — *npj Comput. Mater.* **6**, 64 (2020).
+24. [Data-driven discovery of 3D and 2D thermoelectric materials](https://iopscience.iop.org/article/10.1088/1361-648X/aba06b/meta) — *J. Phys. Condens. Matter*.
+25. [Efficient computational design of 2D van der Waals heterostructures: band alignment, lattice mismatch, web-app generation, and machine learning](https://arxiv.org/abs/2004.03025) — arXiv.
+26. [Atomistic Line Graph Neural Network for improved materials property predictions](https://www.nature.com/articles/s41524-021-00650-1) — *npj Comput. Mater.* **7** (2021).
+27. [Recent advances and applications of deep learning methods in materials science](https://www.nature.com/articles/s41524-022-00734-6) — *npj Comput. Mater.* **8** (2022).
+28. [Graph neural network predictions of metal organic framework CO₂ adsorption properties](https://www.sciencedirect.com/science/article/pii/S092702562200163X) — *Comput. Mater. Sci.* **210**, 111388 (2022).
+29. [Data-driven multi-scale modeling and optimization for elastic properties of cubic microstructures](https://link.springer.com/article/10.1007/s40192-022-00258-3) — *Integr. Mater. Manuf. Innov.*
+30. [Uncertainty prediction for machine learning models of material properties](https://pubs.acs.org/doi/abs/10.1021/acsomega.1c03752) — *ACS Omega*.
+31. [Cross-property deep transfer learning framework for enhanced predictive analytics on small materials data](https://www.nature.com/articles/s41467-021-26921-5) — *Nat. Commun.*
+32. [Prediction of the electron density of states for crystalline compounds with Atomistic Line Graph Neural Networks (ALIGNN)](https://link.springer.com/article/10.1007/s11837-022-05199-y) — *JOM*.
+33. [Designing high-Tc superconductors with BCS-inspired screening, DFT, and deep learning](https://arxiv.org/abs/2205.00060) — arXiv.
+34. [Rapid prediction of phonon structure and properties using ALIGNN](https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.7.023803) — *Phys. Rev. Mater.*
+35. [Unified graph neural network force field for the periodic table](https://pubs.rsc.org/en/content/articlehtml/2023/dd/d2dd00096b) — *Digital Discovery*.
+36. [AtomVision: a machine vision library for atomistic images](https://pubs.acs.org/doi/full/10.1021/acs.jcim.2c01533) — *J. Chem. Inf. Model.*
+37. [ChemNLP: a natural language processing library for materials chemistry text data](https://arxiv.org/abs/2209.08203) — arXiv.
+38. [A critical examination of robustness and generalizability of machine learning prediction of materials properties](https://www.nature.com/articles/s41524-023-01012-9) — *npj Comput. Mater.*
+39. [Inverse design of next-generation superconductors using data-driven deep generative models](https://pubs.acs.org/doi/10.1021/acs.jpclett.3c01260) — *J. Phys. Chem. Lett.*
+
+## JARVIS-QC (quantum computing)
+
+40. [Quantum computation for predicting electron and phonon properties of solids](https://iopscience.iop.org/article/10.1088/1361-648X/ac1154) — *J. Phys. Condens. Matter*.
+
+## JARVIS-QETB (quantum-espresso tight-binding)
+
+41. [Fast and accurate prediction of material properties with a three-body tight-binding model for the periodic table](https://journals.aps.org/prmaterials/abstract/10.1103/PhysRevMaterials.7.044603) — *Phys. Rev. Mater.*
diff --git a/docs/tutorials.md b/docs/tutorials.md
index 71b2069a..5e7cdc5a 100644
--- a/docs/tutorials.md
+++ b/docs/tutorials.md
@@ -1,303 +1,252 @@
# Tutorials
-## Quickstart with Jupyter/Google-colab notebooks: https://github.com/usnistgov/aims2024_workshop
+A guided tour of the most common JARVIS-Tools workflows. For runnable
+notebooks, see the
+[AIMS 2024 workshop](https://github.com/usnistgov/aims2024_workshop)
+and the
+[jarvis-tools-notebooks gallery](https://github.com/JARVIS-Materials-Design/jarvis-tools-notebooks).
-More detailed tutorials below:
+## Atomic structures
-## How to analyze an atomic structure
+Atomic structures are the input to nearly every simulation in
+JARVIS-Tools — DFT, molecular dynamics, Monte Carlo, atomistic graph
+neural networks. A structure is defined by element types, fractional or
+Cartesian coordinates, and a lattice matrix that sets the periodic
+boundary conditions.
-Atomic structure act as an input to multiple simulations such as for
-density functional theory, molecular dyanmics, Monte Carlo, atomistic
-graph neural network etc. So, we provide a very bried introduction to
-the atomic structure here. For more general information, refer to
-solid-state physics or introduction to materials-science books.
+The example below builds a silicon primitive cell. The same pattern
+applies to multi-component systems.
-An atomic structure can consist of atomic element types, corresponding
-xyz coordinates in space (either in real or reciprocal space) and
-lattice matrix used in setting periodic boundary conditions.
-
-An example of constructing an atomic structure class using
-`jarvis.core.Atoms` is given below. After creating the Atoms class, we
-can simply print it and visualize the POSCAR format file in a software
-such as VESTA. While the examples below use Silicon elemental crystal
-creation and analysis, it can be used for multi-component systems as
-well.
-
-``` python
+```python
from jarvis.core.atoms import Atoms
+
box = [[2.715, 2.715, 0], [0, 2.715, 2.715], [2.715, 0, 2.715]]
coords = [[0, 0, 0], [0.25, 0.25, 0.25]]
elements = ["Si", "Si"]
+
Si = Atoms(lattice_mat=box, coords=coords, elements=elements, cartesian=False)
-print (Si) # To visualize
-Si.write_poscar('POSCAR.vasp')
-Si.write_cif('POSCAR.vasp')
+print(Si) # POSCAR-style printout
+Si.write_poscar("POSCAR.vasp")
+Si.write_cif("Si.cif")
```
-The Atoms class here is created from the
-raw data, but it can also be read from different file formats such as:
-'.cif', 'POSCAR', '.xyz', '.pdb', '.sdf',
-'.mol2' etc. The Atoms class can also be written to files in
-formats such as POSCAR/.cif etc.
-
-Note that for molecular systems, we use a large vaccum padding (say 50
-Angstrom in each direction) and set lattice_mat accordingly, e.g.
-lattice_mat = \[\[50,0,0\],\[0,50,0\],\[0,0,50\]\]. Similarly, for free
-surfaces we set high vaccum in one of the crystallographic directions
-(say z) by giving a large z-comonent in the lattice matrix while keeping
-the x, y comonents intact.
-
-``` python
-my_atoms = Atoms.from_poscar('POSCAR')
-my_atoms.write_poscar('MyPOSCAR')
+The `Atoms` class can also be loaded from `.cif`, `POSCAR`, `.xyz`,
+`.pdb`, `.sdf`, or `.mol2` files, and written back out to any of those
+formats.
+
+For molecular systems, pad with vacuum (e.g. 50 Å in each direction):
+`lattice_mat=[[50,0,0],[0,50,0],[0,0,50]]`. For free surfaces, add
+vacuum along one crystallographic direction (typically z) while keeping
+the in-plane lattice vectors intact.
+
+```python
+my_atoms = Atoms.from_poscar("POSCAR")
+my_atoms.write_poscar("MyPOSCAR")
```
-Once this Atoms class is created, several imprtant information can be
-obtained such as:
-
-``` python
-print ('volume',Si.volume)
-print ('density in g/cm3', Si.density)
-print ('composition as dictionary', Si.composition)
-print ('Chemical formula', Si.composition.reduced_formula)
-print ('Spacegroup info', Si.spacegroup())
-print ('lattice-parameters', Si.lattice.abc, Si.lattice.angles)
-print ('packing fraction',Si.packing_fraction)
-print ('number of atoms',Si.num_atoms)
-print ('Center of mass', Si.get_center_of_mass())
-print ('Atomic number list', Si.atomic_numbers)
+Once an `Atoms` object exists, common quantities are one attribute away:
+
+```python
+print("volume ", Si.volume)
+print("density (g/cm³) ", Si.density)
+print("composition ", Si.composition)
+print("formula ", Si.composition.reduced_formula)
+print("space group ", Si.spacegroup())
+print("lattice (abc) ", Si.lattice.abc, Si.lattice.angles)
+print("packing fraction", Si.packing_fraction)
+print("num atoms ", Si.num_atoms)
+print("center of mass ", Si.get_center_of_mass())
+print("atomic numbers ", Si.atomic_numbers)
```
-For creating/accessing dataset(s), we use `Atoms.from_dict()` and
-`Atoms.to_dict()` methods:
+To round-trip through dicts (useful for serializing to JSON):
-``` python
+```python
d = Si.to_dict()
new_atoms = Atoms.from_dict(d)
```
-The jarvis.core.Atoms object can be
-converted back and forth to other simulation toolsets such as Pymatgen
-and ASE if insyalled, as follows
+To convert to/from other toolkits:
-``` python
-pmg_struct = Si.pymatgen_converter()
-ase_atoms = Si.ase_converter()
+```python
+pmg_struct = Si.pymatgen_converter() # requires pymatgen
+ase_atoms = Si.ase_converter() # requires ase
```
-In order to make supercell, the following example can be used:
+Supercells:
-``` python
-supercell_1 = Si.make_supercell([2,2,2])
-supercell_2 = Si.make_supercell_matrix([[2,0,0],[0,2,0],[0,0,2]])
-supercell_1.density == supercell_2.density
+```python
+supercell_1 = Si.make_supercell([2, 2, 2])
+supercell_2 = Si.make_supercell_matrix([[2, 0, 0], [0, 2, 0], [0, 0, 2]])
+assert supercell_1.density == supercell_2.density
```
-### How to get RDF, ADF, DDF
+### Radial, angular, and dihedral distribution functions
-Nearest-neighbor analysis one of the most important tools in atomistic
-simulations. Quantities such as radial (RDF), angle (ADF) and dihedral
-(DDF) distribution functions can be obtained using
-jarvis.analysis.structure.neighbors.NeighborsAnalysis
-class as shown in the following example using the Si Atoms class
-obtained above. Different cut-off parameters for angle and sihedral
-distribution are used to narrow down the number of neighbors. For
-details, please look into respective modules.
+`NeighborsAnalysis` computes radial (RDF), angular (ADF), and dihedral
+(DDF) distribution functions. Different cutoffs limit how many neighbors
+are considered for the angular and dihedral distributions; see the
+module reference for details.
-``` python
-nb = NeighborsAnalysis(Si)
-bins_rdf, rdf, nbs = nb.get_rdf() #Global Radial distribution function
-adfa, bins_a = nb.ang_dist_first() #Angular distribution function upto first neighbor
-adfb, bins_b = nb.ang_dist_second() #Angular distribution function upto second neighbor
-ddf, bins_d = nb.get_ddf() #Dihedral distribution function upto first neighbor
-import matplotlib
-%matplotlib inline
+```python
+from jarvis.analysis.structure.neighbors import NeighborsAnalysis
import matplotlib.pyplot as plt
from matplotlib.gridspec import GridSpec
-the_grid = GridSpec(2, 2)
-plt.rcParams.update({'font.size': 24})
-plt.figure(figsize=(16,14))
-
-plt.subplot(the_grid[0, 0])
-plt.title('(a) RDF')
-plt.plot(bins_rdf, rdf)
-plt.xlabel(r'Distance bins ($\AA$)')
-
-plt.subplot(the_grid[0, 1])
-plt.title('(b) ADF-a')
-plt.plot(bins_a[:-1], adfa)
-plt.xlabel(r'Angle bins ($^\circ$)')
-
-plt.subplot(the_grid[1, 0])
-plt.title('(c) ADF-b')
-plt.plot(bins_b[:-1], adfb)
-plt.xlabel(r'Angle bins ($^\circ$)')
-
-plt.subplot(the_grid[1, 1])
-plt.title('(d) DDF')
-plt.plot(bins_d[:-1], ddf)
-plt.xlabel(r'Angle bins ($^\circ$)')
+nb = NeighborsAnalysis(Si)
+bins_rdf, rdf, _ = nb.get_rdf() # global RDF
+adfa, bins_a = nb.ang_dist_first() # ADF, first-neighbor cutoff
+adfb, bins_b = nb.ang_dist_second() # ADF, second-neighbor cutoff
+ddf, bins_d = nb.get_ddf() # DDF, first-neighbor cutoff
+
+grid = GridSpec(2, 2)
+plt.rcParams.update({"font.size": 24})
+plt.figure(figsize=(16, 14))
+
+plt.subplot(grid[0, 0]); plt.title("(a) RDF")
+plt.plot(bins_rdf, rdf); plt.xlabel(r"Distance ($\AA$)")
+
+plt.subplot(grid[0, 1]); plt.title("(b) ADF-a")
+plt.plot(bins_a[:-1], adfa); plt.xlabel(r"Angle ($^\circ$)")
+
+plt.subplot(grid[1, 0]); plt.title("(c) ADF-b")
+plt.plot(bins_b[:-1], adfb); plt.xlabel(r"Angle ($^\circ$)")
+
+plt.subplot(grid[1, 1]); plt.title("(d) DDF")
+plt.plot(bins_d[:-1], ddf); plt.xlabel(r"Angle ($^\circ$)")
plt.tight_layout()
```
-### How to get XRD paterns
+### XRD patterns
-X-ray diffraction patterns act as one of the most important experimental
-methods for determining atomic structure. Using Cu-K alpha wavelength,
-the theoretical XRD patterns (two-theta and d_hkl dependence) for Si
-class above can be obatined as follows.
+Theoretical XRD patterns (2θ and d_hkl) using Cu-Kα radiation:
-``` python
+```python
import matplotlib.pyplot as plt
from matplotlib.gridspec import GridSpec
+from jarvis.analysis.diffraction.xrd import XRD
-Si = Atoms(lattice_mat=box, coords=coords, elements=elements)
-a, b, c = XRD().simulate(atoms=atoms)
-
-the_grid = GridSpec(1,2)
-plt.rcParams.update({'font.size': 24})
-plt.figure(figsize=(10,5))
-
-plt.subplot(the_grid[0])
-plt.bar(a,c)
-plt.xlabel('2$\Theta$')
-plt.ylabel('XRD intensity')
-plt.subplot(the_grid[1])
-plt.bar(a,b)
-plt.xlabel('d$_{hkl}$')
-plt.ylabel('XRD intensity')
+two_theta, d_hkl, intensity = XRD().simulate(atoms=Si)
+
+grid = GridSpec(1, 2)
+plt.rcParams.update({"font.size": 24})
+plt.figure(figsize=(10, 5))
+
+plt.subplot(grid[0])
+plt.bar(two_theta, intensity)
+plt.xlabel(r"2$\Theta$"); plt.ylabel("XRD intensity")
+
+plt.subplot(grid[1])
+plt.bar(two_theta, d_hkl)
+plt.xlabel(r"d$_{hkl}$"); plt.ylabel("XRD intensity")
plt.tight_layout()
```
-### How to make defects
+### Defects: vacancies, surfaces, and heterostructures
-While the above Si atomic structure generated above is perfect/defect
-free, in reality there can be several defects present in an atomic
-structure such as point defects (vacancies, interstitials,
-substituions), line defects (dislocations), surface-defects
-(free-surfaces, grain boundaries, stacking faults, interfaces),
-volume-defects (voids/pores) etc.
+Real materials contain point defects (vacancies, interstitials,
+substitutions), line defects (dislocations), surface defects (free
+surfaces, grain boundaries, stacking faults, interfaces), and volume
+defects (voids, pores). JARVIS-Tools generates several of these
+automatically.
-An example of creating vacancy structures using unique Wycoff positions
-is shown below:
+Vacancies at the unique Wyckoff sites:
-``` python
+```python
from jarvis.analysis.defects.vacancy import Vacancy
-#enforces cell-size to be close to 10 Angstroms
+
vacs = Vacancy(atoms=Si).generate_defects(enforce_c_size=10.0)
len(vacs), vacs[0].to_dict()["defect_structure"].num_atoms
-# We find that there are only one unique point vacanc available based on Wycoff-position information
+# Si has only one symmetry-unique vacancy site.
```
-Similarly, an example of creating, free surfaces is shown below:
+Free surfaces:
-``` python
-from jarvis.analysis.defects.surface import wulff_normals, Surface
+```python
+from jarvis.analysis.defects.surface import Surface
-# Let's create (1,1,1) surface with three layers, and vacuum=18.0 Angstrom
-# We center it around origin so that it looks good during visualization
surface_111 = (
Surface(atoms=Si, indices=[1, 1, 1], layers=3, vacuum=18)
- .make_surface()
- .center_around_origin()
+ .make_surface()
+ .center_around_origin()
)
print(surface_111)
```
-While the above example makes only one surface (111), we can ask
-jarvis-tools to provide all symmetrically distinct surfaces as follows:
+All symmetry-distinct surfaces up to a given Miller index:
-``` python
+```python
from jarvis.analysis.structure.spacegroup import (
Spacegroup3D,
symmetrically_distinct_miller_indices,
)
+
spg = Spacegroup3D(atoms=Si)
cvn = spg.conventional_standard_structure
mills = symmetrically_distinct_miller_indices(max_index=3, cvn_atoms=cvn)
-for i in mills:
- surf = Surface(atoms=Si, indices=i, layers=3, vacuum=18).make_surface()
- print ('Index:', i)
- print (surf)
+for hkl in mills:
+ surf = Surface(atoms=Si, indices=hkl, layers=3, vacuum=18).make_surface()
+ print("Index:", hkl)
+ print(surf)
```
-Heterostructures of a film and a substrate can be created using ZSL
-algorithm as shown in the following example:
+Film/substrate heterostructures via the Zur–McGill (ZSL) algorithm:
-``` python
-from jarvis.analysis.interface.zur import ZSLGenerator, mismatch_strts, get_hetero, make_interface
-film = Surface(atoms=Si, indices=[1, 1, 1], layers = 3, vacuum = 18 ).make_surface().center_around_origin()
-substrate = Surface(atoms=Si, indices=[1, 1, 1], layers = 3, vacuum = 18 ).make_surface().center_around_origin()
-info = make_interface(film=film, subs=substrate)['interface'].center(vacuum=18)
-print (info)
-```
+```python
+from jarvis.analysis.interface.zur import make_interface
+from jarvis.analysis.defects.surface import Surface
-## How to setup/analyze DFT calculations using VASP
-
-The Vienna Ab initio Simulation Package (VASP) is a package for
-performing ab initio quantum mechanical calculations using either
-Vanderbilt pseudopotentials, or the projector augmented wave method, and
-a plane wave basis set. Manual for VASP is available at:
- .
-
-Running a VASP calculation requires the following files: `INCAR`,
-`POSCAR`, `KPOINTS`, `POTCAR` as well as additional files such as
-`vdw_kernel.bindat` for specific types of calculations. While setting up
-calculations for one or a few systems/setups should be straight forward,
-setting up calculations for thousands of materials and most importantly
-making a database out of all those calculations require automated
-calculations script collections such as JARVIS-Tools.
-
-Gievn an atomic structure in 1) `jarvis.core.Atoms` format, JARVIS-Tools
-2) prepares input files such as `INCAR` etc. as mentioned above and 3)
-submits the calculations to your queuing system such as SLURM/PBS using
-`jarvis.tasks.vasp` and `jarvis.tasks.queue_jobs`. After a calculations
-get completed, 4) automated analysis can be carried out and plots and
-webpages are generated. The input file generation and output file
-parsing modules for VASP can be found in `jarvis.io.vasp.inputs` and
-`jarvis.io.vasp.outputs` modules. The automated analyis and XML
-generation for webpages can be found in `jarvis.db.vasp_to_xml` module.
-After the xml page creation they are converted using html using XSLT
-scripts.
-
-Additionally, a JSON file is created with metadata from all the XML
-pages for thousands of materials to easily use in data-analytics/machine
-learning applications.The JARVIS-DFT
-() database primarily uses such a
-workflow. Make sure `VASP_PSP_DIR` is declared as a PATH to VASP
-pseudopotential directory i.e.
-
-``` bash
-$ export VASP_PSP_DIR=YOUR_PATH_TO_PSUEDOPTENTIALS
+film = Surface(atoms=Si, indices=[1, 1, 1], layers=3, vacuum=18).make_surface().center_around_origin()
+substrate = Surface(atoms=Si, indices=[1, 1, 1], layers=3, vacuum=18).make_surface().center_around_origin()
+
+interface = make_interface(film=film, subs=substrate)["interface"].center(vacuum=18)
+print(interface)
```
-in your ~/.bashrc file.
+## DFT calculations with VASP
+
+The Vienna Ab initio Simulation Package (VASP) performs ab initio
+quantum-mechanical calculations using either Vanderbilt pseudopotentials
+or the projector augmented-wave method, with a plane-wave basis set.
+See the [VASP manual](https://www.vasp.at/wiki/index.php/The_VASP_Manual)
+for theory and runtime details.
+
+A VASP run requires `INCAR`, `POSCAR`, `KPOINTS`, and `POTCAR` (plus
+`vdw_kernel.bindat` for some calculations). For one-off jobs this is
+straightforward; for thousands of materials with consistent
+post-processing, JARVIS-Tools provides:
+
+1. an `Atoms` representation in `jarvis.core.atoms`,
+2. input-file generation in `jarvis.io.vasp.inputs`,
+3. queue submission via `jarvis.tasks.vasp` and `jarvis.tasks.queue_jobs`,
+4. output parsing in `jarvis.io.vasp.outputs`, and
+5. XML/HTML generation in `jarvis.db.vasp_to_xml` (via XSLT for the
+ web rendering).
-### How to setup a single calculation
+A consolidated JSON file is then built from the per-material XML pages
+for downstream data analytics and ML. The
+[JARVIS-DFT database](https://jarvis.nist.gov/jarvisdft/) is produced
+with this workflow.
-We start by setting up and submitting a single VaspJob:
+Make sure `VASP_PSP_DIR` points at your pseudopotential directory,
+typically in your `~/.bashrc`:
-``` python
+```bash
+export VASP_PSP_DIR=/path/to/vasp_pseudopotentials
+```
+
+### A single calculation
+
+```python
+import os
from jarvis.tasks.vasp.vasp import VaspJob, write_vaspjob
from jarvis.io.vasp.inputs import Potcar, Incar, Poscar
-from jarvis.db.jsonutils import dumpjson
-from jarvis.core.atoms import Atoms
from jarvis.core.kpoints import Kpoints3D
-from jarvis.tasks.queue_jobs import Queue
-import os
+from jarvis.db.jsonutils import dumpjson
-# Load/build crystal structure
-mat = Poscar.from_file('POSCAR')
-# coords = [[0, 0, 0], [0.25, 0.25, 0.25]]
-# elements = ["Si", "Si"]
-# box = [[2.715, 2.715, 0], [0, 2.715, 2.715], [2.715, 0, 2.715]]
-# atoms = Atoms(lattice_mat=box, coords=coords, elements=elements)
-# mat = Poscar(atoms)
-# mat.comment = "Silicon"
-
-# Build INCAR file
-data = dict(
+mat = Poscar.from_file("POSCAR")
+
+incar = Incar(dict(
PREC="Accurate",
ISMEAR=0,
SIGMA=0.01,
@@ -316,103 +265,72 @@ data = dict(
LVTOT=".FALSE.",
LVHAR=".FALSE.",
LWAVE=".FALSE.",
-)
-inc = Incar(data)
-# Build POTCAR info
-# export VASP_PSP_DIR = 'PATH_TO_YOUR_PSP'
-pot = Potcar.from_atoms(mat.atoms)
-#pot = Potcar(elements=mat.atoms.elements)
-
-# Build Kpoints info
-kp = Kpoints3D().automatic_length_mesh(
+))
+
+potcar = Potcar.from_atoms(mat.atoms)
+kpoints = Kpoints3D().automatic_length_mesh(
lattice_mat=mat.atoms.lattice_mat, length=20
)
-vasp_cmd = "PATH_TO vasp_std"
-copy_files = ["PATH_TO vdw_kernel.bindat"]
-jobname = "MAIN-RELAX@JVASP-1002"
job = VaspJob(
poscar=mat,
- incar=inc,
- potcar=pot,
- kpoints=kp,
- vasp_cmd=vasp_cmd,
- copy_files=copy_files,
- jobname=jobname,
+ incar=incar,
+ potcar=potcar,
+ kpoints=kpoints,
+ vasp_cmd="/path/to/vasp_std",
+ copy_files=["/path/to/vdw_kernel.bindat"],
+ jobname="MAIN-RELAX@JVASP-1002",
)
dumpjson(data=job.to_dict(), filename="job.json")
write_vaspjob(pyname="job.py", job_json="job.json")
```
-The job.py can now be run on a cluster or on a PC as a python script.
-For running this job on a PBS cluster,
+`job.py` can now be run directly on a workstation, or submitted to a
+PBS/SLURM cluster:
-``` python
-submit_cmd = ["qsub", "submit_job"]
-# Example job commands, need to change based on your cluster
-job_line = (
- "source activate my_jarvis \n"
- + "python job.py"
-)
-name = "TestJob"
-directory = os.getcwd()
+```python
+import os
+from jarvis.tasks.queue_jobs import Queue
+
+job_line = "source activate my_jarvis\npython job.py"
Queue.pbs(
job_line=job_line,
- jobname=name,
- directory=directory,
- submit_cmd=submit_cmd,
- )
+ jobname="TestJob",
+ directory=os.getcwd(),
+ submit_cmd=["qsub", "submit_job"],
+)
```
-### How to setup high-throughput calculations
-
-Currently, JARVIS-Tools can be used to submit job with SLURM and PBS
-clusters only. For high-throughput automated submissions one can use
-pre-build `JobFactory` module that allows automatic calculations for a
-series of properties.
+### High-throughput calculations
-``` python
-# List of materials to run high-throughput calculations on
-ids = ['POSCAR-1.vasp','POSCAR-2.vasp','POSCAR-3.vasp']
+`JobFactory` chains together a sequence of standard property
+calculations (relaxation, band structure, optics, elastic constants,
+…) for many structures.
-from jarvis.tasks.vasp.vasp import (
- JobFactory,
- VaspJob,
- GenericIncars,
- write_jobfact,
-)
-from jarvis.io.vasp.inputs import Potcar, Incar, Poscar
+```python
+import os
+from jarvis.tasks.vasp.vasp import JobFactory, GenericIncars, write_jobfact
+from jarvis.io.vasp.inputs import Poscar
from jarvis.db.jsonutils import dumpjson
-from jarvis.db.figshare import data
-from jarvis.core.atoms import Atoms
from jarvis.tasks.queue_jobs import Queue
-import os
-vasp_cmd = "mpirun PATH_TO vasp_std"
-copy_files = ["PATH_TO vdw_kernel.bindat"]
-submit_cmd = ["qsub", "submit_job"]
-
-# For slurm
-# submit_cmd = ["sbatch", "submit_job"]
-
-steps = [
- "ENCUT",
- "KPLEN",
- "RELAX",
- "BANDSTRUCT",
- "OPTICS",
- "MBJOPTICS",
- "ELASTIC",
-]
-incs = GenericIncars().optb88vdw().incar.to_dict()
-
-for id in ids:
- mat = Poscar.from_file(id)
- cwd_home = os.getcwd()
- dir_name = id.split('.vasp')[0] + "_" + str("PBEBO")
- if not os.path.exists(dir_name):
- os.makedirs(dir_name)
+
+structures = ["POSCAR-1.vasp", "POSCAR-2.vasp", "POSCAR-3.vasp"]
+
+vasp_cmd = "mpirun /path/to/vasp_std"
+copy_files = ["/path/to/vdw_kernel.bindat"]
+submit_cmd = ["qsub", "submit_job"] # use ["sbatch", "submit_job"] for SLURM
+
+steps = ["ENCUT", "KPLEN", "RELAX", "BANDSTRUCT", "OPTICS", "MBJOPTICS", "ELASTIC"]
+incs = GenericIncars().optb88vdw().incar.to_dict()
+
+home = os.getcwd()
+for poscar_file in structures:
+ mat = Poscar.from_file(poscar_file)
+ dir_name = poscar_file.split(".vasp")[0] + "_PBEBO"
+ os.makedirs(dir_name, exist_ok=True)
os.chdir(dir_name)
+
job = JobFactory(
vasp_cmd=vasp_cmd,
poscar=mat,
@@ -420,7 +338,6 @@ for id in ids:
copy_files=copy_files,
use_incar_dict=incs,
)
-
dumpjson(data=job.to_dict(), filename="job_fact.json")
write_jobfact(
pyname="job_fact.py",
@@ -428,399 +345,321 @@ for id in ids:
input_arg="v.step_flow()",
)
- # Example job commands, need to change based on your cluster
- job_line = (
- "source activate my_jarvis \n"
- + "python job_fact.py"
- )
- name = id
- directory = os.getcwd()
+ job_line = "source activate my_jarvis\npython job_fact.py"
Queue.pbs(
job_line=job_line,
- jobname=name,
- #partition="",
+ jobname=poscar_file,
walltime="24:00:00",
- #account="",
cores=12,
- directory=directory,
- submit_cmd=submit_cmd,
- )
- os.chdir(cwd_home)
- """
- # For Slurm clusters
- Queue.slurm(
- job_line=job_line,
- jobname=name,
- directory=directory,
+ directory=os.getcwd(),
submit_cmd=submit_cmd,
)
- os.chdir(cwd_home)
- """
-```
-
-We provide modules to convert the calculation informato to `XML` which
-can be converted to `HTML` using `XSLT`. An example is give below:
+ # SLURM equivalent:
+ # Queue.slurm(job_line=job_line, jobname=poscar_file,
+ # directory=os.getcwd(), submit_cmd=["sbatch", "submit_job"])
-``` python
-from jarvis.db.vasp_to_xml import VaspToApiXmlSchema
-from jarvis.db.restapi import Api
-folder="jarvis/jarvis/examples/vasp/SiOptB88vdW"
-filename = "JVASP-1002.xml"
-VaspToApiXmlSchema(folder=folder).write_xml(filename=filename)
+ os.chdir(home)
```
-### How to plot electronic bandstructure and DOS
+Convert a finished calculation tree to JARVIS-API XML (and from there
+to HTML via XSLT):
-If you use the workflow used above, the density of states plot can be
-obtained using thr `vasprun.xml` file in MAIN-RELAX folder while the
-band-structure plot is obtained using `vasprun.xml` in MAIN-BAND folder.
+```python
+from jarvis.db.vasp_to_xml import VaspToApiXmlSchema
-``` python
-from jarvis.io.vasp.outputs import Vasprun
-vrun = Vasprun('vasprun.xml')
-%matplotlib inline
-import matplotlib.pyplot as plt
-plt.rcParams.update({'font.size': 22})
-
-# Bandstructure plot
-vrun.get_bandstructure(kpoints_file_path='KPOINTS')
-
-# DOS plot
-energies, spin_up, spin_dn=vrun.total_dos
-plt.rcParams.update({'font.size': 22})
-plt.plot(energies,spin_up,label='Spin-up')
-plt.plot(energies,spin_dn,label='Spin-down')
-plt.xlabel('Energy(E-Ef)')
-plt.ylabel('DOS(arb.unit)')
-plt.xlim(-4,4)
-plt.legend()
+VaspToApiXmlSchema(folder="jarvis/jarvis/examples/vasp/SiOptB88vdW").write_xml(
+ filename="JVASP-1002.xml",
+)
```
-### How to obtain elastic constants
-
-### How to plot generate an STM/STEM image
-
-### How to plot generate a dielectric function spectra and solar eff.
-
-### How to generate/use electronic Wannier tight binding model
+### Band structure and DOS
-### How to generate Fermi-surfaces
+After the workflow above, the band structure and DOS come from the
+`vasprun.xml` files in the `MAIN-BAND` and `MAIN-RELAX` folders
+respectively.
-### How to run BoltzTrap for transport properties
+```python
+import matplotlib.pyplot as plt
+from jarvis.io.vasp.outputs import Vasprun
-### How to make heterostructures/interfaces
+vrun = Vasprun("vasprun.xml")
+plt.rcParams.update({"font.size": 22})
-### How to get IR/Raman spectra
+# Band structure
+vrun.get_bandstructure(kpoints_file_path="KPOINTS")
-### How to get piezoelectic/dielecrric/BEC constants
+# DOS
+energies, spin_up, spin_dn = vrun.total_dos
+plt.plot(energies, spin_up, label="Spin up")
+plt.plot(energies, spin_dn, label="Spin down")
+plt.xlabel(r"$E - E_\mathrm{F}$ (eV)")
+plt.ylabel("DOS (arb. units)")
+plt.xlim(-4, 4)
+plt.legend()
+```
-### How to get electric field gradients
+### Other VASP analyses
-### How to get work-function of a surface
+The following workflows are available but not yet documented in this
+guide. Consult the corresponding modules under `jarvis.analysis` and
+`jarvis.io.vasp.outputs` for usage:
-### How to get exfoliation energy of a 2D material
+- elastic constants
+- STM / STEM image generation
+- dielectric function and solar-cell efficiency
+- electronic Wannier tight-binding models
+- Fermi surfaces
+- BoltzTraP transport properties
+- heterostructures and interfaces
+- IR / Raman spectra
+- piezoelectric, dielectric, Born effective charge constants
+- electric-field gradients
+- surface work functions
+- 2D-material exfoliation energies
-## How to run/analyze MD static/dynamic calculation using LAMMPS
+## Classical MD with LAMMPS
-Molecular dynamics/classical force-field calculations can be carried out
-with LAMMPS software as in JARVIS-FF. An example for running LAMMPS is
-given below. Here, a `LammpsJob` module is defined with the help of
-atoms, pair-style, coefficient, and template file (\*.mod file) to
-control the calculations.
+JARVIS-Tools wraps LAMMPS through `LammpsJob`, which takes an `Atoms`
+object, a pair-style and coefficient, and a control file
+(`*.mod` template).
-### How to run calculation
+### Run a calculation
-``` python
+```python
from jarvis.tasks.lammps.lammps import LammpsJob, JobFactory
from jarvis.core.atoms import Atoms
from jarvis.db.figshare import get_jid_data
from jarvis.analysis.structure.spacegroup import Spacegroup3D
+# Pull aluminum FCC from JARVIS-DFT
+atoms = Atoms.from_dict(get_jid_data(jid="JVASP-816", dataset="dft_3d")["atoms"])
+cvn_atoms = Spacegroup3D(atoms).conventional_standard_structure
-# atoms = Atoms.from_poscar('POSCAR')
-# Get Aluminum FCC from JARVIS-DFT database
-tmp_dict = get_jid_data(jid="JVASP-816", dataset="dft_3d")["atoms"]
-atoms = Atoms.from_dict(tmp_dict)
-
-# Get conventional cell
-spg = Spacegroup3D(atoms)
-cvn_atoms = spg.conventional_standard_structure
-
-# Set-up path to force-field/potential file, .mod file. and lammps executable
-ff = "/users/knc6/Software/LAMMPS/lammps-master/potentials/Al_zhou.eam.alloy"
+ff = "/users/knc6/Software/LAMMPS/lammps-master/potentials/Al_zhou.eam.alloy"
mod = "/users/knc6/Software/Devs/jarvis/jarvis/tasks/lammps/templates/inelast.mod"
cmd = "/users/knc6/Software/LAMMPS/lammps-master/src/lmp_serialout"
+
parameters = {
- "pair_style": "eam/alloy",
- "pair_coeff": ff,
- "atom_style": "charge",
+ "pair_style": "eam/alloy",
+ "pair_coeff": ff,
+ "atom_style": "charge",
"control_file": mod,
}
-
-# Test LammpsJob
-lmp = LammpsJob(
- atoms=cvn_atoms, parameters=parameters, lammps_cmd=cmd, jobname="Test"
+LammpsJob(
+ atoms=cvn_atoms, parameters=parameters, lammps_cmd=cmd, jobname="Test",
).runjob()
-# Test in a high-throughput
+# High-throughput equivalent
job_fact = JobFactory(pair_style="eam/alloy", name="my_first_lammps_run")
job_fact.all_props_eam_alloy(atoms=cvn_atoms, ff_path=ff, lammps_cmd=cmd)
```
-### How to analyze data
+### Parse and export
-An example to parse LAMMPS calculation folder using the above workflow
-is shown below:
-
-``` python
+```python
from jarvis.io.lammps.outputs import parse_material_calculation_folder
-folder = '/home/users/knc6/Software/jarvis/jarvis/examples/lammps/Aleam'
-data = parse_material_calculation_folder(folder)
-print (data)
-```
-
-The calculation data can now be converted into XML files as follows. The
-XML with the help of XSLT is converted into an HTML page.
-
-``` python
from jarvis.db.lammps_to_xml import write_xml
-write_xml(data=data,filename='JLMP-123.xml')
+
+data = parse_material_calculation_folder(
+ "/home/users/knc6/Software/jarvis/jarvis/examples/lammps/Aleam"
+)
+write_xml(data=data, filename="JLMP-123.xml")
```
-## How to run/analyze DFT static calculation using Quantum espresso
+The XML is converted to HTML via XSLT for web display.
-Quantum ESPRESSO is a suite for first-principles electronic-structure
-calculations and materials modeling, distributed for free and as free
-software under the GNU General Public License. It is based on
-density-functional theory, plane wave basis sets, and pseudopotentials.
+## DFT calculations with Quantum ESPRESSO
-### How to setup a single calculation
+Quantum ESPRESSO is a free, GPL-licensed suite for first-principles
+electronic-structure calculations using DFT, plane-wave basis sets, and
+pseudopotentials.
-An example for running QE simulation is shown below:
+### A single calculation
-``` python
-from jarvis.core.kpoints import Kpoints3D
+```python
from jarvis.core.atoms import Atoms
+from jarvis.core.kpoints import Kpoints3D
+from jarvis.io.qe.inputs import QEinfile
+
box = [[2.715, 2.715, 0], [0, 2.715, 2.715], [2.715, 0, 2.715]]
coords = [[0, 0, 0], [0.25, 0.25, 0.25]]
elements = ["Si", "Si"]
Si = Atoms(lattice_mat=box, coords=coords, elements=elements)
-print(Si)
-kp = Kpoints3D().automatic_length_mesh(
- lattice_mat=Si.lattice_mat, length=20
-)
-qe = QEinfile(Si, kp)
-qe.write_file()
-kp = Kpoints3D().kpath(atoms=Si)
+
+# SCF input
+kp = Kpoints3D().automatic_length_mesh(lattice_mat=Si.lattice_mat, length=20)
qe = QEinfile(Si, kp)
-qe.write_file("qe.in2")
-sp = qe.atomic_species_string()
-sp = qe.atomic_cell_params()
-print("sp", sp)
-print(qe.input_params['system_params']['nat'])
+qe.write_file() # default filename
+
+# Band-structure input on a high-symmetry k-path
+kp_path = Kpoints3D().kpath(atoms=Si)
+QEinfile(Si, kp_path).write_file("qe.in2")
+
+print(qe.atomic_species_string())
+print(qe.atomic_cell_params())
+print("nat =", qe.input_params["system_params"]["nat"])
+```
+
+Then run from the shell:
+
+```bash
$PATH_TO_PWSCF/pw.x -i qe.in
```
-### How to setup high-throughput calculations
+## ML models with JARVIS-CFID (sklearn / LightGBM)
-## How to traing JARVIS-CFID ML models using sklearn/lightgbm
+JARVIS-Tools supports two main routes to atomistic ML models:
-There are several methods to train atomistic property ML models such as
-based on hand-crafted descritprs and graph neural network. Examples of
-such methods are: JARVIS-CFID (Classical Force-Field Inspired
-Descriptors) for descriptors based training and JARVIS-ALIGNN (Atomistic
-Line Graph Neural Network) based on GNNs. In this section we discuss the
-JARVIS-CFID ( `jarvis.ai.descriptors.cfid`), which can be used for
-training models with only chemical formula or chemical formula+structure
-information.
+- **JARVIS-CFID** (Classical Force-field Inspired Descriptors) —
+ hand-crafted descriptors usable with classical ML libraries. See
+ `jarvis.ai.descriptors.cfid`.
+- **JARVIS-ALIGNN** (Atomistic Line Graph Neural Network) — graph
+ neural networks for property prediction, distributed as a
+ separate `alignn` package.
-### How to train chemical formula only datasets
+This section covers CFID for both formula-only and formula+structure
+inputs.
-For each chemical formula, we can obtain 438
-descriptors consisting of features such as avergae
-electronegativity, average boiling points of elements etc. An example of
-getting descriptors isshown below:
+### Chemical-formula-only models
-``` python
+For each chemical formula, CFID produces 438 descriptors (average
+electronegativity, average boiling point, etc.). A toy training set:
+
+```python
import numpy as np
-from jarvis.core.composition import Composition
-from jarvis.core.specie import Specie
-from jarvis.ai.pkgs.lgbm.regression import regression
from jarvis.ai.descriptors.cfid import get_chem_only_descriptors
+from jarvis.ai.pkgs.lgbm.regression import regression
-# Load a dataset, you can use pandas read_csv also to generte my_data
-# Here is a sample dataset
my_data = [
- ["CoAl", 1],
- ["CoNi", 2],
- ["CoNb2Ni5", 3],
- ["Co1.2Al2.3NiRe2", 4],
- ["Co", 5],
- ["CoAlTi", 1],
- ["CoNiTi", 2],
- ["CoNb2Ni5Ti", 3],
- ["Co1.2Al2.3NiRe2Ti", 4],
- ["CoTi", 5],
- ["CoAlFe", 1],
- ["CoNiFe", 2],
- ["CoNb2Ni5Fe", 3],
- ["Co1.2Al2.3NiRe2Fe", 4],
- ["CoFe", 5],
+ ["CoAl", 1], ["CoNi", 2], ["CoNb2Ni5", 3],
+ ["Co1.2Al2.3NiRe2", 4], ["Co", 5], ["CoAlTi", 1],
+ ["CoNiTi", 2], ["CoNb2Ni5Ti", 3], ["Co1.2Al2.3NiRe2Ti", 4],
+ ["CoTi", 5], ["CoAlFe", 1], ["CoNiFe", 2],
+ ["CoNb2Ni5Fe", 3], ["Co1.2Al2.3NiRe2Fe", 4], ["CoFe", 5],
]
+X, Y, IDs = [], [], []
+for i, (formula, target) in enumerate(my_data):
+ X.append(get_chem_only_descriptors(formula))
+ Y.append(target)
+ IDs.append(i)
-# Convert my_data to numpy array
-X = []
-Y = []
-IDs = []
-for ii, i in enumerate(my_data):
- X.append(get_chem_only_descriptors(i[0]))
- Y.append(i[1])
- IDs.append(ii)
-
-X = np.array(X)
-Y = np.array(Y).reshape(-1, 1)
+X = np.array(X)
+Y = np.array(Y).reshape(-1, 1)
IDs = np.array(IDs)
```
-Now, we can use different ML algorithms on the descriptors and dataset
-such as linear regression, random forest, gradient boosting etc.
+Now train a LightGBM regressor through the JARVIS-Tools wrapper, which
+also handles feature pre-processing:
-An example, for using LightGBM with jarvis-tools wrapper code is shown
-below:
-
-``` python
-# Train a LightGBM regression model
+```python
config = {"n_estimators": 5, "learning_rate": 0.01, "num_leaves": 2}
-# The regression module does feature pre-processing as well
-# Change config settings to improve model such as by hyper-parameter tuning
info = regression(X=X, Y=Y, jid=IDs, feature_importance=False, config=config)
-
-# Print performance metrices
-# Print performance metrices
print(
- 'r2=',info["reg_scores"]["r2"],
- 'MAE=',info["reg_scores"]["mae"],
- 'RMSE=',info["reg_scores"]["rmse"],
+ "r2 =", info["reg_scores"]["r2"],
+ "MAE =", info["reg_scores"]["mae"],
+ "RMSE=", info["reg_scores"]["rmse"],
)
```
-### How to train regression model
-
-Suppose we have 60000 materials, and we get 1557 descriptor for each
-material (438 chemical as above as well as structure and charge
-descriptors), we will have a 60000x1557 matrix. Let's call this matrix
-as 'x' or input matrix. Next, we can get target ('y') data either from
-DFT, FF calculations or experiments. For example, we can choose
-formation energies of 60000 materials in the JARVIS-DFT as the dtarget
-data giving 60000x1 matrix.
-
-Now, we can use a ML/AI algorithm to establish statistical relation
-between the x and y data. Once trained we get a trained model, which can
-be stored in say pickle or joblib format.
-
-For a new material now, it can be converted into CFID i.e. 1x1557 matrix
-which when fed to the model will give 1x1 prediction hence the ML
-prediction. We can use a range of ML algorithms such as linear
-regression, decision trees, Gaussian processes etc. We find with CFID
-descriptors, gradient boosting decision trees (especially in LightGBM)
-gives one of the most accurate results. We provide tools to run with
-major ML packages such as scikit-learn, tensorflow, pytorch, lightgbm
-etc. Example-1:
-
-``` python
-# An example of JARVIS-ML training
-from jarvis.ai.pkgs.utils import get_ml_data
-from jarvis.ai.pkgs.utils import regr_scores
-X,y,jid=get_ml_data()
-#Formation energy for 3D materials, you can choose other properties/dataset as well
+### Formula + structure regression
+
+For 60,000 materials, CFID produces a 1,557-dimensional descriptor per
+material (438 chemical + structural and charge descriptors), giving a
+60,000 × 1,557 input matrix. Pair this with a target — for example
+formation energies from JARVIS-DFT — and train any regressor.
+
+We find that gradient-boosted decision trees (LightGBM in particular)
+work especially well with CFID. JARVIS-Tools ships wrappers for
+scikit-learn, TensorFlow, PyTorch, and LightGBM.
+
+```python
+from jarvis.ai.pkgs.utils import get_ml_data, regr_scores
import lightgbm as lgb
from sklearn.model_selection import train_test_split
-lgbm = lgb.LGBMRegressor(device= 'gpu',n_estimators= 1170,learning_rate= 0.15375236057119931,num_leaves= 273)
-X_train, X_test, y_train, y_test, jid_train, jid_test = train_test_split(X, y, jid, random_state=1, test_size=.1)
-lgbm.fit(X_train,y_train)
-pred = lgbm.predict(X_test)
-reg_sc = regr_scores(y_test, pred)
-print (reg_sc['mae'])
+
+# Default target: formation energy for 3D materials.
+X, y, jid = get_ml_data()
+
+X_train, X_test, y_train, y_test, _, _ = train_test_split(
+ X, y, jid, random_state=1, test_size=0.1,
+)
+
+lgbm = lgb.LGBMRegressor(
+ device="gpu",
+ n_estimators=1170,
+ learning_rate=0.15375236057119931,
+ num_leaves=273,
+)
+lgbm.fit(X_train, y_train)
+print("MAE =", regr_scores(y_test, lgbm.predict(X_test))["mae"])
```
-## How to traing JARVIS-ALIGNN ML models using PyTorch
-
-### How to train regression model
-
-How to train classification model ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-## How to use quantum computation algorithms using Qiskit/Tequila/Pennylane
-
-Quantum chemistry is one of the most attractive applications for quantum
-computations. Predicting the energy levels of a Hamiltonian is a key
-problem in quantum chemistry. Variational quantum eigen solver (VQE) is
-one of the most celebrated methods for predicting an approximate ground
-state of a Hamiltonian on a quantum computer following the variational
-principles of quantum mechanics.VQE utilizes Ritz variational principle
-where a quantum computer is used to prepare a wave function ansatz of
-the system and estimate the expectation value of its electronic
-Hamiltonian while a classical optimizer is used to adjust the quantum
-circuit parameters in order to find the ground state energy. A typical
-VQE task is carried out as follows: an ansatz/circuit model with tunable
-parameters is constructed and a quantum circuit capable of representing
-this ansatz is designed. In this section, we show a few examples to
-apply quantum algorithms for solids using Wannier-tight binding
-Hamiltonians (WTBH). WTBHs can be generated from several DFT codes.
-Here, we use JARVIS-WTBH database.
-
-### How to generate circuit model
-
-Developing a heuristic quantum circuit model is probably the most
-challenging part of applying quantum algorithms. Fortunately, there are
-few well-known generalized models that we can use or generate ourselves.
-There are several circuit models (for a fixed number of qubits and
-repeat units) available in `jarvis.core.circuits.`. In the following
-example, we use circuit6/EfficientSU2 model and use it to predict
-electronic energy levels (at a K-point in the Brillouin zone) of FCC
-Aluminum using a WTBH.
-
-``` python
-from jarvis.db.figshare import get_wann_electron, get_wann_phonon, get_hk_tb
+## ML models with JARVIS-ALIGNN (PyTorch)
+
+ALIGNN training and inference live in the standalone
+[`alignn`](https://github.com/usnistgov/alignn) package; see its
+documentation for regression and classification workflows.
+
+## Quantum computing with Qiskit / Tequila / PennyLane
+
+Quantum chemistry — and, in JARVIS, condensed-matter electronic-structure
+problems via Wannier tight-binding Hamiltonians (WTBH) — is one of the
+most promising applications of quantum computers. The Variational
+Quantum Eigensolver (VQE) is a standard hybrid quantum-classical
+algorithm for ground-state estimation: a parameterized quantum circuit
+("ansatz") prepares a trial state, the quantum device measures the
+expectation value of the Hamiltonian, and a classical optimizer updates
+the circuit parameters to minimize the energy.
+
+This section runs VQE on a WTBH from the JARVIS-WTBH database. WTBHs can
+be generated by several DFT codes; here we use the JARVIS-WTBH dataset
+directly.
+
+### Build a circuit and run VQE
+
+A handful of standard ansatz templates live in `jarvis.core.circuits`.
+The example below uses circuit-6 (EfficientSU2) to predict electronic
+energy levels of FCC aluminum at the X-point in the Brillouin zone.
+
+```python
+from qiskit import Aer
+from jarvis.db.figshare import get_wann_electron, get_hk_tb
from jarvis.io.qiskit.inputs import HermitianSolver
from jarvis.core.circuits import QuantumCircuitLibrary
-from qiskit import Aer
backend = Aer.get_backend("statevector_simulator")
-# Aluminum JARVIS-ID: JVASP-816
-wtbh, Ef, atoms = get_wann_electron("JVASP-816")
-kpt = [0.5, 0., 0.5] # X-point
-hk = get_hk_tb(w=wtbh, k=kpt)
-HS = HermitianSolver(hk)
-n_qubits = HS.n_qubits()
-circ = QuantumCircuitLibrary(n_qubits=n_qubits).circuit6()
-en, vqe_result, vqe = HS.run_vqe(var_form=circ, backend=backend)
-vals,vecs = HS.run_numpy()
-# Ef: Fermi-level
-print('Classical, VQE (eV):', vals[0]-Ef, en-Ef)
-print('Show model\n', circ)
-```
-### How to run cals. on simulators
+# Aluminum, JARVIS-ID JVASP-816
+wtbh, Ef, atoms = get_wann_electron("JVASP-816")
+hk = get_hk_tb(w=wtbh, k=[0.5, 0.0, 0.5]) # X-point
+
+solver = HermitianSolver(hk)
+circuit = QuantumCircuitLibrary(n_qubits=solver.n_qubits()).circuit6()
+
+en, vqe_result, vqe = solver.run_vqe(var_form=circuit, backend=backend)
+vals, vecs = solver.run_numpy()
+
+print("Classical, VQE (eV):", vals[0] - Ef, en - Ef)
+print("Circuit:")
+print(circuit)
+```
-In the above example, we run simulations on `statevector_simulator`.
-Qiskit provides several other simulators, which can also be used.
+### Run on a real quantum device
-### How to run cals. on actual quantum computers
+Replace the simulator backend with an IBM Quantum device:
-To run calculations on real quantum computers, we just replace the
-`backend` parameter above such as the following:
+```python
+import qiskit
+from qiskit import IBMQ
-``` python
-token='Get Token from your IBM account'
+token = ""
qiskit.IBMQ.save_account(token)
provider = IBMQ.load_account()
-backend = provider.get_backend('ibmq_5_yorktown')
+backend = provider.get_backend("ibmq_5_yorktown")
```
-Your job will put in a queue and as the simulation complete result will
-be sent back to you. Note that there might be a lot of jobs in the queue
-already, so it might take a while. You may run simulations using IBM GUI
-or use something like Jupyter notebook/Colab notebook.
+The job is queued; results are returned when execution finishes. Wait
+times depend on device load.
diff --git a/environment.yml b/environment.yml
index f35d8c1f..11ee7ae3 100644
--- a/environment.yml
+++ b/environment.yml
@@ -246,10 +246,10 @@ dependencies:
- python-dateutil==2.8.2
- pyyaml==6.0.1
- pyyaml-env-tag==0.1
- - qiskit==0.41.1
- - qiskit-aer==0.11.2
- - qiskit-ibmq-provider==0.20.1
- - qiskit-terra==0.23.2
+ - qiskit>=2.3.1
+ - qiskit-aer>=0.17.2
+ - qiskit_algorithms>=0.4.1
+ - rustworkx
- regex==2023.12.25
- requests==2.28.2
- requests-ntlm==1.1.0
@@ -257,8 +257,8 @@ dependencies:
- scikit-learn==1.4.1.post1
- scipy==1.12.0
- semantic-version==2.6.0
- - spglib==2.3.1
- - stevedore==5.2.0
+ - spglib==2.7.0
+ - stevedore==5.7.0
- symengine==0.11.0
- sympy==1.12
- threadpoolctl==3.3.0
diff --git a/jarvis/__init__.py b/jarvis/__init__.py
index 7536edbb..621071ed 100644
--- a/jarvis/__init__.py
+++ b/jarvis/__init__.py
@@ -1,6 +1,6 @@
"""Version number."""
-__version__ = "2026.4.2"
+__version__ = "2026.6.12"
import os
diff --git a/jarvis/core/atoms.py b/jarvis/core/atoms.py
index d12ebe4b..4c581e45 100644
--- a/jarvis/core/atoms.py
+++ b/jarvis/core/atoms.py
@@ -1361,17 +1361,19 @@ def pymatgen_converter(self):
def phonopy_converter(self, pbc=True):
"""Get phonopy representation of the atoms object."""
try:
- from phonopy.structure.atoms import Atoms as PhonopyAtoms
-
- return PhonopyAtoms(
- symbols=self.elements,
- positions=self.cart_coords,
- pbc=pbc,
- cell=self.lattice_mat,
- )
+ from phonopy.structure.atoms import PhonopyAtoms
except Exception:
print("Requires phonopy for this functionality.")
- pass
+ return
+ kw = dict(
+ symbols=self.elements,
+ positions=self.cart_coords,
+ cell=self.lattice_mat,
+ )
+ try:
+ return PhonopyAtoms(pbc=pbc, **kw) # phonopy < 4
+ except TypeError:
+ return PhonopyAtoms(**kw) # phonopy >= 4 dropped pbc=
def ase_converter(self, pbc=True):
"""Get ASE representation of the atoms object."""
diff --git a/jarvis/core/specie.py b/jarvis/core/specie.py
index f2a767e8..058c050d 100644
--- a/jarvis/core/specie.py
+++ b/jarvis/core/specie.py
@@ -316,14 +316,11 @@ def get_node_attributes(species, atom_features="atomic_number"):
# For alternative features use
# get_digitized_feats_hot_encoded()
i = json.load(f)
- try:
- return i[key]
- except KeyError:
- print(f"warning: could not load CGCNN features for {key}")
- print("Setting it to max atomic number available here, 103")
- # TODO Check for the error in oqmd_3d_no_cfid dataset
- # return i['Lr']
- return i["100"]
+ # cgcnn.json defines elements 1-100; species outside that set
+ # (trans-fermium placeholders, or an unrecognized 'nan' symbol)
+ # fall back to element 100's features silently -- these never occur
+ # in real structures, so the old print was pure noise.
+ return i.get(key, i["100"])
keys = [
diff --git a/jarvis/db/figshare.py b/jarvis/db/figshare.py
index 38d5dc36..69e5774e 100644
--- a/jarvis/db/figshare.py
+++ b/jarvis/db/figshare.py
@@ -40,9 +40,9 @@ def get_db_info():
],
# https://doi.org/10.6084/m9.figshare.6815699
"dft_3d": [
- "https://ndownloader.figshare.com/files/38521619",
- "jdft_3d-12-12-2022.json",
- "Obtaining 3D dataset 76k ...",
+ "https://ndownloader.figshare.com/files/64391379",
+ "jdft_3d-9-24-2025.json",
+ "Obtaining 3D dataset 94k ...",
"https://doi.org/10.1016/j.commatsci.2025.114063"
# "https://www.nature.com/articles/s41524-020-00440-1"
+ "\nOther versions:https://doi.org/10.6084/m9.figshare.6815699",
@@ -55,6 +55,15 @@ def get_db_info():
"https://www.nature.com/articles/s41524-020-00440-1",
],
# https://doi.org/10.6084/m9.figshare.6815699
+ "dft_3d_2022": [
+ "https://ndownloader.figshare.com/files/38521619",
+ "jdft_3d-12-12-2022.json",
+ "Obtaining 3D dataset 76k ...",
+ "https://doi.org/10.1016/j.commatsci.2025.114063"
+ # "https://www.nature.com/articles/s41524-020-00440-1"
+ + "\nOther versions:https://doi.org/10.6084/m9.figshare.6815699",
+ ],
+ # https://doi.org/10.6084/m9.figshare.6815699
"dft_3d_2021": [
"https://ndownloader.figshare.com/files/29204826",
"jdft_3d-8-18-2021.json",
@@ -86,6 +95,84 @@ def get_db_info():
"Obtaining ALIGNN-FF training DB 300k ...",
"https://doi.org/10.1039/D2DD00096B",
],
+ # ALIGNN2 datasets (Figshare project 279395)
+ # https://doi.org/10.6084/m9.figshare.33325302
+ "alignn_ff_db2": [
+ "https://ndownloader.figshare.com/files/67810098",
+ "fd_id_prop.json",
+ "Obtaining ALIGNN-FF finite-difference (FD) training DB 1.18M ...",
+ "https://doi.org/10.6084/m9.figshare.33325302",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325272
+ "dfpt_tensors": [
+ "https://ndownloader.figshare.com/files/67810035",
+ "dfpt.json",
+ "Obtaining JARVIS-DFT DFPT tensors (Born charges, dielectric, piezo) ...",
+ "https://doi.org/10.6084/m9.figshare.33325272",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325275
+ "a2f": [
+ "https://ndownloader.figshare.com/files/67810083",
+ "a2f_id_prop.json",
+ "Obtaining Eliashberg alpha^2F(omega) spectral-function dataset ...",
+ "https://doi.org/10.6084/m9.figshare.33325275",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325278
+ "elastic_tensor": [
+ "https://ndownloader.figshare.com/files/67810041",
+ "id_prop_elastic.json",
+ "Obtaining JARVIS-DFT elastic stiffness tensor (Cij, 6x6) ...",
+ "https://doi.org/10.6084/m9.figshare.33325278",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325281
+ "multitask_eps": [
+ "https://ndownloader.figshare.com/files/67810086",
+ "eps_id_prop.json",
+ "Obtaining JARVIS-DFT multitask dielectric (eps) dataset ...",
+ "https://doi.org/10.6084/m9.figshare.33325281",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325284
+ "chg_mag": [
+ "https://ndownloader.figshare.com/files/67810089",
+ "chg_mag_id_prop.json",
+ "Obtaining JARVIS-DFT per-atom charge (Bader) + magnetic-moment ...",
+ "https://doi.org/10.6084/m9.figshare.33325284",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325287
+ "ir_alignn": [
+ "https://ndownloader.figshare.com/files/67810092",
+ "ir_id_prop.json",
+ "Obtaining JARVIS-DFT DFPT infrared (IR) spectra dataset ...",
+ "https://doi.org/10.6084/m9.figshare.33325287",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325290
+ "raman_alignn": [
+ "https://ndownloader.figshare.com/files/67810095",
+ "raman_id_prop.json",
+ "Obtaining JARVIS Raman spectra dataset (ALIGNN2 form) ...",
+ "https://doi.org/10.6084/m9.figshare.33325290",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325293
+ "edos_alignn": [
+ "https://ndownloader.figshare.com/files/67810056",
+ "edos.json",
+ "Obtaining JARVIS-DFT electronic DOS (300-bin) dataset ...",
+ "https://doi.org/10.6084/m9.figshare.33325293",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33325299
+ "pdos_alignn": [
+ "https://ndownloader.figshare.com/files/67810062",
+ "pdos.json",
+ "Obtaining JARVIS-DFT phonon DOS (200-bin) dataset ...",
+ "https://doi.org/10.6084/m9.figshare.33325299",
+ ],
+ # https://doi.org/10.6084/m9.figshare.33336759
+ "ltc_alignn": [
+ "https://ndownloader.figshare.com/files/67841763",
+ "ltc_id_prop.json",
+ "Obtaining lattice thermal conductivity (log10 kappa_L) dataset on OQMD structures ...",
+ "https://doi.org/10.6084/m9.figshare.33336759",
+ ],
"mp_3d_2020": [
"https://ndownloader.figshare.com/files/26791259",
"all_mp.json",
@@ -99,6 +186,12 @@ def get_db_info():
"Obtaining MEGNET-3D CFID dataset 69k...",
"https://pubs.acs.org/doi/10.1021/acs.chemmater.9b01294",
],
+ "matpes": [
+ "https://ndownloader.figshare.com/files/66983876",
+ "matpes.json",
+ "Obtaining MATPES-PBE dataset 434k...",
+ "https://matpes.ai",
+ ],
# https://doi.org/10.6084/m9.figshare.14745435
"megnet2": [
"https://ndownloader.figshare.com/files/28332741",
@@ -172,7 +265,7 @@ def get_db_info():
],
# https://doi.org/10.6084/m9.figshare.14912820.v1
"cod_200": [
- "https://figshare.com/ndownloader/files/63463986",
+ "https://ndownloader.figshare.com/files/63463986",
"cod_200.json",
"Obtaining COD dataset 237k",
"https://doi.org/10.1107/S1600576720016532",
diff --git a/jarvis/io/qiskit/inputs.py b/jarvis/io/qiskit/inputs.py
index 8a1361b9..d55afb8e 100644
--- a/jarvis/io/qiskit/inputs.py
+++ b/jarvis/io/qiskit/inputs.py
@@ -1,56 +1,140 @@
-"""Module to solve Hermitian Matrix and predict badstructures."""
-# Reference: https://doi.org/10.1088/1361-648X/ac1154
+"""Module to solve Hermitian Matrix and predict bandstructures.
+
+Migrated to Qiskit >= 1.2 / 2.x + qiskit-algorithms.
+Supports: statevector simulator, Aer simulators, and IBM Quantum hardware.
+
+Reference: https://doi.org/10.1088/1361-648X/ac1154
+
+Install:
+ pip install "qiskit>=1.2" qiskit-aer qiskit-algorithms
+ pip install qiskit-ibm-runtime # for hardware
+"""
import numpy as np
-import itertools
-import functools
-from qiskit_aer import Aer
-from qiskit.utils import QuantumInstance, algorithm_globals
-from qiskit.opflow import I, X, Y, Z
-from qiskit.algorithms import VQE
+import matplotlib.pyplot as plt
+
+from qiskit.quantum_info import SparsePauliOp, Operator
+from qiskit.circuit.library import EfficientSU2
+from qiskit_algorithms import VQE
+from qiskit_algorithms.optimizers import SLSQP
+
from jarvis.core.kpoints import Kpoints3D as Kpoints
from jarvis.db.figshare import get_hk_tb
from jarvis.core.kpoints import generate_kgrid
-import matplotlib.pyplot as plt
plt.switch_backend("agg")
-# from qiskit.algorithms.optimizers import SLSQP
+
+
+def _get_estimator(backend="statevector_simulator", seed=50, ibm_token=None):
+ """Create the appropriate V2 Estimator for the requested backend.
+
+ Parameters
+ ----------
+ backend : str
+ "statevector_simulator", "aer_simulator*", or an IBM backend name
+ like "ibm_kingston", "ibm_brisbane", etc.
+ seed : int
+ Random seed for reproducibility.
+ ibm_token : str, optional
+ IBM Quantum API token. Required for IBM hardware backends if
+ not already saved via QiskitRuntimeService.save_account().
+ """
+ if backend == "statevector_simulator":
+ from qiskit.primitives import StatevectorEstimator
+
+ return StatevectorEstimator(seed=seed)
+
+ elif backend.startswith("aer"):
+ from qiskit_aer import AerSimulator
+ from qiskit_aer.primitives import EstimatorV2 as AerEstimator
+
+ method_map = {
+ "aer_simulator": "automatic",
+ "aer_simulator_statevector": "statevector",
+ "aer_simulator_density_matrix": "density_matrix",
+ "aer_simulator_mps": "matrix_product_state",
+ }
+ method = method_map.get(backend, "automatic")
+ aer_backend = AerSimulator(method=method, seed_simulator=seed)
+ return AerEstimator.from_backend(aer_backend)
+
+ else:
+ # IBM hardware backend
+ try:
+ from qiskit_ibm_runtime import (
+ QiskitRuntimeService,
+ EstimatorV2 as RuntimeEstimator,
+ )
+
+ if ibm_token:
+ # Try new IBM Cloud channel first; fall back to ibm_quantum
+ try:
+ QiskitRuntimeService.save_account(
+ channel="ibm_cloud",
+ token=ibm_token,
+ overwrite=True,
+ set_as_default=True,
+ )
+ except Exception:
+ QiskitRuntimeService.save_account(
+ channel="ibm_quantum",
+ token=ibm_token,
+ overwrite=True,
+ set_as_default=True,
+ )
+ service = QiskitRuntimeService()
+ hw_backend = service.backend(backend)
+ return RuntimeEstimator(hw_backend)
+ except ImportError:
+ raise ImportError(
+ f"Backend '{backend}' requires qiskit-ibm-runtime. "
+ "Install: pip install qiskit-ibm-runtime"
+ )
+ except Exception as e:
+ raise ValueError(f"Could not initialize backend '{backend}': {e}")
+
+
+# Available backends for API/frontend enumeration
+AVAILABLE_BACKENDS = [
+ {
+ "id": "statevector_simulator",
+ "name": "Statevector (exact)",
+ "desc": "Exact statevector simulation, no noise",
+ },
+ {
+ "id": "aer_simulator",
+ "name": "Aer (automatic)",
+ "desc": "Aer simulator with automatic method selection",
+ },
+ {
+ "id": "aer_simulator_statevector",
+ "name": "Aer Statevector",
+ "desc": "Aer with statevector method",
+ },
+ {
+ "id": "aer_simulator_density_matrix",
+ "name": "Aer Density Matrix",
+ "desc": "Aer with density matrix method (supports noise)",
+ },
+ {
+ "id": "aer_simulator_mps",
+ "name": "Aer MPS",
+ "desc": "Aer with matrix product state (larger qubit counts)",
+ },
+]
def decompose_Hamiltonian(H):
"""Decompose Hermitian matrix into Pauli basis."""
- # Inspired from
- # https://github.com/PennyLaneAI/pennylane/blob/master/pennylane/utils.py#L45
- # https://qiskit.org/documentation/tutorials/algorithms/04_vqe_advanced.html
- x, y = H.shape
- N = int(np.log2(len(H)))
- if len(H) - 2 ** N != 0 or x != y:
- raise ValueError(
- "Hamiltonian should be in the form (2^n x 2^n), for any n>=1"
- )
- pauilis = [I, X, Y, Z]
- decomposedH = 0
- for term in itertools.product(pauilis, repeat=N):
- matrices = [i.to_matrix() for i in term]
- # coefficient of the pauli string = (1/2^N) * (Tr[pauliOp x H])
- coeff = np.trace(functools.reduce(np.kron, matrices) @ H) / (2 ** N)
- coeff = np.real_if_close(coeff).item()
- if coeff == 0:
- continue
- obs = 1
- for i in term:
- obs = obs ^ i
- decomposedH += coeff * obs
- return decomposedH
+ return SparsePauliOp.from_operator(Operator(H)).simplify()
class HermitianSolver(object):
"""Solve a Hermitian matrix using quantum algorithms."""
def __init__(self, mat=[], verbose=False):
- """Initialize with a numpy Hermitian matrix."""
N = int(np.ceil(np.log2(len(mat))))
- hk = np.zeros((2 ** N, 2 ** N), dtype="complex")
+ hk = np.zeros((2**N, 2**N), dtype="complex")
hk[: mat.shape[0], : mat.shape[1]] = mat
self.mat = hk
self.verbose = verbose
@@ -58,32 +142,32 @@ def __init__(self, mat=[], verbose=False):
raise ValueError("Only implemented for Hermitian matrix.")
def n_qubits(self):
- """Get number of qubits required."""
return int(np.log2(len(self.mat)))
def check_hermitian(self):
- """Check if a matrix is Hermitian."""
adjoint = self.mat.conj().T
return np.allclose(self.mat, adjoint)
def run_vqe(
self,
- backend=Aer.get_backend("statevector_simulator"),
+ backend="statevector_simulator",
var_form=None,
optimizer=None,
reps=None,
mode="min_val",
+ ibm_token=None,
):
- """Run variational quantum eigensolver."""
+ """Run variational quantum eigensolver.
+
+ Auto-transpiles the ansatz to ISA circuits when running on real
+ IBM hardware (required since March 2024).
+ """
seed = 50
- algorithm_globals.random_seed = seed
N = self.n_qubits()
- qi = QuantumInstance(
- Aer.get_backend("statevector_simulator"),
- seed_transpiler=seed,
- seed_simulator=seed,
+
+ estimator = _get_estimator(
+ backend=backend, seed=seed, ibm_token=ibm_token
)
- # n_qubits = self.n_qubits
if mode == "max_val":
Hamil_qop = decompose_Hamiltonian(-1 * self.mat)
@@ -99,15 +183,37 @@ def run_vqe(
if var_form is None:
if reps is None:
reps = 2
- # reps=5
- from qiskit.circuit.library import EfficientSU2
-
var_form = EfficientSU2(N, reps=reps)
+
if optimizer is None:
- vqe = VQE(var_form, quantum_instance=qi)
+ optimizer = SLSQP()
- else:
- vqe = VQE(var_form, optimizer=optimizer, quantum_instance=qi)
+ # ── ISA TRANSPILATION FOR REAL HARDWARE ──
+ is_hardware = not (
+ backend == "statevector_simulator" or backend.startswith("aer")
+ )
+ if is_hardware:
+ try:
+ from qiskit.transpiler.preset_passmanagers import (
+ generate_preset_pass_manager,
+ )
+ from qiskit_ibm_runtime import QiskitRuntimeService
+
+ service = QiskitRuntimeService()
+ hw_backend = service.backend(backend)
+ pm = generate_preset_pass_manager(
+ target=hw_backend.target, optimization_level=2
+ )
+ var_form = pm.run(var_form)
+ # Re-map observable to transpiled qubit layout
+ # Hamil_qop = Hamil_qop.apply_layout(var_form.layout)
+ except Exception as e:
+ raise RuntimeError(
+ f"Failed to transpile circ. backend '{backend}':{e}"
+ )
+
+ vqe = VQE(estimator, var_form, optimizer)
+ np.random.seed(seed)
result = vqe.compute_minimum_eigenvalue(operator=Hamil_qop)
en = result.eigenvalue
@@ -117,35 +223,15 @@ def run_vqe(
return en, result, vqe
def run_numpy(self):
- """Obtain eigenvalues and vecs using Numpy solvers."""
return np.linalg.eigh(self.mat)
- # def run_qpe(self, n_ancillae=8):
- # """Run quantum phase estimations."""
- # quantum_instance = aqua.QuantumInstance(
- # backend=Aer.get_backend("statevector_simulator"), shots=1
- # )
- # Hamil_mat = aqua.operators.MatrixOperator(self.mat)
- # # Hamil_mat = MatrixOperator(self.mat)
- # #Hamil_qop = aqua.operators.op_converter.to_weighted_pauli_operator(
- # # Hamil_mat
- # #)
- # # Hamil_qop = op_converter.to_weighted_pauli_operator(Hamil_mat)
-
- # Hamil_qop = decompose_Hamiltonian(self.mat)
- # qpe = aqua.algorithms.QPE(Hamil_qop, num_ancillae=n_ancillae)
- # qpe_result = qpe.run(quantum_instance)
- # # qc = qpe.construct_circuit(measurement=True)
- # print("qpe_result", qpe_result)
- # return qpe_result["eigenvalue"], qpe_result, qpe
-
def run_vqd(
self,
- backend=Aer.get_backend("statevector_simulator"),
+ backend="statevector_simulator",
var_form=None,
optimizer=None,
reps=2,
- # reps=5,
+ ibm_token=None,
):
"""Run variational quantum deflation."""
tmp = HermitianSolver(self.mat)
@@ -155,24 +241,64 @@ def run_vqd(
optimizer=optimizer,
reps=reps,
mode="max_val",
+ ibm_token=ibm_token,
)
+ # Try to get eigenstate (V2 result has optimal_circuit, not eigenstate)
+ try:
+ from qiskit.quantum_info import Statevector
+
+ if (
+ hasattr(vqe_result, "optimal_circuit")
+ and vqe_result.optimal_circuit is not None
+ ):
+ opt_c = vqe_result.optimal_circuit
+ if opt_c.num_parameters > 0 and hasattr(
+ vqe_result, "optimal_point"
+ ):
+ opt_c = opt_c.assign_parameters(
+ dict(zip(opt_c.parameters, vqe_result.optimal_point))
+ )
+ eigstate = np.array(Statevector(opt_c)).flatten()
+ else:
+ eigstate = np.array(vqe_result.eigenstate).flatten()
+ except Exception:
+ eigstate = np.zeros(len(tmp.mat), dtype=complex)
+
eigvals = [max_eigval]
- eigstates = [vqe_result.eigenstate]
- # eigvals = []
- # eigstates= []
+ eigstates = [eigstate]
+
for r in range(len(tmp.mat) - 1):
val, vqe_result, vqe = tmp.run_vqe(
backend=backend,
var_form=var_form,
optimizer=optimizer,
reps=reps,
+ ibm_token=ibm_token,
)
- outer_prod = np.outer(
- vqe_result.eigenstate, np.conj(vqe_result.eigenstate).T
- )
+ try:
+ if (
+ hasattr(vqe_result, "optimal_circuit")
+ and vqe_result.optimal_circuit is not None
+ ):
+ opt_c = vqe_result.optimal_circuit
+ if opt_c.num_parameters > 0 and hasattr(
+ vqe_result, "optimal_point"
+ ):
+ opt_c = opt_c.assign_parameters(
+ dict(
+ zip(opt_c.parameters, vqe_result.optimal_point)
+ )
+ )
+ eigstate = np.array(Statevector(opt_c)).flatten()
+ else:
+ eigstate = np.array(vqe_result.eigenstate).flatten()
+ except Exception:
+ eigstate = np.zeros(len(tmp.mat), dtype=complex)
+
+ outer_prod = np.outer(eigstate, np.conj(eigstate).T)
tmp.mat = tmp.mat - (val - max_eigval) * outer_prod
eigvals.append(val)
- eigstates.append(vqe_result.eigenstate)
+ eigstates.append(eigstate)
tmp = HermitianSolver(tmp.mat)
eigvals = np.array(eigvals)
@@ -188,7 +314,7 @@ def get_bandstruct(
atoms={},
ef=0,
line_density=1,
- ylabel="eV", # "Energy ($cm^{-1}$)",
+ ylabel="eV",
font=22,
var_form=None,
filename="bands.png",
@@ -198,6 +324,8 @@ def get_bandstruct(
tol=None,
factor=1,
verbose=False,
+ backend="statevector_simulator",
+ ibm_token=None,
):
"""Compare bandstructures using quantum algos."""
info = {}
@@ -212,48 +340,40 @@ def get_bandstruct(
for ii, i in enumerate(kpts):
if max_nk is not None and ii == max_nk:
break
- # For reducing CI/CD time
- print("breaking here", ii, max_nk)
- else:
- try:
-
- hk = get_hk_tb(w=w, k=i)
- HS = HermitianSolver(hk)
- vqe_vals, _ = HS.run_vqd(var_form=var_form)
- np_vals, _ = HS.run_numpy()
- if verbose:
- print("kp=", ii, i)
- print("np_vals", np_vals)
- print("vqe_vals", vqe_vals)
- eigvals_q.append(vqe_vals)
- eigvals_np.append(np_vals)
- # break
- if (
- neigs is not None
- and isinstance(neigs, int)
- and neigs == len(eigvals_q)
- ):
- break
- except Exception as exp:
- print(exp)
- pass
- eigvals_q = factor * np.array(eigvals_q) # 3.14 for phonon
+ try:
+ hk = get_hk_tb(w=w, k=i)
+ HS = HermitianSolver(hk)
+ vqe_vals, _ = HS.run_vqd(
+ var_form=var_form,
+ backend=backend,
+ ibm_token=ibm_token,
+ )
+ np_vals, _ = HS.run_numpy()
+ if verbose:
+ print("kp=", ii, i)
+ print("np_vals", np_vals)
+ print("vqe_vals", vqe_vals)
+ eigvals_q.append(vqe_vals)
+ eigvals_np.append(np_vals)
+ if (
+ neigs is not None
+ and isinstance(neigs, int)
+ and neigs == len(eigvals_q)
+ ):
+ break
+ except Exception as exp:
+ print(exp)
+ pass
+
+ eigvals_q = factor * np.array(eigvals_q)
eigvals_np = factor * np.array(eigvals_np)
for ii, i in enumerate(eigvals_q.T - ef):
- if ii == 0:
- plt.plot(i, "*", c="b", label="VQD")
- else:
- plt.plot(i, "*", c="b")
-
+ plt.plot(i, "*", c="b", label="VQD" if ii == 0 else "")
for ii, i in enumerate(eigvals_np.T - ef):
- if ii == 0:
- plt.plot(i, c="g", label="Numpy")
- else:
- plt.plot(i, c="g")
- new_kp = []
- new_labels = []
- count = 0
+ plt.plot(i, c="g", label="Numpy" if ii == 0 else "")
+
+ new_kp, new_labels, count = [], [], 0
kp = np.arange(len(kpts))
for i, j in zip(kp, labels):
if j != "":
@@ -265,6 +385,7 @@ def get_bandstruct(
new_kp.append(i)
new_labels.append("$" + str(j) + "$")
count += 1
+
info["eigvals_q"] = list(eigvals_q.tolist())
info["eigvals_np"] = list(eigvals_np.tolist())
info["kpts"] = list(kpts)
@@ -287,100 +408,3 @@ def get_bandstruct(
else:
plt.show()
return info
-
-
-def get_dos(
- w=[],
- grid=[2, 1, 1],
- proj=None,
- efermi=0.0,
- xrange=None,
- nenergy=100,
- sig=0.02,
- use_dask=True,
- filename="dos.png",
- savefig=True,
-):
- """Get density of states."""
- nwan = int(np.ceil(np.log2(w.nwan))) ** 2
- kpoints = generate_kgrid(grid=grid)
- nk = len(kpoints)
- q_vals = np.zeros((nk, nwan), dtype=float)
- np_vals = np.zeros((nk, nwan), dtype=float)
- pvals = np.zeros((nk, nwan - 1), dtype=float)
- # if use_dask:
- # def get_vqd_vals(k):
- # hk = get_hk_tb(w=w, k=k)
- # HS = HermitianSolver(hk)
- # vqe_vals, _ = HS.run_vqd()
- # return vqe_vals
-
- # values=[delayed(get_vqd_vals)(k) for k in kpoints]
- # resultsDask = compute(*values, scheduler='processes')
- for i, k in enumerate(kpoints):
- hk = get_hk_tb(w=w, k=k)
- HS = HermitianSolver(hk)
- vqe_vals, _ = HS.run_vqd()
- n_vals, _ = HS.run_numpy()
- print("np_vals", n_vals, len(n_vals), np_vals.shape)
- print("vqe_vals", vqe_vals, len(vqe_vals), q_vals.shape)
- q_vals[i, :] = vqe_vals
- np_vals[i, :] = n_vals
-
- if xrange is None:
- vmin = np.min(q_vals[:])
- vmax = np.max(q_vals[:])
- vmin2 = vmin - (vmax - vmin) * 0.05
- vmax2 = vmax + (vmax - vmin) * 0.05
- xrange = [vmin2, vmax2]
- # plt.xlim(xrange)
-
- energies = np.arange(
- xrange[0], xrange[1] + 1e-5, (xrange[1] - xrange[0]) / float(nenergy),
- )
- dos = np.zeros(np.size(energies))
- pdos = np.zeros(np.size(energies))
-
- v = q_vals
-
- # condmin = np.min(v[v > 0.0])
- # valmax = np.max(v[v < 0.0])
- # print("DOS BAND GAP ", condmin - valmax, " ", valmax, " ", condmin)
-
- c = -0.5 / sig ** 2
- for i in range(np.size(energies)):
- arg = c * (v - energies[i]) ** 2
- dos[i] = np.sum(np.exp(arg))
- if proj is not None:
- pdos[i] = np.sum(np.exp(arg) * pvals)
-
- de = energies[1] - energies[0]
- dos = dos / sig / (2.0 * np.pi) ** 0.5 / float(nk)
- if proj is not None:
- pdos = pdos / sig / (2.0 * np.pi) ** 0.5 / float(nk)
- print("np.sum(dos) ", np.sum(dos * de))
- if proj is not None:
- print("np.sum(pdos) ", np.sum(pdos * de))
- plt.plot(energies, dos)
- if savefig:
- plt.savefig(filename)
- plt.close()
- else:
- plt.show()
- return energies, dos, pdos
-
-
-"""
-if __name__ == "__main__":
- from jarvis.db.figshare import (
- get_wann_electron,
- get_wann_phonon,
- )
- from jarvis.core.circuits import QuantumCircuitLibrary
-
- wtbh, ef, atoms = get_wann_electron("JVASP-816")
- hk = get_hk_tb(w=wtbh, k=[0.0, 0.0, 0.0])
- H = HermitianSolver(hk)
- qc = QuantumCircuitLibrary(n_qubits=3).circuit6() # 2^3 = 8
- en, vqe_result, vqe = H.run_vqe(mode="min_val", var_form=qc)
-"""
diff --git a/jarvis/tests/testfiles/io/qiskit/test_hermsolver.py b/jarvis/tests/testfiles/io/qiskit/test_hermsolver.py
index 39c39825..c8281fd0 100644
--- a/jarvis/tests/testfiles/io/qiskit/test_hermsolver.py
+++ b/jarvis/tests/testfiles/io/qiskit/test_hermsolver.py
@@ -1,14 +1,12 @@
-from qiskit import Aer
-from qiskit.utils import QuantumInstance, algorithm_globals
-from qiskit.algorithms import VQE
-from qiskit.algorithms.optimizers import SLSQP
+#from qiskit.utils import QuantumInstance, algorithm_globals
+#from qiskit.algorithms import VQE
+#from qiskit.algorithms.optimizers import SLSQP
import numpy as np
import itertools, functools
-from qiskit.opflow import I, X, Y, Z
+#from qiskit.opflow import I, X, Y, Z
from jarvis.db.figshare import get_wann_electron, get_wann_phonon, get_hk_tb
from jarvis.core.circuits import QuantumCircuitLibrary
from jarvis.io.qiskit.inputs import HermitianSolver
-from qiskit import Aer
def decompose_Hamiltonian(H):
@@ -37,6 +35,31 @@ def decompose_Hamiltonian(H):
return decomposedH
+def test_qiskit():
+ from jarvis.db.figshare import get_wann_electron, get_hk_tb
+ from jarvis.io.qiskit.inputs import HermitianSolver
+ from jarvis.core.circuits import QuantumCircuitLibrary
+
+ # Aluminum JARVIS-ID: JVASP-816
+ wtbh, Ef, atoms = get_wann_electron("JVASP-1002")
+ kpt = [0.5, 0.0, 0.5] # X-point
+ hk = get_hk_tb(w=wtbh, k=kpt)
+
+ HS = HermitianSolver(hk)
+ n_qubits = HS.n_qubits()
+ circ = QuantumCircuitLibrary(n_qubits=n_qubits, reps=1).circuit6()
+
+ # Backend is now a string identifier; the StatevectorEstimator V2
+ # primitive is constructed internally by HermitianSolver.run_vqe()
+ en, vqe_result, vqe = HS.run_vqe(var_form=circ, backend="statevector_simulator")
+
+ vals, vecs = HS.run_numpy()
+
+ # Ef: Fermi-level
+ print("Classical, VQE (eV):", vals[0] - Ef, en - Ef)
+ print("Show model\n", circ)
+
+"""
def test_qiskit():
wtbh, Ef, atoms = get_wann_electron("JVASP-816")
kpt = [0.5, 0.0, 0.5] # X-point
@@ -80,7 +103,6 @@ def test_statvector():
print("Show model\n", circ)
-"""
# Commenting due to pypi conflicts in qiskit
#
# from qiskit.circuit.library import EfficientSU2
diff --git a/setup.py b/setup.py
index 173c6595..60213d13 100644
--- a/setup.py
+++ b/setup.py
@@ -12,7 +12,7 @@
setup(
name="jarvis-tools",
- version="2026.4.2",
+ version="2026.6.12",
long_description=long_d,
install_requires=[
"numpy>=1.20.1",