ML Cluster Expansion

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:

${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.

${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.

# 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):

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.

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).