ml-cluster-expansion

Cluster Expansion

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 mcp_smol_train_cluster_expansion.
5. Sampling: Run MC with mcp_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.

# Env: smol-agent
python .agents/skills/ml-cluster-expansion/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.

# MCP Tool: mcp_smol_sample_ordered_structures
result = mcp_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).