Mat Pourbaix Diagram

Pourbaix Diagram

<!-- mcp-tools-note -->

[!NOTE] Steps written server.tool are MCP tool calls: fairchem.load_model is the load_model tool of the fairchem server (mcp__fairchem__load_model, or mcp__plugin_atomistic-skills_fairchem__load_model 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 fairchem python -m src.mcp_server.cli fairchem load_model key=value relax_structure key=value

Goal

To calculate thermodynamically consistent Pourbaix (pH-voltage) diagrams for assessing the aqueous electrochemical stability of materials. This skill uses Machine Learning Interatomic Potentials (MLIPs) for solid phase energies combined with Materials Project data for aqueous species, following the rigorous methodology of Persson et al. (2012)¹.

Applications:

• Alkaline-stable solid-state electrolytes (Li-air batteries)
• Corrosion-resistant materials
• Aqueous battery electrodes
• Electrochemical stability screening

Features

• Automated Referenced: Fetches elemental energies from elemental-energies skill to fill missing terminal entries (e.g., if you relaxed LiCoO2 but forgot Li metal, it will be auto-loaded).
• H2O Reference: Checks resources/h2o_energies.json values matching the MLIP checkpoint. If found, uses this pre-calculated energy. If not found, falls back to look for H2O relaxation in the --relaxed_solids directory.
• MP2020 Compatibility: Automatically detects if compatibility corrections are needed via gga-ggau-mixed-mlips.yaml.

Background

Pourbaix Diagrams

A Pourbaix diagram shows the thermodynamically stable phases as a function of pH and electrochemical potential (voltage vs. SHE). The diagram maps stability domains for solids and dissolved ions in aqueous environments.

Critical: Thermodynamic Consistency

The Challenge: Mixing computational (MLIP/DFT) solid energies with experimental aqueous ion data creates energy scale mismatch.

The Solution (Persson et al. 2012)¹: Water correction that aligns MLIP water formation energy with experimental Gibbs free energy. We use a robust cycle that fixes the hydrogen reference to the Standard Hydrogen Electrode (SHE) scale.

3. Automated Referencing

The script calculate_pourbaix.py automatically:

1. Fetches per-atom elemental energies from the elemental-energies skill.
2. Applies thermodynamic corrections for H₂ gas ($S^\circ$, $\Delta H$) to deriving $\mu_H$.
3. Uses a locally relaxed H₂O structure to derive $\mu_O$, ensuring correct water formation energy.
   • H2O Reference: Checks resources/h2o_energies.json values matching the MLIP checkpoint. If found, uses this pre-calculated energy. If not found, falls back to look for H2O relaxation in the --relaxed_solids directory.

Is calculate_water_correction.py still needed? No. The correction logic is now internal to calculate_pourbaix.py to simplify the workflow.

Resources

• resources/h2o_energies.json: A dictionary mapping MLIP checkpoint names (e.g., MACE-MP-medium, uma-s-1_omat) to the relaxed energy of H2O per atom. This avoids the need for manual H2O relaxation when using supported MLIPs.

Methods: MLIP vs. Pure Materials Project

There are two ways to generate Pourbaix diagrams using this skill. Prioritize Method 1 (Pure MP) if the target chemical system's energies are likely present and accurate in the Materials Project database. Use Method 2 (MLIP) when investigating novel materials, specific polymorphs not in MP, or when high-fidelity MLIP energies are preferred.

Method 1: Pure Materials Project (Recommended for existing materials)

Use calculate_pourbaix_mp.py to fetch entries directly from Materials Project. This requires no local relaxation and uses MP's internal DFT energies.

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/calculate_pourbaix_mp.py \
    --comp_dict "Li=1,Fe=1" \
    --output ./output_dir

Method 2: MLIP-Calculated Workflow (For novel/specific structures)

Use this workflow to calculate stability using specific MLIP models. This involves fetching structures, relaxing them, and then generating the diagram.

1. Get Structures from Materials Project

Query all relevant solid phases and reference molecules:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_pourbaix_structures.py \
    --chemsys "Zn" \
    --output_dir ./structures/

This retrieves:

• All solid phases in the chemical system (e.g., Zn, ZnO, ZnO2, etc.)
• Reference molecule: H₂O (Required for water correction)

2. Select Foundation Potential

Choose an appropriate MLIP based on your system (see ${CLAUDE_SKILL_DIR}/../ml-foundation-potentials/SKILL.md).

[!IMPORTANT] Recommended for Pourbaix diagrams: MatPES-r2SCAN To ensure energy scale compatibility with Materials Project aqueous ions (which are often based on r2SCAN or compatible corrections), prioritize using r2SCAN-trained MLIPs.

• MatGL: CHGNet-PES-MatPES-r2SCAN-1M-2026.9
• MACE: MACE-MH-1 with matpes_r2scan head.