Poraquê

Poraquê learns maps between the three-dimensional scalar fields of density-functional theory. Given only a crystal geometry it predicts the valence charge density and the kinetic energy density — no wavefunctions, no self-consistency cycle.

{POSCAR, INCAR, POTCAR} --analytic--> EXTCAR --Model 1--> CHGCAR --Model 2--> TAUCAR
                                                                                 |
                                                                        integrate v
                                                                              energy

The first step is closed-form; only the two field-to-field maps are learned. They are not unrelated regressions: the first is the Hohenberg–Kohn map, whose existence is a theorem, and the second is the kinetic energy density functional, the missing ingredient of orbital-free DFT.

Install

git clone https://github.com/seixas-research/poraque.git
cd poraque
pip install -e .

Python 3.11 or newer. Installing registers three console commands — poraque-train, poraque-inference and poraque-committee — which run from any directory once the environment is active. Each is the main() of the script of the same name under scripts/, so python scripts/poraque_train.py is equivalent to poraque-train and needs nothing installed.

Use

# 1. train one ext2chg and one chg2tau model on all structures
poraque-train --write-config configs/train_config.yaml
poraque-train --config configs/train_config.yaml

# 2. measure generalisation
poraque-train --config configs/train_config.yaml --kfold --k-folds 5

# 3. predict a structure that has never been computed
poraque-inference new_structure/ --output predictions/new_structure

Every predicted field is written in CHGCAR format.

Or drive it from ASE:

from ase.build import bulk
from poraque.calculator import Poraque

atoms = bulk("Au", "fcc", a=4.08, cubic=True)
atoms.calc = Poraque("models/poraque_models.pfno", potcar="POTCAR")
atoms.get_potential_energy()
print(atoms.calc.components)     # T_s, E_ext, alpha Z, E_H, E_xc, Ewald

Forces and stress are not implemented, so this is single points, not relaxations.

What is in here

Design points

• The external potential is computed natively. Poraquê reconstructs it from the POTCAR tables on any standard VASP output, matching a reference potential to a relative 5×10⁻⁵. There is no option to import one: the training input must be exactly what inference produces.
• Grids may differ between materials. One model serves all of them: the operator's weights live in Fourier-mode space, and batches are bucketed by grid shape.
• Constraints are structural where possible. For chg2tau, τ = τ_vW[ρ] + softplus(·) makes the Hoffmann-Ostenhof bound hold by construction rather than by penalty.
• Resampling is spectral. Fourier truncation is the exact band-limited projection for a plane-wave field; interpolation would alias and shift the electron count.
• CUDA, Apple Metal and CPU, selected automatically.

Status

Seventeen gold supercells — ten 27-atom cells and seven 32-atom cells, spanning four grid shapes. A single 80/20 split at 32³ working resolution, 300 epochs with early stopping, whole structures held out (seed=42):

R² on the held-out structures is 0.9976 (ext2chg) and 0.9953 (chg2tau). The ± is the spread across the three validation structures, not a cross-validation error bar — see the caveat below.

The learned kinetic functional beats the analytic orbital-free functionals by a wide margin on this system — on the same held-out fields Thomas-Fermi scores 1.347 and von Weizsäcker 0.738, so chg2tau is 26× and 14× better respectively.

What this split can and cannot tell you. With valid_fraction = 0.2 and 17 structures, the held-out set is three structures — and at seed=42 all three (struct_011, struct_012, struct_016) happen to be 32-atom cells. So the headline numbers describe the harder subset only, there is no held-out 27-atom measurement at all, and three structures is too thin a base for a meaningful error bar. Earlier 5-fold cross-validation on the 12-structure dataset put 32-atom cells at roughly twice the error of 27-atom ones; the number above is consistent with that, and is better than the 0.0445 that subset scored then, which is what four 32-atom cells in training rather than one should buy. Use --kfold for a figure that covers every structure.

Still one element. These numbers measure interpolation between geometries of gold and now, weakly, extrapolation across cell size. They say nothing about transfer to other chemistry. Growing the dataset remains the main open item — see docs/notes/roadmap.md.

Energies are not there yet. The total energy is a sum of terms of order 10⁴ eV whose physically relevant variation is a fraction of an eV per atom — a relative ~10⁻⁴ — and a field-level error of 2×10⁻² cannot survive that cancellation. The last full measurement, on the earlier 12-structure dataset, put the true spread at 0.27 eV/atom against an error on predicted differences of 0.29 eV/atom — a ratio of 1.06 with correlation r ≈ −0.1. Those figures have not been re-measured on the current 17-structure dataset, and the verdict they support is unchanged either way: an error equal to the signal and no correlation means the predicted energy ordering carries no information. The energy module itself is validated against exact Madelung constants and uniform-electron-gas limits; it is the fields that are not yet accurate enough. See docs/source/energy/index.md.

License

MIT. See LICENSE.