mp-pyrho: Quantum Chemistry Data Regridding

Common errors

• ModuleNotFoundError: No module named 'mp_pyrho'

  cause The `mp-pyrho` library has not been installed in your current Python environment.
  fix Install the library using pip: `pip install mp-pyrho`

• TypeError: regrid() got an unexpected keyword argument 'center_method' (or featurize())

  cause You are attempting to use the `center_method` parameter, or a specific value for it, with an `mp-pyrho` version older than 0.5.0, where this parameter or its default change was introduced.
  fix Upgrade your `mp-pyrho` installation to version 0.5.0 or newer using `pip install --upgrade mp-pyrho`. Then, consult the documentation for the correct parameter usage.

• ValueError: The grid_data provided has a shape (X, Y, Z) incompatible with the structure's lattice matrix.

  cause The dimensions of the input `grid_data` array do not correctly align with the periodicity and lattice vectors defined by the `pymatgen.core.Structure` object. This typically occurs when manually constructing `RhoGrid` or with issues in parsing VASP output files.
  fix Verify that your `grid_data` represents the volumetric data sampled correctly across the unit cell of the `structure`. For VASP data, ensure proper parsing of `CHGCAR`, `POSCAR`, `LOCPOT`, etc. If creating manually, ensure `grid_data.shape` corresponds to the number of points in each lattice vector direction.

Warnings

• breaking In `mp-pyrho` version 0.5.0, the default `center_method` for both `RhoGrid.regrid()` and `RhoGrid.featurize()` changed from 'com' (center of mass) to 'mass' (mass-weighted center). This change can lead to different output data if not explicitly handled.
  Fix: If your previous workflow relied on the 'com' centering, explicitly set `center_method='com'` in your `regrid()` and `featurize()` calls to maintain consistency: `rho_grid.regrid(..., center_method='com')`.
• gotcha In `mp-pyrho` version 0.5.0, the `featurize()` method's `vectorize_grid` parameter default changed to `True`. This means `featurize()` now returns a 1D NumPy array by default, instead of a 3D grid, which might be unexpected if you are used to previous versions.
  Fix: If you require the 3D grid output from `featurize()`, explicitly set `vectorize_grid=False`: `rho_grid.featurize(..., vectorize_grid=False)`.
• gotcha The library is primarily designed for periodic volumetric data from quantum chemistry calculations (e.g., VASP CHGCAR, LOCPOT). Using non-periodic data or data formats not compatible with `pymatgen`'s structure representation can lead to unexpected errors or incorrect physical interpretations during regridding and featurization.
  Fix: Ensure your input `structure` and `grid_data` accurately represent a periodic system and that the `grid_data` aligns with the unit cell dimensions. Use `RhoGrid.from_file()` or `RhoGrid.from_directory()` for robust loading of standard VASP outputs.

Install

• pip install mp-pyrho Install mp-pyrho

Imports

• RhoGrid

  from mp_pyrho.grid import RhoGrid

Quickstart

This quickstart demonstrates how to initialize a `RhoGrid` object with a `pymatgen.core.Structure` and dummy 3D volumetric data. It then shows how to use the `regrid` method to standardize the resolution and the `featurize` method to generate a machine-learning-ready representation, either as a 1D vector or a 3D grid.

from pymatgen.core import Structure
from mp_pyrho.grid import RhoGrid
import numpy as np

# Create a dummy structure (e.g., a simple cubic perovskite)
structure = Structure.from_spacegroup("Pm-3m", [3.8], ["Fe", "O"], [[0, 0, 0], [0.5, 0.5, 0.5]])

# Create dummy 3D volumetric data (e.g., 20x20x20 points)
# In a real scenario, this would be loaded from a CHGCAR, LOCPOT, or similar file
dummy_grid_data = np.random.rand(20, 20, 20)

# Initialize RhoGrid object with the structure and volumetric data
rho_grid = RhoGrid(structure=structure, grid_data=dummy_grid_data)

# Regrid the data to a new target resolution (e.g., 0.1 Å)
# The output is a 3D NumPy array
regridded_data = rho_grid.regrid(target_resolution=0.1)
print(f"Original grid shape: {rho_grid.grid_data.shape}")
print(f"Shape of regridded data: {regridded_data.shape}")

# Featurize the regridded data
# For mp-pyrho >= 0.5.0, `vectorize_grid` defaults to True and `center_method` to 'mass'
features_vectorized = rho_grid.featurize(target_resolution=0.1)
print(f"Shape of features (vectorized): {features_vectorized.shape}")

# If you need the 3D grid output from featurize, set vectorize_grid=False
features_3d_grid = rho_grid.featurize(target_resolution=0.1, vectorize_grid=False)
print(f"Shape of features (3D grid): {features_3d_grid.shape}")