Package: xtal2png
⚠️ Manuscript and results using a generative model coming soon ⚠️xtal2pngEncode/decode a crystal structure to/from a grayscale PNG image for direct use with image-based machine learning models such asGoogle's Imagen.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 text-to-image diffusion model,Imagen(unofficial), whichcan also be used as an image-to-image model. 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,xtal2pnglets 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 ofxtal2png. It's up to you!Getting StartedInstallationcondacreate-nxtal2png-cconda-forgextal2pngm3gnet
condaactivatextal2pngNOTE:m3gnetis an optional dependency that performs surrogate DFT relaxation.ExampleHere, we use the top-levelXtalConverterclass with and without optional relaxation viam3gnet.# example_structures is a list of `pymatgen.core.structure.Structure` objects>>>fromxtal2pngimportXtalConverter,example_structures>>>>>>xc=XtalConverter(relax_on_decode=False)>>>data=xc.xtal2png(example_structures,show=True,save=True)>>>decoded_structures=xc.png2xtal(data,save=False)>>>len(decoded_structures)2>>xc=XtalConverter(relax_on_decode=True)>>data=xc.xtal2png(example_structures,show=True,save=True)>>relaxed_decoded_structures=xc.png2xtal(data,save=False)>>len(relaxed_decoded_structures)2Outputprint(example_structures[0],decoded_structures[0],relaxed_decoded_structures[0])OriginalStructureSummaryLatticeabc:5.03378811.52302110.74117angles:90.090.090.0volume:623.0356027127609A:5.0337880.03.0823061808931787e-16B:1.8530431062799525e-1511.5230217.055815392078867e-16C:0.00.010.74117PeriodicSite: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]...DecodedStructureSummaryLatticeabc:5.025098039215686511.53333333333333110.8angles:90.090.090.0volume:625.9262117647058A:5.02509803921568650.00.0B:0.011.5333333333333310.0C:0.00.010.8PeriodicSite: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]...Relaxed DecodedStructureSummaryLatticeabc:5.02683430738121411.57885461368523710.724087971087924angles:90.090.090.0volume:624.1953646135236A:5.0268343073812140.00.0B:0.011.5788546136852370.0C:0.00.010.724087971087924PeriodicSite: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]...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 approximately1/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 pixelsScaled for Better Viewing (tool credit)LegendAdditional examples can be found inthe docs.Limitations and Design ConsiderationsThere are some limitations and design considerations forxtal2png. Here, we cover round-off error, image dimensions, contextual features, and customization.Round-offWhile the round-off
error is a necessary evil for encoding to aPNG file format, the unrounded NumPy arrays
can be used directly instead if supported by the image model of interest viastructures_to_arraysandarrays_to_structures.Image dimensionsWe choose a
$64\times64$ representation by default which supports up to 52 sites within a unit cell.
The maximum number of sitesmax_sitescan be adjusted which changes the size of the
representation. A square representation is used for greater compatibility with the
common limitation of image-based models supporting only square image arrays. The choice
of the default sidelength as a base-2 number (i.e. $2^6$) reflects common conventions of
low-resolution images for image-based machine learning tasks.Contextual featuresWhile the
distance matrix does not directly contribute to the reconstruction in the current
implementation ofxtal2png, it serves a number of purposes. First, similar to the unit
cell volume and space group information, it can provide additional guidance to the
algorithm. A corresponding example would be the role of background vs. foreground in
classification of wolves vs. huskies; oftentimes classification algorithms will pay
attention to the background (such as presence of snow) in predicting the animal class.
Likewise, providing contextual information such as volume, space group, and a distance
matrix is additional information that can help the models to capture the essence of
particular crystal structures. In a future implementation, we plan to reconstruct
Euclidean coordinates from the distance matrices and homogenize (e.g. via weighted
averaging) the explicit fractional coordinates with the reconstructed coordinates.CustomizationSee thedocsfor the full list of customizable parameters thatXtalConvertertakes.InstallationPyPI (pip) installationCreate and activate a newcondaenvironment namedxtal2png(-n) withpython==3.9.*or your preferred Python version, then installxtal2pngviapip.condacreate-nxtal2pngpython==3.9.*
condaactivatextal2png
pipinstallxtal2pngEditable installationIn order to set up the necessary environment:clone and enter the repository via:gitclonehttps://github.com/sparks-baird/xtal2png.gitcdxtal2pngcreate and activate a new conda environment (optional, but recommended)condaenvcreate--namextal2pngpython==3.9.*
condaactivatextal2pngperform an editable (-e) installation in the current directory (.):pipinstall-e.NOTE:Some changes, e.g. insetup.cfg, might require you to runpip install -e .again.Optional and needed only once aftergit clone:install severalpre-commitgit hooks with:pre-commitinstall# You might also want to run `pre-commit autoupdate`and checkout the configuration under.pre-commit-config.yaml.
The-n, --no-verifyflag ofgit commitcan be used to deactivate pre-commit hooks temporarily.installnbstripoutgit hooks to remove the output cells of committed notebooks with:nbstripout--install--attributesnotebooks/.gitattributesThis is useful to avoid large diffs due to plots in your notebooks.
A simplenbstripout --uninstallwill revert these changes.Then take a look into thescriptsandnotebooksfolders.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.HelpYou can see the usage information of thextal2pngCLI script via:xtal2png--helpUsage:xtal2png[OPTIONS]xtal2pngcommandlineinterface.

Options:--versionShowversion.-p,--pathPATHCrystallographicinformationfile(CIF)filepath(extensionmustbe.cifor.CIF)orpathtodirectorycontaining.ciffilesorprocessedPNGfilepathorpathtodirectorycontainingprocessed.pngfiles(extensionmustbe.pngor.PNG).AssumesCIFsif--encodeflagisused.AssumesPNGsif--decodeflagisused.-s,--save-dirPATHEncodeCIFfilesasPNGimages.--encodeEncodeCIFfilesasPNGimages.--decodeDecodePNGimagestoCIFfiles.-v,--verboseTEXTSetlogleveltoINFO.-vv,--very-verboseTEXTSetlogleveltoINFO.--helpShowthismessageandexit.ExamplesTo encode a single CIF file located atsrc/xtal2png/utils/Zn2B2PbO6.cifas a PNG and save the PNG to thetmpdirectory:xtal2png--encode--pathsrc/xtal2png/utils/Zn2B2PbO6.cif--save-dirtmpTo encode all CIF files contained in thesrc/xtal2png/utilsdirectory as a PNG and
save corresponding PNGs to thetmpdirectory:xtal2png--encode--pathsrc/xtal2png/utils--save-dirtmpTo decode a single structure-encoded PNG file located atdata/preprocessed/Zn8B8Pb4O24,volume=623,uid=b62a.pngas a CIF file and save the CIF
file to thetmpdirectory:xtal2png--decode--pathdata/preprocessed/Zn8B8Pb4O24,volume=623,uid=b62a.png--save-dirtmpTo decode all structure-encoded PNG file contained in thedata/preprocesseddirectory as CIFs and save the CIFs to thetmpdirectory:xtal2png--decode--pathdata/preprocessed--save-dirtmpNote 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 on PyScaffoldThis project has been set up usingPyScaffold4.2.1 and thedsproject extension0.7.1.To create the same starting point for this repository, as of 2022-06-01 on Windows you will need the development versions of PyScaffold and extensions, however this will not be necessary once certain bugfixes have been introduced in the next stable releases:pipinstallgit+https://github.com/pyscaffold/pyscaffold.gitgit+https://github.com/pyscaffold/pyscaffoldext-dsproject.gitgit+https://github.com/pyscaffold/pyscaffoldext-markdown.gitThe followingpyscaffoldcommand creates a starting point for this repository:putupxtal2png--github-actions--markdown--dsprojAlternatively, you can edit a file interactively and update and uncomment relevant lines, which saves some of the additional setup:putup--interactivextal2pngAttributions@michaeldalversonfor iterating through various representations during extensive work with crystal GANs. The base representation forxtal2png(see#output) closely follows a recent iteration (2022-06-13), taking the first layer ($1\times64\times64$) of the $4\times64\times64$ representation and replacing a buffer column/row of zeros with unit cell volume.