Skip to content

Commit

Permalink
Merge pull request #101 from sparks-baird/sgbaird-patch-2
Browse files Browse the repository at this point in the history
update README and ipynb with m3gnet usage (/fixup syntax)
sgbaird authored Jun 17, 2022
2 parents a0619b5 + 01ce16f commit fd0b7dd
Showing 2 changed files with 250 additions and 182 deletions.
51 changes: 37 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -34,20 +34,26 @@ conda activate xtal2png
from xtal2png.utils.data import example_structures
from xtal2png.core import XtalConverter

xc = XtalConverter()
xc = XtalConverter() # DFT surrogate relaxation via m3gnet by default
data = xc.xtal2png(example_structures, show=True, save=True)
relaxed_decoded_structures = xc.png2xtal(data, save=False)


xc = XtalConverter(relax_on_decode=False)
data = xc.xtal2png(example_structures, show=True, save=True)
decoded_structures = xc.png2xtal(data, save=False)
```

### Output
```python
print(example_structures[0], decoded_structures[0])
print(example_structures[0], decoded_structures[0], relaxed_decoded_structures[0])
```

<table>
<tr>
<th> Original </th>
<th> Decoded </th>
<th> Relaxed Decoded </th>
</tr>
<tr>
<td>
@@ -58,11 +64,28 @@ Lattice
abc : 5.033788 11.523021 10.74117
angles : 90.0 90.0 90.0
volume : 623.0356027127609
A : 5.033788 0.0 3.082306e-16
B : 1.853043e-15 11.523021 7.055815e-16
A : 5.033788 0.0 3.0823061808931787e-16
B : 1.8530431062799525e-15 11.523021 7.055815392078867e-16
C : 0.0 0.0 10.74117
PeriodicSite: Zn2+ (0.912, 5.770, 9.126) [0.181, 0.501, 0.850]
PeriodicSite: Zn2+ (4.122, 5.753, 1.616) [0.8188, 0.499, 0.150]
PeriodicSite: Zn2+ (0.9120, 5.7699, 9.1255) [0.1812, 0.5007, 0.8496]
PeriodicSite: Zn2+ (4.1218, 5.7531, 1.6156) [0.8188, 0.4993, 0.1504]
...
```

</td>
<td>

```python
Structure Summary
Lattice
abc : 5.0250980392156865 11.533333333333331 10.8
angles : 90.0 90.0 90.0
volume : 625.9262117647058
A : 5.0250980392156865 0.0 0.0
B : 0.0 11.533333333333331 0.0
C : 0.0 0.0 10.8
PeriodicSite: Zn (0.9016, 5.7780, 3.8012) [0.1794, 0.5010, 0.3520]
PeriodicSite: Zn (4.1235, 5.7554, 6.9988) [0.8206, 0.4990, 0.6480]
...
```

@@ -72,14 +95,14 @@ PeriodicSite: Zn2+ (4.122, 5.753, 1.616) [0.8188, 0.499, 0.150]
```python
Structure Summary
Lattice
abc : 5.058824 11.529412 10.764706
angles : 90.352941 90.352941 90.352941
volume : 627.818381
A : 5.058728 0.0 -0.031162
B : -0.071459 11.528972 -0.071021
C : 0.0 0.0 10.764706
PeriodicSite: Zn (0.877, 5.787, 9.119) [0.180, 0.502, 0.851]
PeriodicSite: Zn (4.111, 5.742, 1.543) [0.820, 0.498, 0.149]
abc : 5.026834307381214 11.578854613685237 10.724087971087924
angles : 90.0 90.0 90.0
volume : 624.1953646135236
A : 5.026834307381214 0.0 0.0
B : 0.0 11.578854613685237 0.0
C : 0.0 0.0 10.724087971087924
PeriodicSite: Zn (0.9050, 5.7978, 3.7547) [0.1800, 0.5007, 0.3501]
PeriodicSite: Zn (4.1218, 5.7810, 6.9693) [0.8200, 0.4993, 0.6499]
...
```

381 changes: 213 additions & 168 deletions notebooks/1.0-xtal2png-tutorial.ipynb
Original file line number Diff line number Diff line change
@@ -1,67 +1,50 @@
{
"nbformat": 4,
"nbformat_minor": 0,
"metadata": {
"colab": {
"name": "xtal2png-tutorial.ipynb",
"provenance": [],
"authorship_tag": "ABX9TyNJG5GbIiRm3b22dp5jDrbI",
"include_colab_link": true
},
"kernelspec": {
"name": "python3",
"display_name": "Python 3"
},
"language_info": {
"name": "python"
}
},
"cells": [
{
"cell_type": "markdown",
"metadata": {
"id": "view-in-github",
"colab_type": "text"
"colab_type": "text",
"id": "view-in-github"
},
"source": [
"<a href=\"https://colab.research.google.com/github/sparks-baird/xtal2png/blob/main/notebooks/1.0-xtal2png-tutorial.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
]
},
{
"cell_type": "markdown",
"source": [
"# Encode/decode a crystal structure to/from a grayscale PNG image"
],
"metadata": {
"id": "mHJ4l5gKuXx-"
}
},
"source": [
"# Encode/decode a crystal structure to/from a grayscale PNG image"
]
},
{
"cell_type": "markdown",
"source": [
"In this notebook, we will install the `xtal2png` package, encode/decode two example pymatgen `Structure` objects, and show some visualizations of the intermediate PNG representations and before/after crystal structure plots. Finally, we comment on how you can use `xtal2png` with state-of-the-art machine learning image models."
],
"metadata": {
"id": "pjrtpDdbuyqp"
}
},
"source": [
"In this notebook, we will install the `xtal2png` package, encode/decode two example pymatgen `Structure` objects, and show some visualizations of the intermediate PNG representations and before/after crystal structure plots. Finally, we comment on how you can use `xtal2png` with state-of-the-art machine learning image models."
]
},
{
"cell_type": "markdown",
"source": [
"## Installation"
],
"metadata": {
"id": "In1KcDcVuxw6"
}
},
"source": [
"## Installation"
]
},
{
"cell_type": "markdown",
"source": [
"Install the `xtal2png` package. Optionally install `ase` and `nglview` which can be used to visualize crystal structures. You may need to restart the runtime via `Ctrl+M, .` or `Runtime --> Restart Runtime` (via menubar)."
],
"metadata": {
"id": "93hxUzlfqb4v"
}
},
"source": [
"Install the `xtal2png` package. Optionally install `ase` and `nglview` which can be used to visualize crystal structures. You may need to restart the runtime via `Ctrl+M, .` or `Runtime --> Restart Runtime` (via menubar)."
]
},
{
"cell_type": "code",
@@ -75,8 +58,8 @@
},
"outputs": [
{
"output_type": "stream",
"name": "stdout",
"output_type": "stream",
"text": [
"Looking in indexes: https://pypi.org/simple, https://us-python.pkg.dev/colab-wheels/public/simple/\n",
"Collecting xtal2png\n",
@@ -143,134 +126,157 @@
},
{
"cell_type": "markdown",
"source": [
"## Encode(/decode) two pymatgen `Structure` objects"
],
"metadata": {
"id": "5_ur18igvGap"
}
},
"source": [
"## Encode(/decode) two pymatgen `Structure` objects"
]
},
{
"cell_type": "markdown",
"source": [
"Import a list of two example pymatgen `Structure` objects (these correspond to [mp-560471](https://next-gen.materialsproject.org/materials/mp-560471)/$Zn_2B_2PbO_6$ and [mp-7823](https://next-gen.materialsproject.org/materials/mp-7823)/$V_2NiSe_4$, respectively)"
],
"metadata": {
"id": "auHOZ-dAhd5t"
}
},
"source": [
"Import a list of two example pymatgen `Structure` objects (these correspond to [mp-560471](https://next-gen.materialsproject.org/materials/mp-560471)/$Zn_2B_2PbO_6$ and [mp-7823](https://next-gen.materialsproject.org/materials/mp-7823)/$V_2NiSe_4$, respectively)"
]
},
{
"cell_type": "code",
"source": [
"from xtal2png.utils.data import example_structures\n",
"from xtal2png.core import XtalConverter"
],
"execution_count": null,
"metadata": {
"id": "qDET_Hc6UXP7"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"from xtal2png.utils.data import example_structures\n",
"from xtal2png.core import XtalConverter"
]
},
{
"cell_type": "markdown",
"source": [
"Let's take a look at the second `Structure` which has a smaller footprint."
],
"metadata": {
"id": "EcxElT0bhyxF"
}
},
"source": [
"Let's take a look at the second `Structure` which has a smaller footprint."
]
},
{
"cell_type": "code",
"source": [
"example_structures[1]"
],
"execution_count": null,
"metadata": {
"id": "S2I58v39hyNO"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"example_structures[1]"
]
},
{
"cell_type": "markdown",
"source": [
"We will be using the `XtalConverter` class, for which more information including its `__init__` arguments and functions can be displayed via `help(XtalConverter)`. For just the parameters for class instantiation, try `help(XtalConverter.__init__)`. Note that `max_sites` is not tested for values other than `52`."
],
"metadata": {
"id": "ulVWYCeoiuTM"
}
},
"source": [
"We will be using the `XtalConverter` class, for which more information including its `__init__` arguments and functions can be displayed via `help(XtalConverter)`. For just the parameters for class instantiation, try `help(XtalConverter.__init__)`. Note that `max_sites` is not tested for values other than `52`."
]
},
{
"cell_type": "code",
"source": [
"help(XtalConverter.__init__)"
],
"execution_count": null,
"metadata": {
"id": "hZ4LtYcJkoOC"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"help(XtalConverter.__init__)"
]
},
{
"cell_type": "markdown",
"source": [
"Let's specify the save directory (`save_dir`) for the PNG files as `\"data\"`, which will be automatically created. In this case, it will be saved to temporary Google Colab storage."
],
"metadata": {
"id": "weBReOogvmeK"
}
},
"source": [
"Let's specify the save directory (`save_dir`) for the PNG files as `\"data\"`, which will be automatically created. In this case, it will be saved to temporary Google Colab storage."
]
},
{
"cell_type": "code",
"source": [
"xc = XtalConverter(save_dir=\"data\")\n",
"data = xc.xtal2png(example_structures, save=True)\n",
"decoded_structures = xc.png2xtal(data, save=False)"
],
"execution_count": null,
"metadata": {
"id": "B_S0jeVsVfYK"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"xc = XtalConverter(save_dir=\"data\") # DFT surrogate relaxation via m3gnet by default\n",
"data = xc.xtal2png(example_structures, save=True)\n",
"relaxed_decoded_structures = xc.png2xtal(data, save=False)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Visualization"
],
"We also take a look at the unrelaxed decoded structures."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"xc = XtalConverter(save_dir=\"data\", relax_on_decode=False)\n",
"data = xc.xtal2png(example_structures, save=True)\n",
"decoded_structures = xc.png2xtal(data, save=False)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "DNL8GcdZwixh"
}
},
"source": [
"## Visualization"
]
},
{
"cell_type": "markdown",
"source": [
"For visualization, we'll cover two aspects: the structure-encoded PNG images and visualizing before/after crystal structures."
],
"metadata": {
"id": "Cexf9PqBwkMR"
}
},
"source": [
"For visualization, we'll cover two aspects: the structure-encoded PNG images and visualizing before/after crystal structures."
]
},
{
"cell_type": "markdown",
"source": [
"### Structure-encoded PNG images"
],
"metadata": {
"id": "Xm8i5EZ5wsqJ"
}
},
"source": [
"### Structure-encoded PNG images"
]
},
{
"cell_type": "markdown",
"source": [
"Note that images won't show via `im.show()` command _on Google Colab_ even if you specify `xc.xtal2png(..., show=True, ...)`, so for this Colab example we'll open the images ad-hoc based on where they were saved in local Colab storage. We display the images stacked one on top of another using `display(im)` instead of `im.show()`. Note that the filepaths have the chemical formula, `volume`, and a randomly generated `uid` portion to promote uniqueness, especially when dealing with allotropes (same chemical formula, different crystal structure)."
],
"metadata": {
"id": "TQ8jkgYrhcg2"
}
},
"source": [
"Note that images won't show via `im.show()` command _on Google Colab_ even if you specify `xc.xtal2png(..., show=True, ...)`, so for this Colab example we'll open the images ad-hoc based on where they were saved in local Colab storage. We display the images stacked one on top of another using `display(im)` instead of `im.show()`. Note that the filepaths have the chemical formula, `volume`, and a randomly generated `uid` portion to promote uniqueness, especially when dealing with allotropes (same chemical formula, different crystal structure)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "pV0L8N85kTFk"
},
"outputs": [],
"source": [
"import glob, os\n",
"from PIL import Image\n",
@@ -279,33 +285,32 @@
" im = im.resize((64*5, 64*5), Image.BOX)\n",
" print(fpath)\n",
" display(im)"
],
"metadata": {
"id": "pV0L8N85kTFk"
},
"execution_count": null,
"outputs": []
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "oU6FjfDYnnuI"
},
"source": [
"As mentioned in the README, the legend key for these images is as follows:\n",
"\n",
"&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<img src=https://user-images.githubusercontent.com/45469701/169937021-f6f60169-6965-4db1-9bbd-e8744521d570.png width=327>"
],
"metadata": {
"id": "oU6FjfDYnnuI"
}
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "U-rTkYeMxxAQ"
},
"source": [
"Also described in the README, the match between the encoded and decoded versions is within an expected tolerance, given that PNG images are represented as discrete RGB values between 0 and 255 (i.e. there is a round-off error).\n",
"\n",
"<table>\n",
"<tr>\n",
"<th> Original </th>\n",
"<th> Decoded </th>\n",
"<th> Relaxed Decoded </th>\n",
"</tr>\n",
"<tr>\n",
"<td>\n",
@@ -316,11 +321,11 @@
" abc : 5.033788 11.523021 10.74117\n",
" angles : 90.0 90.0 90.0\n",
" volume : 623.0356027127609\n",
" A : 5.033788 0.0 3.082306e-16\n",
" B : 1.853043e-15 11.523021 7.055815e-16\n",
" A : 5.033788 0.0 3.0823061808931787e-16\n",
" B : 1.8530431062799525e-15 11.523021 7.055815392078867e-16\n",
" C : 0.0 0.0 10.74117\n",
"PeriodicSite: Zn2+ (0.912, 5.770, 9.126) [0.181, 0.501, 0.850]\n",
"PeriodicSite: Zn2+ (4.122, 5.753, 1.616) [0.8188, 0.499, 0.150]\n",
"PeriodicSite: Zn2+ (0.9120, 5.7699, 9.1255) [0.1812, 0.5007, 0.8496]\n",
"PeriodicSite: Zn2+ (4.1218, 5.7531, 1.6156) [0.8188, 0.4993, 0.1504]\n",
"...\n",
"```\n",
"\n",
@@ -330,128 +335,168 @@
"```python\n",
"Structure Summary\n",
"Lattice\n",
" abc : 5.058824 11.529412 10.764706\n",
" angles : 90.352941 90.352941 90.352941\n",
" volume : 627.818381\n",
" A : 5.058728 0.0 -0.031162\n",
" B : -0.071459 11.528972 -0.071021\n",
" C : 0.0 0.0 10.764706\n",
"PeriodicSite: Zn (0.877, 5.787, 9.119) [0.180, 0.502, 0.851]\n",
"PeriodicSite: Zn (4.111, 5.742, 1.543) [0.820, 0.498, 0.149]\n",
" abc : 5.0250980392156865 11.533333333333331 10.8\n",
" angles : 90.0 90.0 90.0\n",
" volume : 625.9262117647058\n",
" A : 5.0250980392156865 0.0 0.0\n",
" B : 0.0 11.533333333333331 0.0\n",
" C : 0.0 0.0 10.8\n",
"PeriodicSite: Zn (0.9016, 5.7780, 3.8012) [0.1794, 0.5010, 0.3520]\n",
"PeriodicSite: Zn (4.1235, 5.7554, 6.9988) [0.8206, 0.4990, 0.6480]\n",
"...\n",
"```\n",
"\n",
"</td>\n",
"<td>\n",
"\n",
"```python\n",
"Structure Summary\n",
"Lattice\n",
" abc : 5.026834307381214 11.578854613685237 10.724087971087924\n",
" angles : 90.0 90.0 90.0\n",
" volume : 624.1953646135236\n",
" A : 5.026834307381214 0.0 0.0\n",
" B : 0.0 11.578854613685237 0.0\n",
" C : 0.0 0.0 10.724087971087924\n",
"PeriodicSite: Zn (0.9050, 5.7978, 3.7547) [0.1800, 0.5007, 0.3501]\n",
"PeriodicSite: Zn (4.1218, 5.7810, 6.9693) [0.8200, 0.4993, 0.6499]\n",
"...\n",
"```\n",
"\n",
"</td>\n",
"</tr>\n",
"</table>"
],
"metadata": {
"id": "U-rTkYeMxxAQ"
}
]
},
{
"cell_type": "markdown",
"source": [
"### Before/after Crystal Structure Visualization"
],
"metadata": {
"id": "6K8M_EWewvgK"
}
},
"source": [
"### Before/after Crystal Structure Visualization"
]
},
{
"cell_type": "markdown",
"source": [
"To visualize the crystal structures before and after, we can use `nglview` after a bit of Colab finnagling with external ipywidgets."
],
"metadata": {
"id": "e1TFsM32pwsN"
}
},
"source": [
"To visualize the crystal structures before and after, we can use `nglview` after a bit of Colab finnagling with external ipywidgets."
]
},
{
"cell_type": "code",
"source": [
"from google.colab import output\n",
"output.enable_custom_widget_manager()"
],
"execution_count": null,
"metadata": {
"id": "VDhN-1cFuGIq"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"from google.colab import output\n",
"output.enable_custom_widget_manager()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "kT2kMJkBriRT"
},
"outputs": [],
"source": [
"from pymatgen.io.ase import AseAtomsAdaptor\n",
"from ase.visualize import view\n",
"aaa = AseAtomsAdaptor()"
],
"metadata": {
"id": "kT2kMJkBriRT"
},
"execution_count": null,
"outputs": []
]
},
{
"cell_type": "code",
"source": [
"[display(view(aaa.get_atoms(s), viewer='ngl')) for s in example_structures]"
],
"execution_count": null,
"metadata": {
"id": "40sCJggKsV5E"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"[display(view(aaa.get_atoms(s), viewer='ngl')) for s in example_structures]"
]
},
{
"cell_type": "code",
"source": [
"[display(view(aaa.get_atoms(s), viewer='ngl')) for s in decoded_structures]"
],
"execution_count": null,
"metadata": {
"id": "FWMOd7gHsTB0"
},
"outputs": [],
"source": [
"[display(view(aaa.get_atoms(s), viewer='ngl')) for s in decoded_structures]"
]
},
{
"cell_type": "code",
"execution_count": null,
"outputs": []
"metadata": {},
"outputs": [],
"source": [
"[display(view(aaa.get_atoms(s), viewer='ngl')) for s in relaxed_decoded_structures]"
]
},
{
"cell_type": "markdown",
"source": [
"Undo the Colab finnagling of external ipywidgets."
],
"metadata": {
"id": "1u_95y04uIRa"
}
},
"source": [
"Undo the Colab finnagling of external ipywidgets."
]
},
{
"cell_type": "code",
"source": [
"from google.colab import output\n",
"output.disable_custom_widget_manager()"
],
"execution_count": null,
"metadata": {
"id": "IVFYjEvUrfCP"
},
"execution_count": null,
"outputs": []
"outputs": [],
"source": [
"from google.colab import output\n",
"output.disable_custom_widget_manager()"
]
},
{
"cell_type": "markdown",
"source": [
"## Final Remarks"
],
"metadata": {
"id": "DLAfVjyrw5VK"
}
},
"source": [
"## Final Remarks"
]
},
{
"cell_type": "markdown",
"source": [
"This tool makes it possible to use state-of-the-art image-based machine learning models with minimal \"plumbing\" required. Just follow the normal instructions for custom image datasets. For example, this can be used with [Palette](https://iterative-refinement.github.io/palette/), an image-to-image guided diffusion model by Google, which has an unofficial implementation [here](https://github.com/Janspiry/Palette-Image-to-Image-Diffusion-Models)."
],
"metadata": {
"id": "7QHtKaklxKip"
}
},
"source": [
"This tool makes it possible to use state-of-the-art image-based machine learning models with minimal \"plumbing\" required. Just follow the normal instructions for custom image datasets. For example, this can be used with [Palette](https://iterative-refinement.github.io/palette/), an image-to-image guided diffusion model by Google, which has an unofficial implementation [here](https://github.com/Janspiry/Palette-Image-to-Image-Diffusion-Models)."
]
}
]
],
"metadata": {
"colab": {
"authorship_tag": "ABX9TyNJG5GbIiRm3b22dp5jDrbI",
"include_colab_link": true,
"name": "xtal2png-tutorial.ipynb",
"provenance": []
},
"kernelspec": {
"display_name": "Python 3",
"name": "python3"
},
"language_info": {
"name": "python"
}
},
"nbformat": 4,
"nbformat_minor": 0
}

0 comments on commit fd0b7dd

Please sign in to comment.