# mp-pyrho
📄 [Full Documentation](https://materialsproject.github.io/pyrho)
# Installation
```
pip install mp-pyrho
```
Tools for re-griding volumetric quantum chemistry data for machine-learning purposes.
[](https://github.com/materialsproject/pyrho/actions/workflows/testing.yml)
[](https://codecov.io/gh/materialsproject/pyrho)
[](https://zenodo.org/badge/latestdoi/266894456)
If you use this package in your research, please cite the following:
```
Shen, J.-X., Munro, J. M., Horton, M. K., Huck, P., Dwaraknath, S., & Persson, K. A. (2022).
A representation-independent electronic charge density database for crystalline materials.
Sci Data, 9(661), 1–7. doi: 10.1038/s41597-022-01746-z
```
# Regridding data using PyRho
## The PGrid Class
The `PGrid` object is defined by an N-dimensional numpy array `grid_data` and a N lattice vector given as a matrix `lattice`. The input array is a scalar field that is defined on a regularly spaced set of grid points starting at the origin. For example, you can construct a periodic field as follows:
```python
import numpy as np
from pyrho.pgrid import PGrid
from pyrho.vis.scatter import get_scatter_plot
def func(X, Y):
return np.sin(X) * np.cos(2 * Y)
a = np.linspace(0, np.pi, 27, endpoint=False)
b = np.linspace(0, np.pi, 28, endpoint=False)
X, Y = np.meshgrid(a, b, indexing="ij")
data = func(X, Y)
pg2d = PGrid(grid_data=data, lattice=[[np.pi, 0], [0, np.pi]])
```
The data can be examined using the helper plotting function which supports up to 3-D.
```python
import matplotlib as mpl
mpl.rc("image", cmap="viridis")
get_scatter_plot(pg2d.grid_data, pg2d.lattice, marker_size=40)
```
The period data in the PGrid object must be fixed-scaled so if you half the number of points in the domain, the range of the data will stay the same. This is different from how the charge density is stored in codes like VASP where the values at each point change based on the number of grid points used to store the data.
The regridding capabilities allow the user to obtain the data in any arbitrary representation. For example, if we want to shift to the middle of the unit-cell and create a ((1,1), (1,-1)) super-cell, with a 30 by 32 grid, we can run:
```python
pg_2x = pg2d.get_transformed([[1, 1], [1, -1]], origin=[0.5, 0.5], grid_out=[30, 32])
get_scatter_plot(pg_2x.grid_data, pg_2x.lattice, skips=1, opacity=1, marker_size=10)
```
# Up-sampling with Fourier interpolation
The up-sampling capabilities allow the user to exploit the periodicity of the data to obtain a higher-resolution grid.
As an example, we can take a sparsely sampled periodic data in 1-D:
```python
def func1(X):
return np.sin(6 * X)
a = np.linspace(0, np.pi, 10, endpoint=False)
data = func1(a)
pg1d = PGrid(grid_data=data, lattice=[[np.pi]])
get_scatter_plot(pg1d.grid_data, pg1d.lattice, marker_size=50)
```
This does not really resemble the `np.sin(6*X)` function we used to generate the data.
However, if we use an up-sample factor of 8, we can obtain a more dense representation:
```python
pg1d_fine = pg1d.get_transformed(
sc_mat=[[2]],
grid_out=[
200,
],
up_sample=8,
)
get_scatter_plot(pg1d_fine.grid_data, pg1d_fine.lattice, marker_size=10)
```
## The ChargeDensity class
The `ChargeDensity` object can use the `from_file` construction method from `pymatgen.io.vasp.outputs.Chgcar` as shown below.
```python
from pymatgen.io.vasp import Chgcar
from pyrho.charge_density import ChargeDensity
cden_uc = ChargeDensity.from_file(
"../test_files/CHGCAR.uc.vasp"
)
cden_sc = ChargeDensity.from_file(
"../test_files/CHGCAR.sc1.vasp"
)
chgcar_sc = Chgcar.from_file(
"../test_files/CHGCAR.sc1.vasp"
)
cden_transformed = cden_uc.get_transformed(
[[1, 1, 0], [1, -1, 0], [0, 0, 1]],
grid_out=cden_sc.grid_shape,
up_sample=2,
)
```
The `normalized_data` property contains a dictionary keyed with the same keys as `Chgcar.data` (typically "total" and "diff" for spin charge densities).
This quantity is the fixed scalar field that should remain fixed after the transformation.
```python
data = cden_uc.normalized_data["total"]
print(
f"The normalized charge density data is has a range of {data.min():0.3f} --> {data.max():0.3f} e-/Ang^3"
)
```
The normalized charge density data is has a range of -0.188 --> 0.572 e-/Ang^3
Note that the PAW transformation sometimes results in negative charge densities.
```python
trans_data = cden_transformed.normalized_data["total"]
print(
f"The transformed normalized charge density data is has a range of {trans_data.min():0.3f} --> {trans_data.max():0.3f} e-/Ang^3"
)
```
The transformed normalized charge density data is has a range of -0.188 --> 0.572 e-/Ang^3
```python
sc_data = cden_sc.normalized_data["total"]
print(
f"The reference normalized charge density data is has a range of {sc_data.min():0.3f} --> {sc_data.max():0.3f} e-/Ang^3"
)
```
The reference normalized charge density data is has a range of -0.188 --> 0.570 e-/Ang^3
## Credits
Jimmy-Xuan Shen: Project lead
Wennie Wang: For naming the package
Raw data
{
"_id": null,
"home_page": null,
"name": "mp-pyrho",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "machine-learning, dft, vasp, volumetric, pymatgen",
"author": null,
"author_email": "Jimmy-Xuan Shen <jmmshn@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/20/39/d8d911262241a7715bab7d5d4f5d2f33dcc81ef67f94ed7b881d221371a3/mp_pyrho-0.4.5.tar.gz",
"platform": null,
"description": "# mp-pyrho\n\ud83d\udcc4 [Full Documentation](https://materialsproject.github.io/pyrho)\n\n# Installation\n\n```\npip install mp-pyrho\n```\n\nTools for re-griding volumetric quantum chemistry data for machine-learning purposes.\n\n[](https://github.com/materialsproject/pyrho/actions/workflows/testing.yml)\n[](https://codecov.io/gh/materialsproject/pyrho)\n[](https://zenodo.org/badge/latestdoi/266894456)\n\n\nIf you use this package in your research, please cite the following:\n\n```\nShen, J.-X., Munro, J. M., Horton, M. K., Huck, P., Dwaraknath, S., & Persson, K. A. (2022). \nA representation-independent electronic charge density database for crystalline materials. \nSci Data, 9(661), 1\u20137. doi: 10.1038/s41597-022-01746-z\n```\n\n# Regridding data using PyRho\n\n\n\n## The PGrid Class\n\nThe `PGrid` object is defined by an N-dimensional numpy array `grid_data` and a N lattice vector given as a matrix `lattice`. The input array is a scalar field that is defined on a regularly spaced set of grid points starting at the origin. For example, you can construct a periodic field as follows:\n\n\n```python\nimport numpy as np\nfrom pyrho.pgrid import PGrid\nfrom pyrho.vis.scatter import get_scatter_plot\n\n\ndef func(X, Y):\n return np.sin(X) * np.cos(2 * Y)\n\n\na = np.linspace(0, np.pi, 27, endpoint=False)\nb = np.linspace(0, np.pi, 28, endpoint=False)\nX, Y = np.meshgrid(a, b, indexing=\"ij\")\ndata = func(X, Y)\npg2d = PGrid(grid_data=data, lattice=[[np.pi, 0], [0, np.pi]])\n```\n\nThe data can be examined using the helper plotting function which supports up to 3-D.\n\n\n```python\nimport matplotlib as mpl\n\nmpl.rc(\"image\", cmap=\"viridis\")\nget_scatter_plot(pg2d.grid_data, pg2d.lattice, marker_size=40)\n```\n\n\n\n\n\nThe period data in the PGrid object must be fixed-scaled so if you half the number of points in the domain, the range of the data will stay the same. This is different from how the charge density is stored in codes like VASP where the values at each point change based on the number of grid points used to store the data.\n\nThe regridding capabilities allow the user to obtain the data in any arbitrary representation. For example, if we want to shift to the middle of the unit-cell and create a ((1,1), (1,-1)) super-cell, with a 30 by 32 grid, we can run:\n\n\n```python\npg_2x = pg2d.get_transformed([[1, 1], [1, -1]], origin=[0.5, 0.5], grid_out=[30, 32])\nget_scatter_plot(pg_2x.grid_data, pg_2x.lattice, skips=1, opacity=1, marker_size=10)\n```\n\n\n\n\n\n\n\n# Up-sampling with Fourier interpolation\n\nThe up-sampling capabilities allow the user to exploit the periodicity of the data to obtain a higher-resolution grid.\nAs an example, we can take a sparsely sampled periodic data in 1-D:\n\n\n```python\ndef func1(X):\n return np.sin(6 * X)\n\n\na = np.linspace(0, np.pi, 10, endpoint=False)\ndata = func1(a)\n\npg1d = PGrid(grid_data=data, lattice=[[np.pi]])\nget_scatter_plot(pg1d.grid_data, pg1d.lattice, marker_size=50)\n```\n\n\n\n\n\n\n\nThis does not really resemble the `np.sin(6*X)` function we used to generate the data.\nHowever, if we use an up-sample factor of 8, we can obtain a more dense representation:\n\n\n```python\npg1d_fine = pg1d.get_transformed(\n sc_mat=[[2]],\n grid_out=[\n 200,\n ],\n up_sample=8,\n)\nget_scatter_plot(pg1d_fine.grid_data, pg1d_fine.lattice, marker_size=10)\n```\n\n\n\n\n\n\n\n## The ChargeDensity class\n\nThe `ChargeDensity` object can use the `from_file` construction method from `pymatgen.io.vasp.outputs.Chgcar` as shown below.\n\n\n```python\nfrom pymatgen.io.vasp import Chgcar\nfrom pyrho.charge_density import ChargeDensity\n\ncden_uc = ChargeDensity.from_file(\n \"../test_files/CHGCAR.uc.vasp\"\n)\ncden_sc = ChargeDensity.from_file(\n \"../test_files/CHGCAR.sc1.vasp\"\n)\nchgcar_sc = Chgcar.from_file(\n \"../test_files/CHGCAR.sc1.vasp\"\n)\ncden_transformed = cden_uc.get_transformed(\n [[1, 1, 0], [1, -1, 0], [0, 0, 1]],\n grid_out=cden_sc.grid_shape,\n up_sample=2,\n)\n\n\n```\n\nThe `normalized_data` property contains a dictionary keyed with the same keys as `Chgcar.data` (typically \"total\" and \"diff\" for spin charge densities).\nThis quantity is the fixed scalar field that should remain fixed after the transformation.\n\n\n```python\ndata = cden_uc.normalized_data[\"total\"]\nprint(\n f\"The normalized charge density data is has a range of {data.min():0.3f} --> {data.max():0.3f} e-/Ang^3\"\n)\n\n```\n\n The normalized charge density data is has a range of -0.188 --> 0.572 e-/Ang^3\n\n\nNote that the PAW transformation sometimes results in negative charge densities.\n\n\n```python\ntrans_data = cden_transformed.normalized_data[\"total\"]\nprint(\n f\"The transformed normalized charge density data is has a range of {trans_data.min():0.3f} --> {trans_data.max():0.3f} e-/Ang^3\"\n)\n\n```\n\n The transformed normalized charge density data is has a range of -0.188 --> 0.572 e-/Ang^3\n\n\n\n```python\nsc_data = cden_sc.normalized_data[\"total\"]\nprint(\n f\"The reference normalized charge density data is has a range of {sc_data.min():0.3f} --> {sc_data.max():0.3f} e-/Ang^3\"\n)\n\n```\n\n The reference normalized charge density data is has a range of -0.188 --> 0.570 e-/Ang^3\n\n\n## Credits\n\nJimmy-Xuan Shen: Project lead\n\nWennie Wang: For naming the package\n",
"bugtrack_url": null,
"license": "modified BSD",
"summary": "Tools for re-griding periodic volumetric quantum chemistry data for machine-learning purposes.",
"version": "0.4.5",
"project_urls": {
"homepage": "https://materialsproject.github.io/pyrho/",
"repository": "https://materialsproject.github.io/pyrho"
},
"split_keywords": [
"machine-learning",
" dft",
" vasp",
" volumetric",
" pymatgen"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6b13c95ef0ded603781142acce1046d37a46ade928ac3608189f0794587717d3",
"md5": "315057cc5f95fdf4208fb472dd7e1e1b",
"sha256": "c9ee1a91c271e25940739883d876a2a476b064d8430c7da4c4b0f95f6bbbc5bd"
},
"downloads": -1,
"filename": "mp_pyrho-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "315057cc5f95fdf4208fb472dd7e1e1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18446,
"upload_time": "2024-10-22T22:21:31",
"upload_time_iso_8601": "2024-10-22T22:21:31.694393Z",
"url": "https://files.pythonhosted.org/packages/6b/13/c95ef0ded603781142acce1046d37a46ade928ac3608189f0794587717d3/mp_pyrho-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2039d8d911262241a7715bab7d5d4f5d2f33dcc81ef67f94ed7b881d221371a3",
"md5": "50a0bbb3fdaa5afbfc43126cfbffa95a",
"sha256": "6705a9fd4cdb01435bd9f0884f5a1ac9289cf2b6bd3caf288653c96afc90bba4"
},
"downloads": -1,
"filename": "mp_pyrho-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "50a0bbb3fdaa5afbfc43126cfbffa95a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2422370,
"upload_time": "2024-10-22T22:21:33",
"upload_time_iso_8601": "2024-10-22T22:21:33.171455Z",
"url": "https://files.pythonhosted.org/packages/20/39/d8d911262241a7715bab7d5d4f5d2f33dcc81ef67f94ed7b881d221371a3/mp_pyrho-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 22:21:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mp-pyrho"
}
JSON