DOCSEARCHbyAlgolia
Submit Docs

MatterGen

repository·main·Indexed 23 days ago

https://github.com/microsoft/mattergen

A generative model for inorganic materials design across the periodic table, version 1.0.3. MatterGen enables the generation of new crystal structures and can be fine-tuned or guided via diffusion to steer generation toward specific property constraints, such as magnetic density, band gap, and bulk modulus. The package includes CLI tools for material generation (mattergen-generate), evaluation of novelty and stability (mattergen-evaluate), and model training (mattergen-train).

Tokens
11.9K
Snippets
19
Records
63
Agent score
83%

What's inside MatterGen

  1. Overview of the MP-20 dataset

    main

    The MP-20 dataset is a collection of materials data originally published by Jain et al. (2013). This specific version has been modified for use with MatterGen. It is published under the Creative Commons Attribution 4.0 International License.

    Data Modifications Applied:

    • Element Filtering: Structures containing Tc, Pm, or any element with an atomic number $\ge 84$ are excluded.
    • DFT Relaxation: Structures were relaxed using Density Functional Theory (DFT) with a PBE functional to ensure consistent energy values.
    • Training Set Filtering: For the training set, any structure with an energy above the hull greater than 0.1 eV/atom was removed.

  3. Understand the MatterGen data release structure

    main

    The data-release directory contains datasets and experimental measurements used in the paper "A generative model for inorganic materials design". The directory structure is as follows:

    • cifs/: Zipped CIF data files for crystal structures from the paper.
    • alex-mp/: The Alex-MP dataset used for training and fine-tuning MatterGen.
    • mp-20/: The MP-20 dataset (provided for reproducibility, though not part of the primary release).
    • nanoindentaion_measurements/: CSV files containing load-depth profiles for TaCr2O6 nanoindentation measurements.
    • xrd_measurements/: Measured XRD profiles (xrd_measurement_TaCr2O6.dat) and Rietveld refinement FullProf files (Rietveld_refinment_TaCr2O6) for TaCr2O6.
    • xps_measurements/: XPS scan raw files for TaCr2O6 in .vgd format (covering whole spectra and individual peaks).

  4. What is MatterGen and how is it used?

    main

    MatterGen is a diffusion-based generative model designed for inorganic materials design. It jointly predicts a material's atomic fractional coordinates, elements, and unit cell lattice vectors.

    Primary Use Cases

    • Unconditional Generation: Generate new inorganic material candidates without specific property constraints.
    • Property-Conditioned Generation: Generate materials based on target property values such as bulk modulus, chemical system, or magnetic density.
    • Fine-tuning: The base model can be fine-tuned on user-provided datasets containing property-labeled materials to enable generation with custom target properties.

    Technical Constraints and Scope

    • Atom Limit: The model is designed for unit cells containing up to 20 atoms. It is not intended for structures with more than 20 atoms.
    • Material Type: It is specialized for inorganic crystalline materials. It is not suitable for organic crystals or non-crystalline materials.
    • Element Restrictions: The model does not support noble gases, radioactive elements, or elements with an atomic number greater than 84 (e.g., Tc and Pm are excluded).

  5. Data filtering and modifications in the alex-mp dataset

    main

    The alex-mp dataset has undergone specific preprocessing and filtering steps to ensure consistency and suitability for training. When using this data, be aware of the following modifications:

    • Element Filtering: Structures containing Tc, Pm, or any element with an atomic number $\ge 84$ are excluded.
    • Energy Consistency: Structures were relaxed using Density Functional Theory (DFT) with a PBE functional to provide consistent energy values.
    • Training Set Constraints:
      • Size Limit: Any structure with more than 20 atoms inside the unit cell was removed.
      • Stability Limit: Any structure with an energy above the hull higher than 0.1 eV/atom was removed.

  6. MatterGen Training Datasets Overview

    main

    MatterGen utilizes several datasets for training and evaluation:

    • MP-20: Contains ~45k general inorganic materials, including most experimentally known materials with $\le$ 20 atoms in the unit cell.
    • Alex-MP-20: A larger dataset of ~600k structures derived from MP-20 and Alexandria, containing structures with $\le$ 20 atoms in the unit cell and below 0.1 eV/atom of the convex hull.
    • Alex-MP (Reference): A reference set containing 845,997 structures with DFT energies, used to evaluate the novelty and stability of generated samples.

  7. Use the TRI2024 correction scheme for evaluation

    main

    For benchmarking and general tasks, it is recommended to use the TRI2024 correction scheme and its corresponding reference dataset. This requires downloading the reference dataset via Git LFS first.

    Steps:

    1. Download the reference dataset: git lfs pull -I data-release/alex-mp/reference_TRI2024correction.gz --exclude="".
    2. Run evaluation with the --reference_dataset_path and --energy_correction_scheme="TRI2024" flags (if providing external energies).
    git lfs pull -I data-release/alex-mp/reference_TRI2024correction.gz --exclude=""

mattergen-evaluate --structures_path=$RESULTS_PATH --relax=True --structure_matcher='disordered' --save_as="$RESULTS_PATH/metrics.json" --reference_dataset_path="data-release/alex-mp/reference_TRI2024correction.gz"

  8. Pre-process datasets for training

    main

    Before training, you must unpack and preprocess the dataset files using the csv-to-dataset command.

    To preprocess the mp_20 dataset:

    1. Download the file from LFS.
    2. Unzip it into a datasets directory.
    3. Run csv-to-dataset specifying the folder, dataset name, and cache folder.

    To preprocess the larger alex_mp_20 dataset, follow the same steps using the alex-mp data release. Note that this process can take approximately 1 hour.

    # For mp_20
git lfs pull -I data-release/mp-20/ --exclude=""
unzip data-release/mp-20/mp_20.zip -d datasets
csv-to-dataset --csv-folder datasets/mp_20/ --dataset-name mp_20 --cache-folder datasets/cache

# For alex_mp_20
git lfs pull -I data-release/alex-mp/alex_mp_20.zip --exclude=""
unzip data-release/alex-mp/alex_mp_20.zip -d datasets
csv-to-dataset --csv-folder datasets/alex_mp_20/ --dataset-name alex_mp_20 --cache-folder datasets/cache

  9. Fine-tune on custom property data

    main

    To use your own property data for fine-tuning, follow these steps:

    1. Register Property: Add the property name to the PROPERTY_SOURCE_IDS list in mattergen/common/utils/globals.py.
    2. Update Dataset: Add a new column with the property name (typically float values) to your training and validation CSV files (e.g., datasets/alex_mp_20/train.csv).
    3. Re-process: Re-run the csv-to-dataset command for your dataset.
    4. Configure Embedding: Add a <your_property>.yaml config file to mattergen/conf/lightning_module/diffusion_module/model/property_embeddings. For float values, you can copy an existing config like dft_mag_density.yaml. For complex properties, you may need to implement a custom PropertyEmbedding subclass.
    5. Fine-tune: Run mattergen-finetune referencing your new property name.

  10. Fine-tune MatterGen on property data

    main

    You can fine-tune the base model (or a model you trained yourself) on specific properties (e.g., dft_mag_density).

    Single Property Fine-tuning: Use mattergen-finetune. You must specify the adapter.pretrained_name (either mattergen_base or your custom $MODEL_PATH) and use Hydra overrides to map the property to the adapter's embeddings.

    Multi-property Fine-tuning: To fine-tune on multiple properties, add an override for each property using the pattern: +lightning_module/diffusion_module/model/property_embeddings@adapter.adapter.property_embeddings_adapt.<property>=<property> and include all properties in the data_module.properties list.

    # Single property fine-tuning
export PROPERTY=dft_mag_density
mattergen-finetune adapter.pretrained_name=mattergen_base data_module=mp_20 +lightning_module/diffusion_module/model/property_embeddings@adapter.adapter.property_embeddings_adapt.$PROPERTY=$PROPERTY ~trainer.logger data_module.properties=["$PROPERTY"]

# Multi-property fine-tuning
export PROPERTY1=dft_mag_density
export PROPERTY2=dft_band_gap 
export MODEL_NAME=mattergen_base
mattergen-finetune adapter.pretrained_name=$MODEL_NAME data_module=mp_20 +lightning_module/diffusion_module/model/property_embeddings@adapter.adapter.property_embeddings_adapt.$PROPERTY1=$PROPERTY1 +lightning_module/diffusion_module/model/property_embeddings@adapter.adapter.property_embeddings_adapt.$PROPERTY2=$PROPERTY2 ~trainer.logger data_module.properties=["$PROPERTY1","$PROPERTY2"]

  11. Best practices for fine-tuning MatterGen on new properties

    main

    When fine-tuning MatterGen to support property-guided generation for a new property, follow these recommendations to ensure performance:

    • Data Quantity: Use a sufficient amount of labeled property data, ideally at least several thousand labeled structures.
    • Data Coverage: Ensure the training data has good coverage of the property values within the range you intend to target during generation.
    • Quality Dependency: Note that the effectiveness of property-guided generation is heavily dependent on the quality and quantity of the property labels used during training.

  12. Run MatterGen on Apple Silicon

    main

    Running MatterGen on Apple Silicon is currently experimental. To use it, you must set the following environment variable before starting any training or generation run:

    export PYTORCH_ENABLE_MPS_FALLBACK=1