MatterGen: fine-tuned crystal generation, and what the checkpoints actually commit you to

The problem MatterGen targets, and who it is written for

Inorganic materials discovery has a search-space problem that is not solved by filtering a database. MatterGen is positioned as a generative model for inorganic materials design across the periodic table, and the README frames the core capability as fine-tuning to steer generation toward a wide range of property constraints. That framing matters: the project is not a screening tool over existing structures, it produces new candidate crystals. The audience is therefore narrow. You need a Linux machine with a CUDA GPU, Python 3.10 or newer, and enough familiarity with crystallography to read a .cif file and judge whether the output is chemically plausible. The README assumes Linux and a CUDA GPU for the primary installation path, so a researcher on a laptop without a discrete GPU is not the intended user. The property names in the checkpoint list (dft_band_gap, dft_mag_density, ml_bulk_modulus) also signal that this is aimed at people who already know which property they care about and roughly what values are interesting. If you are still deciding what to compute, the model will not make that decision for you.

Diffusion over crystal structures, and what the guidance factor does

The mechanism visible in the README is denoising diffusion over crystal structures. Generation writes out a denoising trajectory per structure when --record-trajectories is left at its default of True, and the output files are described as containing the full denoising trajectory for each individual structure. That is a useful detail for anyone debugging samples: you can inspect intermediate frames in generated_trajectories.zip rather than only the final structure. Conditioning is implemented through classifier-free diffusion guidance. The README states that --diffusion-guidance-factor corresponds to the gamma parameter in classifier-free diffusion guidance, that setting it to zero corresponds to unconditional generation, and that increasing it tends to produce samples which adhere more to the input property values, though at the expense of diversity and realism. That is a real trade-off stated plainly by the documentation, and it is the knob most users will spend time tuning. The base checkpoints (mattergen_base on Alex-MP-20, mp_20_base on MP-20) are unconditional, so guidance only becomes meaningful once you load a fine-tuned checkpoint that has a property head to guide against. Nothing in the supplied material describes the internal architecture beyond this, so claims about the backbone, the number of parameters or the training compute would be guesses.

Installing MatterGen: uv, PyTorch Geometric wheels and Git LFS

The README gives two installation routes. The source route uses uv: pip install uv, then uv venv .venv --python 3.10, source .venv/bin/activate, then uv pip install -e . The released-package route installs from PyPI with a pinned wheel index: uv pip install mattergen --find-links https://data.pyg.org/whl/torch-2.2.0+cu121.html. That find-links URL pins torch 2.2.0 with cu121, so the wheel index you use has to match the PyTorch and CUDA combination you actually have. This is the first thing that breaks in practice, and the README does not offer a matrix of alternatives. The second dependency is Git LFS, because datasets and checkpoints live inside the repository through it. The README suggests checking with git lfs --version, and if that fails, sudo apt install git-lfs followed by git lfs install. If you cloned before installing LFS, the checkpoints are not real files. You can fetch a single one with git lfs pull -I checkpoints/<model_name> --exclude="", which is the practical command when you want one checkpoint rather than the whole set. Checkpoints are also on Hugging Face and, per the README, are downloaded from there by default when requested, so the LFS route is a fallback rather than a requirement.

Running generation: the two commands that cover most use

Unconditional sampling takes two environment variables and one command. Set MODEL_NAME=mattergen_base and RESULTS_PATH=results/, then run mattergen-generate $RESULTS_PATH --pretrained-name=$MODEL_NAME --batch_size=16 --num_batches 1. The sample count is batch_size multiplied by num_batches. Passing --seed=42 resets the Python, NumPy and PyTorch random generators before sampling, but the README is explicit that exact reproducibility is only expected with the same software and hardware configuration because some CUDA operations are nondeterministic. Treat the seed as a way to make a run repeatable on one machine, not as a guarantee across machines. Output lands in three places: generated_crystals_cif.zip with one .cif per structure, generated_crystals.extxyz with all structures as frames, and, if --record-trajectories is True (the default), generated_trajectories.zip. Conditional generation swaps the checkpoint and adds two arguments: mattergen-generate $RESULTS_PATH --pretrained-name=dft_mag_density --batch_size=16 --properties_to_condition_on="{'dft_mag_density': 0.15}" --diffusion_guidance_factor=2.0. Note the quoting: the property dictionary is passed as a string on the command line, so shell quoting errors are a likely source of confusing failures. To sample from your own trained model, replace --pretrained-name=$MODEL_NAME with --model_path=$MODEL_PATH.

The checkpoint list is the real constraint on what you can ask for

This is the limitation that decides most adoption questions. MatterGen conditions on properties that a fine-tuned checkpoint was trained for. The released set is finite: chemical_system, space_group, dft_mag_density, dft_band_gap, ml_bulk_modulus, dft_mag_density_hhi_score and chemical_system_energy_above_hull. If the property you care about is not in that list, the README does not document a general mechanism for conditioning on it. You would be training or fine-tuning your own model, which is a different project in terms of effort. There is a second, quieter caveat in the README: the checkpoints provided were re-trained using this repository, so they are not identical to the ones used in the paper, and results may slightly deviate from those in the publication. Anyone trying to reproduce a specific number from the Nature paper should read that note before spending a week on a discrepancy. Third, the conditioning target is a scalar you supply, and the guidance factor trades adherence against diversity and realism, so a run that hits the target value is not automatically a run that produced plausible crystals. The evaluation step exists for that reason, and skipping it means you are reading a number without checking the structure behind it.

Apple Silicon is flagged experimental, and the README means it

The README carries a warning block stating that running MatterGen on Apple Silicon is experimental, to be used at your own risk, and that you must run export PYTORCH_ENABLE_MPS_FALLBACK=1 before any training or generation run. Two things follow. First, the installation instructions assume Linux and a CUDA GPU, so an M-series machine is off the documented path even with the environment variable set. Second, the fallback variable is a signal that some operations are falling back rather than running natively, which is consistent with the note about nondeterministic CUDA operations and reproducibility. If your only machine is a Mac, the honest reading of the material is that you are outside the supported configuration and should expect to debug rather than generate. A cloud GPU instance matching the cu121 wheel index is the lower-risk route, and it also removes the question of whether a slow run is a fallback problem or a model problem.

How it differs from enumerating structures with a database or a substitution heuristic

The obvious alternative for a materials team is to work from an existing computed database, filter by composition and stability, and apply substitution or prototype rules. That approach has different failure characteristics. A database filter can only return structures that someone already computed, so it cannot propose a composition outside the covered space, and its output quality is bounded by the coverage of the source data. MatterGen generates structures, and the diffusion trajectory is part of the output, which means the model can in principle propose arrangements that are not in the training set. The cost of that is the opposite problem: generated structures need validation, and the README's own evaluation section exists because a generated crystal is a hypothesis, not a result. A second difference is conditioning granularity. A database filter gives you exact, auditable constraints over recorded values. MatterGen gives you a learned conditioning signal with a guidance factor that trades target adherence against diversity, so the constraint is soft and tunable rather than exact. Teams that need a defensible, reproducible selection criterion may find the filter easier to defend. Teams that have exhausted the database and need new candidates are the ones for whom generation adds something a filter cannot.

Maintenance, versioning and the MIT licence

The repository is MIT licensed, which is permissive and places few obligations on how you use or redistribute the code. That is a statement about the licence text, not legal advice; if you plan to ship something commercial on top of the checkpoints, read the licence file and the model card yourself, since the supplied material does not describe checkpoint-specific terms beyond the repository licence. On maintenance, the visible signal is release cadence: v1.0.1, v1.0.2 and v1.0.3 all landed on 2025-07-23, and the last push to the default branch is dated 2026-08-27. Three patch releases in one day reads as a burst of fixes around a 1.0 stabilization rather than a steady maintenance rhythm, and the material does not say what changed in each. The practical upgrade cost is dominated by the environment rather than the code: the PyPI route pins a specific torch and CUDA wheel index, so moving to a newer PyTorch means finding a matching PyTorch Geometric wheel build yourself. The checkpoint caveat compounds this. Because the released checkpoints were retrained in this repository and differ from the paper versions, upgrading the code without pinning the checkpoint can silently change your results. Record the checkpoint name and the wheel index alongside any output you intend to compare later.

Editorial conclusion

Adopt MatterGen if your target property is already covered by one of the released fine-tuned checkpoints (chemical_system, space_group, dft_mag_density, dft_band_gap, ml_bulk_modulus, dft_mag_density_hhi_score, chemical_system_energy_above_hull) and you have a CUDA GPU plus Git LFS available. Do not adopt it expecting a general property-conditioning interface: the README does not document a way to condition on a property outside that list without training or fine-tuning your own model, and Apple Silicon is explicitly flagged as experimental. Before committing, verify that git lfs --version returns a version string, that your PyTorch and CUDA combination matches the wheel index you install from, and whether the checkpoint you intend to use was retrained in this repository rather than taken from the paper.

Official sources

1. License: MIT
2. microsoft/mattergen on GitHub
3. Project website
4. README
5. Releases