Encode and decode crystal structures via portable networks graphics (PNG) files.
Project description
⚠️ Codebase and Documentation under construction, conda-forge release coming soon (2022-05-26) ⚠️
xtal2png
Encode/decode a crystal structure to/from a grayscale PNG image for direct use with image-based machine learning models such as Palette.
The latest advances in machine learning are often in natural language such as with LSTMs and transformers or image processing such as with GANs, VAEs, and guided diffusion models. Encoding/decoding crystal structures via grayscale PNG images is akin to making/reading a QR code for crystal structures. This allows you, as a materials informatics practitioner, to get streamlined results for new state-of-the-art image-based machine learning models applied to crystal structure. Let's take Google's image-to-image diffusion model, Palette. Rather than dig into the code spending hours, days, or weeks modifying, debugging, and playing GitHub phone tag with the developers before you can (maybe) get preliminary results, xtal2png
lets you get those results using the default instructions on the repository.
After getting preliminary results, you get to decide whether it's worth it to you to take on the higher-cost/higher-expertise task of modifying the codebase and using a more customized approach. Or, you can stick with the results of xtal2png
. It's up to you!
Quick Start
Installation
conda env create -n xtal2png -c conda-forge xtal2png
conda activate xtal2png
Example
# a list of `pymatgen.core.structure.Structure` objects
from xtal2png.utils.data import example_structures
from xtal2png.core import XtalConverter
xc = XtalConverter()
data = xc.xtal2png(example_structures, show=True, save=True)
decoded_structures = xc.png2xtal(data, save=False)
Output
print(example_structures[0], decoded_structures[0])
Original | Decoded |
---|---|
Structure Summary
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
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]
...
|
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]
...
|
The before and after structures match within an expected tolerance; note the round-off error due to encoding numerical data as RGB images which has a coarse resolution of approximately 1/255 = 0.00392
. Note also that the decoded version lacks charge states. The QR-code-like intermediate PNG image is also provided in original size and a scaled version for a better viewing experience:
64x64 pixels | Scaled for Better Viewing (tool credit) | Legend |
---|---|---|
Installation
Anaconda (conda
) installation (recommended)
(2022-05-23, conda-forge installation still pending, fallback to pip install xtal2png
as separate command)
Create and activate a new conda
environment named xtal2png
(-n
) that will search for and install the xtal2png
package from the conda-forge
Anaconda channel (-c
).
conda env create -n xtal2png -c conda-forge xtal2png
conda activate xtal2png
Alternatively, in an already activated environment:
conda install -c conda-forge xtal2png
If you run into conflicts with packages you are integrating with xtal2png
, please try installing all packages in a single line of code (or two if mixing conda
and pip
packages in the same environment) and/or installing with mamba
(source).
PyPI (pip
) installation
Create and activate a new conda
environment named xtal2png
(-n
) with python==3.9.*
or your preferred Python version, then install xtal2png
via pip
.
conda env create -n xtal2png python==3.9.*
conda activate xtal2png
pip install xtal2png
Editable installation
In order to set up the necessary environment:
-
clone and enter the repository via:
git clone https://github.com/sparks-baird/xtal2png.git cd xtal2png
-
create and activate a new conda environment (optional, but recommended)
conda env create --name xtal2png python==3.9.* conda activate xtal2png
-
perform an editable (
-e
) installation in the current directory (.
):pip install -e .
NOTE: Some changes, e.g. in
setup.cfg
, might require you to runpip install -e .
again.
Optional and needed only once after git clone
:
-
install several pre-commit git hooks with:
pre-commit install # You might also want to run `pre-commit autoupdate`
and checkout the configuration under
.pre-commit-config.yaml
. The-n, --no-verify
flag ofgit commit
can be used to deactivate pre-commit hooks temporarily. -
install nbstripout git hooks to remove the output cells of committed notebooks with:
nbstripout --install --attributes notebooks/.gitattributes
This is useful to avoid large diffs due to plots in your notebooks. A simple
nbstripout --uninstall
will revert these changes.
Then take a look into the scripts
and notebooks
folders.
Command Line Interface (CLI)
Make sure to install the package first per the installation instructions above. Here is how to access the help for the CLI and a few examples to get you started.
Help
You can see the usage information of the xtal2png
CLI script via:
(xtal2png) PS C:\Users\sterg\Documents\GitHub\sparks-baird\xtal2png> xtal2png --help
usage: xtal2png [-h] [--version] [-p STRING] [-s STRING] [--encode] [--decode] [-v] [-vv] Crystal to PNG encoder/decoder. optional arguments: -h, --help show this help message and exit --version show program's version number and exit -p STRING, --path STRING Crystallographic information file (CIF) filepath (extension must be .cif or .CIF) or path to directory containing .cif files or processed PNG filepath or path to directory containing processed .png files (extension must be .png or .PNG). Assumes CIFs if --encode flag is used. Assumes PNGs if --decode flag is used. -s STRING, --save-dir STRING Directory to save processed PNG files or decoded CIFs to. --encode Encode CIF files as PNG images. --decode Decode PNG images as CIF files. -v, --verbose set loglevel to INFO -vv, --very-verbose set loglevel to DEBUG
Examples
To encode a single CIF file located at src/xtal2png/utils/Zn2B2PbO6.cif
as a PNG and save the PNG to the tmp
directory:
xtal2png --encode --path src/xtal2png/utils/Zn2B2PbO6.cif --save-dir tmp
To encode all CIF files contained in the src/xtal2png/utils
directory as a PNG and
save corresponding PNGs to the tmp
directory:
xtal2png --encode --path src/xtal2png/utils --save-dir tmp
To decode a single structure-encoded PNG file located at
data/preprocessed/Zn8B8Pb4O24,volume=623,uid=b62a.png
as a CIF file and save the CIF
file to the tmp
directory:
xtal2png --decode --path data/preprocessed/Zn8B8Pb4O24,volume=623,uid=b62a.png --save-dir tmp
To decode all structure-encoded PNG file contained in the data/preprocessed
directory as CIFs and save the CIFs to the tmp
directory:
xtal2png --decode --path data/preprocessed --save-dir tmp
Note that the save directory (e.g. tmp
) including any parents (e.g. ab/cd/tmp
) will
be created automatically if the directory does not already exist.
Project Organization
├── AUTHORS.md <- List of developers and maintainers.
├── CHANGELOG.md <- Changelog to keep track of new features and fixes.
├── CONTRIBUTING.md <- Guidelines for contributing to this project.
├── Dockerfile <- Build a docker container with `docker build .`.
├── LICENSE.txt <- License as chosen on the command-line.
├── README.md <- The top-level README for developers.
├── configs <- Directory for configurations of model & application.
├── data
│ ├── external <- Data from third party sources.
│ ├── interim <- Intermediate data that has been transformed.
│ ├── preprocessed <- The final, canonical data sets for modeling.
│ └── raw <- The original, immutable data dump.
├── docs <- Directory for Sphinx documentation in rst or md.
├── environment.yml <- The conda environment file for reproducibility.
├── models <- Trained and serialized models, model predictions,
│ or model summaries.
├── notebooks <- Jupyter notebooks. Naming convention is a number (for
│ ordering), the creator's initials and a description,
│ e.g. `1.0-fw-initial-data-exploration`.
├── pyproject.toml <- Build configuration. Don't change! Use `pip install -e .`
│ to install for development or to build `tox -e build`.
├── references <- Data dictionaries, manuals, and all other materials.
├── reports <- Generated analysis as HTML, PDF, LaTeX, etc.
│ └── figures <- Generated plots and figures for reports.
├── scripts <- Analysis and production scripts which import the
│ actual PYTHON_PKG, e.g. train_model.
├── setup.cfg <- Declarative configuration of your project.
├── setup.py <- [DEPRECATED] Use `python setup.py develop` to install for
│ development or `python setup.py bdist_wheel` to build.
├── src
│ └── xtal2png <- Actual Python package where the main functionality goes.
├── tests <- Unit tests which can be run with `pytest`.
├── .coveragerc <- Configuration for coverage reports of unit tests.
├── .isort.cfg <- Configuration for git hook that sorts imports.
└── .pre-commit-config.yaml <- Configuration of pre-commit git hooks.
Note
This project has been set up using PyScaffold 4.2.1 and the dsproject extension 0.7.1.
The following pyscaffold
command creates a starting point for this repository:
putup xtal2png --github-actions --markdown --dsproj
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.