crystalflow

crystalflow is a flow-based deep learning model for crystal structure prediction. It uses neural ordinary differential equations and continuous density modeling with normalizing flows to generate plau

SKILL.md

GitHub

CrystalFlow

Overview

CrystalFlow is a generative model for crystal structure prediction developed by MindSpore. It uses a flow-based architecture built on neural ordinary differential equations (Neural ODEs) and continuous density modeling with normalizing flows. Compared to diffusion-model-based generative methods, CrystalFlow is simpler, more flexible, and more efficient.

The model achieves competitive performance on benchmarks such as MP20 (Materials Project dataset with up to 20 atoms per unit cell) and can generate stable crystal structures for various chemical compositions.

This skill provides inference capabilities for CrystalFlow on Ascend NPU using MindSpore.


When to Use

  • Crystal structure prediction: Generate stable crystal structures from chemical composition
  • Materials discovery: Explore plausible crystal structures for new materials
  • Property-guided generation: Generate structures with specific target properties (when conditioned)
  • Multi-element systems: Handle complex multi-element material systems

How It Works

1. Dataset Acquisition and Processing

Dataset Requirements

Requirement Description
Data Format Crystal structure data in format compatible with MindChem (structure coordinates, lattice parameters)
Data Size MP20: ~15,000 stable structures; Perovskite: ~10,000; Carbon: ~2,000
Data Source MindSpore MindChem dataset repository

Data Acquisition Methods

  1. MindSpore Dataset Download: Download from https://download-mindspore.osinfra.cn/mindscience/mindchemistry/diffcsp/dataset/
  2. Supported Datasets:
    • perov_5: Perovskite dataset
    • carbon_24: Carbon crystal dataset
    • mp_20: Materials Project dataset (up to 20 atoms/unit cell)
    • mpts_52: Materials Project dataset (up to 52 atoms/unit cell)

Data Preprocessing

  • Download the dataset folders and dataset_prop.txt property file
  • Place them under the dataset folder in the project directory
  • Structure:
    crystalflow/
    └─dataset/
          perov_5/
          carbon_24/
          mp_20/
          mpts_52/
          dataset_prop.txt
    

2. Environment Configuration and Dependencies

Framework

CrystalFlow uses MindSpore (not PyTorch) as its deep learning framework.

Dependency Installation

# Clone MindChem repository
git clone https://gitcode.com/mindscience/MindChem.git
cd MindChem/applications/crystalflow

# Install dependencies
pip install -r requirement.txt

Environment Requirements

Requirement Specification
Python Version Python 3.8+
Framework MindSpore
Hardware Ascend NPU (910 series recommended)
Memory At least 16GB RAM recommended
Disk Space At least 10GB for model and datasets

Installation Steps

  1. Step 1: Clone the MindChem repository
  2. Step 2: Navigate to MindChem/applications/crystalflow
  3. Step 3: Download required datasets from the dataset link
  4. Step 4: Install dependencies with pip install -r requirement.txt
  5. Step 5: Configure the config.yaml file for inference parameters

3. Usage Limitations and Notes

Model Limitations

Limitation Type Description
Functional Limitations Generates crystal structures; requires composition as input
Performance Limitations Generation quality depends on training data coverage
Scale Limitations MP20 dataset supports up to 20 atoms per unit cell
Input Format Requires chemical composition (element types and counts)

Notes

  • Note 1: CrystalFlow is based on flow modeling (normalizing flows), not diffusion models
  • Note 2: The model is trained on stable crystal structures from the Materials Project
  • Note 3: For best results, use compositions that are well-represented in the training data
  • Note 4: Generated structures may require additional relaxation/optimization for energy minimization

4. Model Invocation Guide

Model Initialization

The model weights are loaded automatically during inference. Configuration is managed through config.yaml.

Running Inference

From the CrystalFlow directory:

cd MindChem/applications/crystalflow

# Edit config.yaml to set test parameters
# Key settings:
#   - test.num_eval: number of samples to generate per composition
#   - test.checkpoint_path: path to model checkpoint

# Run inference
python evaluate.py

Crystal Generation Task Checklist

When the user is asking for a crystal generation task, collect and confirm these inputs first:

  1. composition: chemical formula such as Li2O, BaTiO3, or an explicit element-count mapping
  2. n_structures: number of candidate crystals to sample
  3. checkpoint: local CrystalFlow checkpoint path
  4. app_dir: local CrystalFlow application directory
  5. save_dir: directory for generated structures

Recommended local workflow:

  1. Prepare the local CrystalFlow project and checkpoint
  2. Generate a config template for this crystal generation run
  3. Fill in the composition-related field required by your local CrystalFlow code
  4. Run python evaluate.py
  5. Convert generated outputs into CIF and continue with relaxation, property prediction, or diffraction analysis

Example Local Script

This skill includes an example script at scripts/generate_crystal_local_example.py to illustrate how to organize a local crystal generation task.

Example usage:

python scripts/generate_crystal_local_example.py \
  --composition "Li2O" \
  --n_structures 5 \
  --checkpoint /path/to/crystalflow.ckpt \
  --app_dir /path/to/MindChem/applications/crystalflow \
  --config_out ./generated_crystalflow_config.yaml

What this example script does:

  • Records the target composition for the current generation task
  • Writes a minimal local inference config template
  • Reminds you to fill in the composition source expected by your own CrystalFlow implementation
  • Prints the local command you should run next

Important:

  • The script is for local workflow illustration
  • It does not assume CrystalFlow is deployed as a service
  • Different CrystalFlow forks may store composition input in different places, so you should adapt the generated config template to your actual project

Configuration (config.yaml)

Key inference parameters in config.yaml:

test:
  num_eval: 10          # Number of samples per composition
  checkpoint_path: ""   # Path to model checkpoint
  save_dir: "./results" # Output directory for generated structures

Result Post-processing

  • Generated crystal structures are saved to the directory specified in config.yaml
  • Output format: crystal structure files (coordinates, lattice parameters)
  • Evaluation metrics can be computed using compute_metric.py

Reference Resources