rhoprint

Physically interpretable descriptors ("fingerprints") extracted from VASP charge-density (CHGCAR) files, for materials-informatics and ML interpretability studies.

Developed at CMS Lab, IIT Kanpur (Department of Materials Science and Engineering) alongside work on charge-density-informed ML models for elastic-property prediction (bulk modulus, shear modulus, Young's modulus, formation energy, Debye temperature).

What it computes

rhoprint compute --full (or rhoprint.compute_all_features) extracts every descriptor below for one material, given its CHGCAR file and a material_id of the form <formula>_<space_group_number> (e.g. NdP_225).

Charge-density grid descriptors

Computed directly from the CHGCAR voxel grid.

Structural & compositional descriptors

Derived from the material_id (crystal symmetry) and chemical formula (via pymatgen).

Derived cross-term descriptors

Ratios and products combining the above, capturing non-linear structure-electronic interactions.

Install

pip install rhoprint
# or, for development:
git clone https://github.com/CMSLabIITK/rhoprint
cd rhoprint
pip install -e ".[dev]"

Quickstart

from rhoprint import parse_chgcar, compute_all_grid_functionals

data = parse_chgcar("CHGCAR")
features = compute_all_grid_functionals(data)
print(features)
# {'zeta': 0.31, 'laplacian_mean': ..., 'moment_1': ..., ...}

Batch processing a dataset

from rhoprint import run_batch

df = run_batch(
    data_dir="/path/to/materials",   # each subdir has a CHGCAR file
    out_csv="results/functionals.csv",
    n_workers=4,
    resume=True,
)

or from the command line:

rhoprint compute path/to/CHGCAR
rhoprint batch --data_dir /path/to/materials --out_csv results/functionals.csv --n_workers 4 --resume

Derived + compositional descriptors on a dataset

import pandas as pd
from rhoprint.functionals.derived import compute_derived_ratios
from rhoprint.functionals.composition import compute_compositional_features_batch

df = pd.read_csv("results/functionals.csv")
comp = compute_compositional_features_batch(df["formula"])
df = pd.concat([df, comp], axis=1)
df = compute_derived_ratios(df)

Full descriptor set in one call

compute_all_features combines all three descriptor groups above (grid, structural/compositional, derived) into a single row, given a material_id of the form <formula>_<space_group_number>:

from rhoprint import compute_all_features

row = compute_all_features("NdP_225", "path/to/CHGCAR")

or for a whole dataset (each subdirectory named <formula>_<space_group_number>, containing a CHGCAR file):

from rhoprint import run_full_batch

df = run_full_batch(
    data_dir="/path/to/materials",
    out_csv="results/full_functionals.csv",
    n_workers=4,
    resume=True,
)

or from the command line:

rhoprint compute path/to/NdP_225/CHGCAR --full
rhoprint batch --data_dir /path/to/materials --out_csv results/full_functionals.csv --n_workers 4 --full --resume

Notes

• parse_chgcar assumes VASP 5 format (element symbols on their own line). VASP 4-format CHGCAR files (no element-symbol line) are not supported.

Citing

See CITATION.cff.

Zenodo DOI: pending. The repo is owned by the CMS Lab GitHub org; a permanent Zenodo DOI will be minted.

License

MIT — see LICENSE.