The Crystal Structure Prediction Network (CRYSPNet) project introduces an alternative way to perform fast prediction on Crystal Structure Information (Bravais Lattice, Space Group, and Latice Parameter) with the power of neural networks.

Note: Python 3.6 or later is required. Since Fastai library does not support Windows, the following installation only works on linux-based environment. We recommand using CONDA environment to create a new environment for this installation. To install the project with pip and git, run the following commands:

    git clone https://github.com/auroralht/cryspnet.git
    cd cryspnet
    pip install -e .

Pre-trained models are stored in google drive. Download the file learner.zip from from the drive. After downing the file copy it to cryspnet/cryspnet and extract it. Five folders: BravaisEsmMetal, BravaisEsmOxide, BravaisEsmWhole, LatticeParam, and SpaceGroup should be in the cryspnet/cryspnet/learner directory after the extraction is completed.

fastai, pytorch, and Matminer are three major package used heavily in this project. If these packages cannot be installed, please go to their github/documentation site for more information.

(optional) We recommand using JupyterLab to execute our Notebook example. Running with Jupyter Notebook is extremely fine also. To install:

    conda install -c conda-forge jupyterlab

    pip install jupyterlab

Input requirement: The input would be stored in a csv like file with a column name called formula.

Here is an example of running prediction on formula listed in demo.csv

    cd cryspnet
    python predict.py -i demo/demo.csv -o output/output.csv 

You can also use the Bravais lattice model trained on Metal or Oxide compound by:

    python predict.py -i demo/demo.csv -o output/output.csv --use_metal
    python predict.py -i demo/demo.csv -o output/output.csv --use_oxide 

You could also change the topn_bravais and topn_spacegroup to see more or less top-N prediction from the Bravais lattice and space group models.

    python predict.py 
        -i demo/demo.csv \
        -o output/output.csv \
        --topn_bravais 2 \
        --topn_spacegroup 3 \

The output is stored in .csv format with the first two rows as header. The layout of output is shown by this example:

First row is the major index that group various predictions of one Bravais Lattice type together. The first column "formula" like its name said shows the chemical formula. "Top-n Bravais" shows this part of prediction is from the n-th most likely Bravais Lattice. In the second row, "Bravais" and "Bravais prob" shows the Bravais Lattice and its predicted probability. "a", "b", "c", "alpha", "beta", "gamma" show the predicted lattice parameters and "v" shows the unit cell volume. "Top-k Spacegroup" and "Top-k Spacegroup prob" show the k-th most likely spacegroup number and its predicted probability.

To open this .csv in python, consider using these lines:

    import pandas as pd
    pd.read_csv("output/output.csv",  header=[0,1])

The package is wrapper of fastai learner, and is easy to use. The following example shows the basic workfolow:

    import pandas as pd
    from cryspnet.models import *

    formula = pd.read_csv("demo/demo.csv")
    BE = load_Bravais_models()
    LPB = load_Lattice_models()
    SGB = load_SpaceGroup_models()

    featurizer = FeatureGenerator()
    predictors = featurizer.generate(formula)

    bravais_probs, bravais = BE.predicts(predictors, topn_bravais=1)
    predictors['bravais'] = bravais

    spacegroup_probs, spacegroup = SGB.predicts(predictors, topn_spacegroup=1)
    latticeparameter = LPB.predicts(predictors)

More examples could be finded in Notebook.

PyXtal is an open-source library that could generated structures from chemcial formula and space group inputs. Combinint with this library, here we demonstrate a workflow to create candidate crystal structures for only chemical formula input. To install PyXtal:

    pip install pyxtal==0.0.8

Here is an example to use PyXtal in conjuct with the prediction from CRYSPNet:

    python predict.py -i demo/demo.csv -o output/output.csv 

    python random_crystal.py \
        -i output/output.csv \
        -o output/random_crystal \
        --topn_bravais 1 \
        --topn_spacegroup 1 \
        --n_workers 4 \
        --n_trails 100