ml-generative-mattergen

Files (9)

• SKILL.md
• README.md · examples/finetuning/
• adapter_config.json · examples/finetuning/example_finetuned_model/
• adapter_model.bin · examples/finetuning/example_finetuned_model/
• make_dummy.py · examples/finetuning/
• run_finetune_example.sh · examples/finetuning/
• prepare_training_data.py · scripts/
• run_finetuning.py · scripts/
• setup_mattergen.py · scripts/

SKILL.md (first lines)

# MatterGen Structure Generation Skill

This skill provides tools for generating novel inorganic material structures using MatterGen, a state-of-the-art diffusion-based generative model for crystalline materials.

## 1. Prerequisites

> [!IMPORTANT]
> **GPU Required**: MatterGen generation needs a CUDA GPU (NVIDIA driver ≥ 525).

- Runs as the `mattergen` MCP server and its scripts run in the `mattergen` environment: on x86_64 a uv environment created on first use (CUDA 12.6 or 13 by driver), on aarch64 the `generative` container image.
- A MatterGen checkout next to this project as `../mattergen`, or anywhere with `MATTERGEN_REPO` pointing to it. MatterGen's PyPI distribution omits the data files it needs (sampling configs, GemNet scale factors), so it runs from the checkout, as upstream installs it. Fetch it with the setup script, which pins the verified commit, skips the LFS checkpoints (the weights come from Hugging Face) and replaces `np.math`, which NumPy 2 removed:

  ```bash
  ${CLAUDE_SKILL_DIR}/../../venv/run mattergen python ${CLAUDE_SKILL_DIR}/scripts/setup_mattergen.py
  ```

  `venv/run` mounts it into the container on aarch64.
- On aarch64 (e.g. NVIDIA DGX Spark) the image carries PyG's extensions compiled for CUDA, which PyG publishes no aarch64 wheels for; nothing needs building on the host.

## 2. Available Models

MatterGen provides several pretrained models:

- `mattergen_base`: Base unconditional generative model
- `mp_20_base`: Materials Project base model
- `dft_mag_density`: Model for magnetic density conditioning
- `chemical_system`: Model for chemical system conditioning

## 3. MCP Tool Usage

The MCP tool automatically loads models when needed - no explicit load step required.

### Unconditional Generation

Generate novel structures without conditioning:

```python
from mcp_base import mattergen.generate_structures

result = mattergen.generate_structures(
    model_name="mattergen_base",
    num_structures=10,
    batch_size=10,
    output_dir="research/my_project/generated"
)
```

### Chemical System Conditioning

Generate structures from a specific chemical system (controls which elements appear):

```python
result = mattergen.generate_structures(
    chemical_system="Li-Fe-P-O",  # Automatically uses chemical_system model
    guidance_scale=1.0,  # Recommended for chemical system conditioning
    num_structures=20,
    batch_size=10,
    output_dir="research/cathode_materials/generated"
)
```

> [!NOTE]
> Chemical system conditioning controls which **elements** appear, but **NOT** the exact stoichiometry.
> For example, `chemical_system="Li-Zr-Cl"` can generate Li3Cl5, LiZrCl4, Li2ZrCl5, etc., but you cannot specify exactly "Li2ZrCl6".



## 4. Fine-Tuning (Skill Scripts)

Fine-tune MatterGen on custom datasets using the skill scripts:

### Step 1: Prepare Training Data

```bash
# Convert structures and properties to CSV format
${CLAUDE_SKILL_DIR}/../../venv/run mattergen python ${CLAUDE_SKILL_DIR}/scripts/prepare_training_data.py \
  --structures-json training_structures.json \
  --property-name "formation_energy" \
  --output training_data.csv
```

**Training data JSON format**:
```json
[
  {
    "structure": {<pymatgen Structure dict>},
    "properties": {"formation_energy": -2.5}
  },
  ...
]
```

### Step 2: Run Fine-Tuning

```bash
${CLAUDE_SKILL_DIR}/../../venv/run mattergen python ${CLAUDE_SKILL_DIR}/scripts/run_finetuning.py \
  --training-data training_data.csv \
  --property-name "formation_energy" \
  --base-model "mattergen_base" \
  --epochs 100 \
  --output-dir finetuned_formation_energy
```

**Fine-tuning parameters**:
- `--training-data`: Path to CSV from Step 1
- `--property-name`: Property to condition on (must match CSV column)
- `--base-model`: Starting model (mattergen_base, chemical_system, etc.)
- `--epochs`: Training epochs (100-200 recommended)
- `--learning-rate`: Learning rate (default: 5e-6)
- `--batch-size`: Batch size (default: 32)

> [!TIP]
> - Start with 2 epochs for quick testing
> - Use 100-200 epochs for actual fine-tuning
> - GPU required (fine-tuning on CPU is extremely slow)

## 5. Output Files

### Generation Output

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills