ml-cluster-expansion

Files (13)

• SKILL.md
• README.md · examples/AgPd_DFT_CE/
• README.md · examples/CuAg_CE/
• cluster_expansion.json · examples/CuAg_CE/
• README.md · examples/pdptag_ternary_surface/
• analyze_mc.py · examples/pdptag_ternary_surface/
• mc_trajectory_final.cif · examples/pdptag_ternary_surface/
• mc_trajectory_initial.cif · examples/pdptag_ternary_surface/
• parse_atat.py · examples/pdptag_ternary_surface/
• parse_primordial.py · examples/pdptag_ternary_surface/
• primordial.cif · examples/pdptag_ternary_surface/
• extract_mc_structures.py · scripts/
• prepare_disordered.py · scripts/

SKILL.md (first lines)

# Cluster Expansion

<!-- mcp-tools-note -->
> [!NOTE]
> Steps written `server.tool` are MCP tool calls: `smol.train_cluster_expansion` is the `train_cluster_expansion`
> tool of the `smol` server (`mcp__smol__train_cluster_expansion`, or
> `mcp__plugin_atomistic-skills_smol__train_cluster_expansion` when installed as a plugin).
> Without a connected server, run the same tools from the shell. Tools named in
> one command share a process, so a model loaded by `load_model` stays loaded:
>
> ```bash
> ${CLAUDE_SKILL_DIR}/../../venv/run cpu python -m src.mcp_server.cli smol train_cluster_expansion key=value run_monte_carlo key=value
> ${CLAUDE_SKILL_DIR}/../../venv/run mlip python -m src.mcp_server.cli mace load_model key=value relax_structure key=value
> ```

## Goal

To automatically build and refine a Cluster Expansion (CE) model for a disordered material system using an **Agent-driven iterative workflow** that leverages MCP tools for efficient training, sampling, and labeling.

## Workflow Overview

1.  **Preparation**: Generate a disordered primordial structure.
2.  **Iteration 0**: systematic enumeration to generate initial structures.
3.  **Labeling**: Relax structures with an MLIP (e.g., MACE, CHGNet) via MCP.
4.  **Training**: Train the CE model using `smol.train_cluster_expansion`.
5.  **Sampling**: Run MC with `smol.run_monte_carlo` to explore configuration space.
6.  **Selection**: Extract structures from MC, compute features, and select novel configurations.
7.  **Loop**: Repeat labeling, training, and sampling until convergence.

---

### Step 1: Prepare the Primordial Structure

Use `prepare_disordered.py` to handle symmetry refinement and disorder creation. It is highly recommended to save the primordial structure as a **JSON** file to preserve exact occupancy and species information, avoiding "unrecognized species" errors during matching.

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/prepare_disordered.py \
    input_structure.cif \
    Li \
    0.5 \
    -o primordial.cif
```

---

### Step 2: Iteration 0 (Ordered Structure Sampling)

Generate an initial set of structures using systematic enumeration and D-optimality via the MCP tool. It is recommended to generate around **1000 structures** to ensure high coverage of the configuration space.

```python
# MCP Tool: smol.sample_ordered_structures
result = smol.sample_ordered_structures(
    disordered_structure="primordial.cif",
    cutoffs={2: 5.0, 3: 4.0},
    num_structures=1000,
    target_num_sites=32,
    output_dir="./ce_project/iter_0/to_label"
)
```

> [!NOTE]
> **Training Workflow**: You can perform a **Simple Training** by only using the initially `sample_ordered_structures` set. This is often sufficient for basic property predictions. For high-accuracy ground-state exploration, you should continue with the **Active Learning** loop (MC sampling and iterative refinement).

> [!TIP]
> This tool works for arbitrary disorder, including **multi-element alloys** (e.g., Co-Ni-Cr) and **multi-sublattice systems** (e.g., (Li-Na)(Cl-Br)).

---

### Step 3: Label Structures (Agent/MCP)

Use the appropriate MLIP MCP tool to **relax** the structures.

> [!IMPORTANT]
> **Fixed Cell**: Always set `relax_cell=False` during MLIP relaxation for cluster expansion training. The cluster expansion model is built on a fixed lattice.
> **Fixed Lattice**: Ensure the supercell matrix used for enumeration/sampling matches your expectation.

**Example (MACE)**:
```python
mace.load_model(model_name="MACE-OMAT-0-small", device="cuda")
mace.relax_structure(
    structure_data="./ce_project/iter_0/to_label",
    fmax=0.02,
    relax_cell=False,
    output_dir="./ce_project/iter_0/results"
)
```

---

### Step 4: Train CE

The `smol.train_cluster_expansion` tool can directly accept the directory containing relaxation results (from Step 3). It will automatically find and aggregate the training data.

```python
result = smol.train_cluster_expansion(
    disordered_structure="primordial.cif",
    training_data="ce_project/iter_0/results",
    cutoffs={2: 5.0, 3: 4.0},
    ce_file="ce_project/cluster_expansion.json"
)
```

---

> [!NOTE]
> **Training Workflow**: You can perform a **Simple Training** by only using the initially `sample_ordered_structures` set. This is often sufficient for basic property predictions. For high-accuracy ground-state exploration, you should continue with the **Active Learning** loop (MC sampling and iterative refinement).

### Step 5: Direct Feature Matrix Fitting (Optional)

In some scenarios, you may have pre-computed feature matrices and energies (e.g., from literature or external workflows). You can directly fit these without building a `ClusterSubspace` first, using the `smol.fit_feature_matrix` tool. This is also how you can utilize advanced techniques like **Sparse Group Lasso (SGL)**.

```python
# MCP Tool: smol.fit_feature_matrix
result = smol.fit_feature_matrix(
    feature_matrix_path="fm.npy",
    energies_path="e.npy",
    groups_path="groups.npy", # Required for sgl
    fit_method="sgl",         # 'ls', 'lasso', 'ridge', or 'sgl'
    alpha=0.002,

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills