Metadata-Version: 2.4
Name: PAOFLOW
Version: 3.0.0
Summary: Utility to construct and operate on Hamiltonians from the Projections of DFT wfc on Atomic Orbital bases (PAO).
Keywords: DFT,Hamiltonians,PAO
Author-email: Marco Buongiorno Nardelli <mbn@unt.edu>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: numpy>=2.0,<2.5; python_version < '3.14'
Requires-Dist: numpy>=2.3.2,<2.5; python_version >= '3.14'
Requires-Dist: scipy>=1.14,<2
Requires-Dist: mpi4py~=4.1
Requires-Dist: pandas>=2.2,<3
Requires-Dist: pre-commit>=2.20.0 ; extra == "dev"
Requires-Dist: pytest>=7 ; extra == "dev"
Requires-Dist: sphinx>=8 ; extra == "docs"
Requires-Dist: myst-parser>=4 ; extra == "docs"
Requires-Dist: myst-nb ; extra == "docs"
Requires-Dist: sphinx-design>=0.6 ; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5 ; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16 ; extra == "docs"
Requires-Dist: sphinx-autobuild ; extra == "docs"
Requires-Dist: sphinx-autoapi ; extra == "docs"
Requires-Dist: numba>=0.58 ; extra == "fast"
Requires-Dist: mayavi ; extra == "fermisurface"
Requires-Dist: scikit-image>=0.20 ; extra == "fermisurface"
Requires-Dist: vtk ; extra == "graphics"
Requires-Dist: matplotlib ; extra == "graphics"
Requires-Dist: mendeleev ; extra == "graphics"
Requires-Dist: phonopy>=2.21 ; extra == "phonon"
Requires-Dist: phono3py>=2.3 ; extra == "phonon"
Requires-Dist: seekpath>=2.0 ; extra == "phonon"
Requires-Dist: scikit-image>=0.20 ; extra == "pyskeaf"
Requires-Dist: shapely>=2.0 ; extra == "pyskeaf"
Requires-Dist: joblib>=1.2 ; extra == "pyskeaf"
Requires-Dist: pandas>=2.0 ; extra == "pyskeaf"
Requires-Dist: psutil ; extra == "transport"
Requires-Dist: z2pack ; extra == "weyl-search"
Requires-Dist: tbmodels ; extra == "weyl-search"
Project-URL: Homepage, https://github.com/marcobn/PAOFLOW
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: fast
Provides-Extra: fermisurface
Provides-Extra: graphics
Provides-Extra: phonon
Provides-Extra: pyskeaf
Provides-Extra: transport
Provides-Extra: weyl-search


<p align="center">
  <img src="src/PAOFLOW/utils/paoflow_header.svg" alt="PAOFLOW" width="100%"/>
</p>

<p align="center">
  <a href="https://paoflow.readthedocs.io"><img src="https://img.shields.io/badge/docs-readthedocs-green?style=flat-square&logo=readthedocs" alt="Documentation"/></a>
  <a href="https://github.com/marcobn/PAOFLOW/wiki"><img src="https://img.shields.io/badge/wiki-GitHub-green?style=flat-square&logo=github" alt="Wiki"/></a>
  <a href="https://github.com/marcobn/PAOFLOW/blob/master/License"><img src="https://img.shields.io/badge/license-GPL--3.0-green?style=flat-square" alt="License"/></a>
  <a href="https://pypi.org/project/PAOFLOW/"><img src="https://img.shields.io/pypi/v/PAOFLOW?style=flat-square&color=green" alt="PyPI"/></a>
</p>

---

## What is PAOFLOW?

PAOFLOW is an open-source Python framework for constructing and operating on **ab initio tight-binding Hamiltonians** built from the projection of DFT wavefunctions onto atomic orbital (PAO) bases. Starting from a converged DFT calculation (Quantum ESPRESSO or VASP), PAOFLOW delivers a compact, tight-binding-like Hamiltonian that serves as the engine for a broad range of materials-property calculations — without any empirical parameters.

---

## Capabilities

| Domain | What PAOFLOW computes |
|---|---|
| **Electronic structure** | Band structures, density of states (total & projected), Fermi surfaces |
| **Self-consistent Hubbard correction** | he ACBN0 and eACBN0 pseudohybrid density functionals for calculations of U and V parameters in the DFT+U and DFT+U+V methods |
| **Spin & magnetism** | Spin texture, non-collinear and fully-relativistic (SOC) Hamiltonians |
| **Optical & dielectric response** | Complex dielectric tensor ε(ω), optical conductivity, joint density of states; non-local velocity correction for norm-conserving pseudopotentials |
| **Transport** | Electrical conductivity, Seebeck coefficient, electronic thermal conductivity (Boltzmann transport) |
| **Kubo-formula response** | anomalous Hall, spin Hall, and orbital Hall conductivities based on Berry curvature integration |
| **Lattice dynamics & phonons** | Phonon dispersions, DOS and thermal properties ([phonopy](https://phonopy.github.io/phonopy/) finite-displacement); Born effective charges, ε∞ and LO–TO splitting; infrared (IR), non-resonant (Placzek) and resonant (Albrecht) Raman spectra; vibrational (ionic) dielectric ε(ω) and reststrahlen emissivity; quasi-harmonic approximation (thermal expansion, V(T), bulk modulus, C_p, thermodynamic and mode Grüneisen dispersion) |
| **Electron-phonon coupling from pseudo-atomic-orbitals interpolation** | electron-phonon coupling, Eliashberg function, superconducting transition temperature |
| **Topology** | Berry curvature, Z₂ invariants, topological surface states |
| **Model Hamiltonians** | Kane–Mele and custom lattice models |
| **Environment-dependent tight-binding models** | Slater-Koster parameterization with structural transferability |
| **Quantum oscillation analysis** | de Haas-van Alphen and Shubnikov-de Haas frequencies and effective masses via Fermi surface extreme orbit finder, including fermi-plotter, a CLI for display Fermi surfaces and B vector(s) for easier interpretation |
| **Landauer-Büttiker quantum transport** | Transmission functions, conductance, and current-voltage characteristics for nanoscale conductor/lead geometries |
| **Interoperability** | Quantum ESPRESSO and VASP DFT code integration - other codes are in the development pipline (we welcome contributions from developers!)|

---

## Getting Started

```bash
pip install PAOFLOW
```

Full installation instructions (conda environment, MPI setup, optional dependencies) are in [INSTALL.md](INSTALL.md).

A step-by-step tutorial and worked examples are available in:
- 📖 **Documentation:** [paoflow.readthedocs.io](https://paoflow.readthedocs.io) *(full API reference, tutorials, theory notes)*
- 📚 **Wiki:** [github.com/marcobn/PAOFLOW/wiki](https://github.com/marcobn/PAOFLOW/wiki) *(how-to guides, FAQ, workflows)*
- 🗂️ **Examples:** [`examples/`](examples/) — QE, VASP, transport, TB models, ACBN0, and more

### Minimal workflow

```python
from PAOFLOW import PAOFLOW

pf = PAOFLOW.PAOFLOW(savedir='Si.save')
pf.projectability()
pf.pao_hamiltonian()
pf.bands(fname='bands')
pf.gradient_and_momenta()
pf.adaptive_smearing(smearing='gauss')
pf.dos(do_dos=True, do_pdos=False)
pf.finish()
```
PAOFLOW ships two small, dependency-light command-line generators that automate
the repetitive parts of setting up a study. They are installed with the package
as console commands:

1. **`paoflow-gen-qe`** — build a Quantum ESPRESSO `scf` input from an online
   materials database entry, with sensible defaults for smearing, magnetism,
   spin–orbit coupling, and the number of bands needed for PAOFLOW's
   extended-basis projections. Two databases are supported and auto-detected
   from the identifier (or selected with `--source`):
   [AFLOW](https://aflow.org) for bulk (3D) crystals and
   [C2DB](https://cmr.fysik.dtu.dk/c2db/c2db.html) for two-dimensional
   materials, where the input is set up with vacuum padding, an in-plane
   **k**-grid, and `assume_isolated='2D'`. When a database provides no
   **k**-mesh, dimension- and metallicity-aware defaults are used and a caveat
   reminds you to check **k**-point convergence. Pseudopotentials from the
   Pseudo Dojo repository (https://www.pseudo-dojo.org/), are included in the
   distribution and should be used for the input generation.
2. **`paoflow-gen`** — interactively generate a PAOFLOW driver script from the
   output of a Quantum ESPRESSO run. It offers three workflows:
   - **regular** — a property-run driver (`main.py`) that computes the
     properties you select (bands, DOS/PDOS, transport, optical, topology,
     …), with a 2D-aware band path, plus an optional companion **plotting
     script** (`plot.py`) that visualizes exactly those properties.
   - **acbn0** — a self-consistent Hubbard *U* (ACBN0) / on-site *U* + intersite
     *V* (eACBN0) driver (`main.acbn0.py`), paired with a `plot.acbn0.py` that
     overlays the band structures of the converged cases (DFT+U and, for
     eACBN0, DFT+U+V) for direct comparison.
   - **phonon** — a three-phase lattice-dynamics driver (`main.phonon.py`)
     that writes the displaced-supercell `pw.x` inputs, harvests the forces
     and assembles the phonon dispersion, DOS, thermal properties and (with
     Born charges) the LO–TO splitting. Optionally it also emits a companion
     **Raman workflow** (`main.raman.py`) for the non-resonant (Placzek)
     Raman spectrum, plus matching `plot.phonon.py` / `plot.raman.py` scripts.
   - **elphon** - sets up a driver for the interpolation of electron-phonon matrix elements from a DFPT calculation (AHC).
---

## For Researchers

PAOFLOW has been used in high-throughput screening campaigns, topological materials discovery, optical/transport property databases, and quantum computing workflows, among others. It is an active platform for methodological development — recent additions include non-local velocity corrections for accurate optical spectra and Boltzmann transport beyond the constant relaxation-time approximation.

## For Industry & HPC

PAOFLOW is MPI-parallel, NumPy/SciPy-based, and designed to plug into existing DFT workflows with minimal overhead. The PAO Hamiltonian is orders of magnitude cheaper to diagonalize than the full DFT problem, enabling dense **k**-point sampling and fine spectral resolution at low computational cost.

An **optional Rust backend** ([`rust/`](rust/)) further accelerates the heaviest numerical kernels — the ACBN0/eACBN0 four-centre Coulomb integrals (ERIs) and the dielectric/JDOS response loops. It is fully optional and imported opportunistically: when the compiled `paoflow_rs` module is unavailable, PAOFLOW falls back to its pure-Python/NumPy implementation with numerically identical results (parity < 1e-12). See the [Rust backend guide](rust/README.md) for build and usage instructions.

---

## License & Citation

Copyright 2016–2026 — Marco Buongiorno Nardelli (mbn@unt.edu) and the PAOFLOW Development Team.

PAOFLOW is free software distributed under the **GNU General Public License v3**. See [License](License) for details.

If you use PAOFLOW in published work, please cite:

> F.T. Cerasoli, A.R. Supka, A. Jayaraj, I. Siloi, M. Costa, J. Slawinska, S. Curtarolo, M. Fornari, D. Ceresoli, and M. Buongiorno Nardelli,
> *Advanced modeling of materials with PAOFLOW 2.0: New features and software design*, Comp. Mat. Sci. **200**, 110828 (2021).

> M. Buongiorno Nardelli, F.T. Cerasoli, M. Costa, S. Curtarolo, R. De Gennaro, M. Fornari, L. Liyanage, A. Supka and H. Wang,
> *PAOFLOW: A utility to construct and operate on ab initio Hamiltonians from the Projections of electronic wavefunctions on Atomic Orbital bases, including characterization of topological materials*, Comp. Mat. Sci. **143**, 462 (2018).

> L.A. Agapito, A. Ferretti, A. Calzolari, S. Curtarolo and M. Buongiorno Nardelli,
> *Effective and accurate representation of extended Bloch states on finite Hilbert spaces*, Phys. Rev. B **88**, 165127 (2013).

> L.A. Agapito, S. Ismail-Beigi, S. Curtarolo, M. Fornari and M. Buongiorno Nardelli,
> *Accurate Tight-Binding Hamiltonian Matrices from Ab-Initio Calculations: Minimal Basis Sets*, Phys. Rev. B **93**, 035104 (2016).

> L.A. Agapito, M. Fornari, D. Ceresoli, A. Ferretti, S. Curtarolo and M. Buongiorno Nardelli,
> *Accurate Tight-Binding Hamiltonians for 2D and Layered Materials*, Phys. Rev. B **93**, 125137 (2016).

> P. D'Amico, L. Agapito, A. Catellani, A. Ruini, S. Curtarolo, M. Fornari, M. Buongiorno Nardelli and A. Calzolari,
> *Accurate ab initio tight-binding Hamiltonians: Effective tools for electronic transport and optical spectroscopy from first principles*, Phys. Rev. B **94**, 165166 (2016).

