xtal2png 0.1.4

Encode and decode crystal structures via portable networks graphics (PNG) files.

:warning: Codebase and Documentation under construction (2022-05-25) :warning:

xtal2png

Encode(/decode) a crystal structure as(/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 (e.g. LSTMs, transformers) or image processing (e.g. GANs, VAEs, guided diffusion models). Encoding/decoding crystal structures via grayscale PNG images (sort of like a QR code for crystal structures) allows materials informatics practitioners to get streamlined results for new state-of-the-art image-based machine learning models applied to crystal structure. What this means is that a user simply needs to follow the directions of an image-based repository for a custom image dataset to get preliminary domain-specific results prior to the higher-cost/higher-expertise task of modifying the codebase to take a custom numerical representation.

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:

1. clone and enter the repository via:

   git clone https://github.com/sparks-baird/xtal2png.git
   cd xtal2png
   

2. create and activate a new conda environment (optional, but recommended)

   conda env create --name xtal2png python==3.9.*
   conda activate xtal2png
   

3. perform an editable (-e) installation in the current directory (.):

   pip install -e .
   

NOTE: Some changes, e.g. in setup.cfg, might require you to run pip install -e . again.

Optional and needed only once after git clone:

3. 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 of git commit can be used to deactivate pre-commit hooks temporarily.

4. 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.

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