README.md

---
base_model: microsoft/mattergen
library_name: mattergen
tags:
- diffusion
- mattergen
- crystal-generation
- materials-science
- transition-metal-oxides
- energy-above-hull
---

# Simergy Diffusion TMO Alpha

Fine-tuned MatterGen diffusion checkpoint for transition-metal oxide crystal generation. The model was full-finetuned from the MatterGen `chemical_system_energy_above_hull` checkpoint and is conditioned on:

- `chemical_system`
- `energy_above_hull`

Recommended diffusion guidance factor: `9.0`.

## Files

- `config.yaml`: MatterGen/Hydra config for loading this checkpoint directory.
- `checkpoints/last.ckpt`: final training checkpoint, used by MatterGen when `checkpoint_epoch="last"`.
- `checkpoints/epoch=59-loss_val=0.36.ckpt`: best monitored validation checkpoint.
- `metrics.csv`: training and validation metrics emitted by Lightning.
- `training_overrides.yaml`: Hydra overrides used for the finetuning run.
- `hparams.yaml`: Lightning hparams file.

## Usage

Download the repository and pass the snapshot directory as MatterGen `model_path`:

```python
from huggingface_hub import snapshot_download

model_dir = snapshot_download("HishaamA/simergy-diffusion-tmo-alpha")
print(model_dir)
```

Then generate with MatterGen:

```bash
python -m mattergen.scripts.generate ./results/tmo_samples \
  --model_path="$MODEL_DIR" \
  --checkpoint_epoch=last \
  --properties_to_condition_on="{'chemical_system':'Li-O','energy_above_hull':0.05}" \
  --diffusion_guidance_factor=9.0 \
  --record_trajectories=False
```

For the best monitored checkpoint, use `--checkpoint_epoch=best`.

## Training Summary

- Base checkpoint: `chemical_system_energy_above_hull`
- Finetuning mode: full finetuning
- Dataset config: `tmo_ehull`
- Trainer config: `single_gpu`
- Max epochs: `100`
- Accumulated gradient batches: `8`
- Learning rate: `5e-6`

Generated structures should be independently screened and validated before any downstream scientific or engineering use.