chem-bond-dissociation

Files (58)

• SKILL.md
• README.md · examples/
• README.md · examples/ethanol_mace_off23_small/
• bde_results.json · examples/ethanol_mace_off23_small/
• frag_bond0_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond0_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond1_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond1_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond2_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond2_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond3_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond3_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond4_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond4_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond5_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond5_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond6_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond6_2.xyz · examples/ethanol_mace_off23_small/
• frag_bond7_1.xyz · examples/ethanol_mace_off23_small/
• frag_bond7_2.xyz · examples/ethanol_mace_off23_small/
• intact_relaxed.xyz · examples/ethanol_mace_off23_small/
• README.md · examples/methanol_mace_omol_both/
• bde_results.json · examples/methanol_mace_omol_both/
• frag_bond0_hetero_neg_pos_1.xyz · examples/methanol_mace_omol_both/
• frag_bond0_hetero_neg_pos_2.xyz · examples/methanol_mace_omol_both/
• frag_bond0_hetero_pos_neg_1.xyz · examples/methanol_mace_omol_both/
• frag_bond0_hetero_pos_neg_2.xyz · examples/methanol_mace_omol_both/
• frag_bond0_homo_1.xyz · examples/methanol_mace_omol_both/
• frag_bond0_homo_2.xyz · examples/methanol_mace_omol_both/
• frag_bond1_homo_1.xyz · examples/methanol_mace_omol_both/
• frag_bond1_homo_2.xyz · examples/methanol_mace_omol_both/
• frag_bond2_homo_1.xyz · examples/methanol_mace_omol_both/
• frag_bond2_homo_2.xyz · examples/methanol_mace_omol_both/
• frag_bond3_homo_1.xyz · examples/methanol_mace_omol_both/
• frag_bond3_homo_2.xyz · examples/methanol_mace_omol_both/
• frag_bond4_homo_1.xyz · examples/methanol_mace_omol_both/
• frag_bond4_homo_2.xyz · examples/methanol_mace_omol_both/
• intact_relaxed.xyz · examples/methanol_mace_omol_both/
• README.md · examples/methanol_uma_omol_both/
• bde_comparison.png · examples/methanol_uma_omol_both/
• bde_results.json · examples/methanol_uma_omol_both/
• frag_bond0_hetero_neg_pos_1.xyz · examples/methanol_uma_omol_both/
• frag_bond0_hetero_neg_pos_2.xyz · examples/methanol_uma_omol_both/
• frag_bond0_hetero_pos_neg_1.xyz · examples/methanol_uma_omol_both/
• frag_bond0_hetero_pos_neg_2.xyz · examples/methanol_uma_omol_both/
• frag_bond0_homo_1.xyz · examples/methanol_uma_omol_both/
• frag_bond0_homo_2.xyz · examples/methanol_uma_omol_both/
• frag_bond1_homo_1.xyz · examples/methanol_uma_omol_both/
• frag_bond1_homo_2.xyz · examples/methanol_uma_omol_both/
• frag_bond2_homo_1.xyz · examples/methanol_uma_omol_both/
• frag_bond2_homo_2.xyz · examples/methanol_uma_omol_both/
• frag_bond3_homo_1.xyz · examples/methanol_uma_omol_both/
• frag_bond3_homo_2.xyz · examples/methanol_uma_omol_both/
• frag_bond4_homo_1.xyz · examples/methanol_uma_omol_both/
• frag_bond4_homo_2.xyz · examples/methanol_uma_omol_both/
• intact_relaxed.xyz · examples/methanol_uma_omol_both/
• plot.py · examples/methanol_uma_omol_both/
• calculate_bde.py · scripts/

SKILL.md (first lines)

# Bond Dissociation Energy Skill

## Goal

Calculate the **homolytic** and/or **heterolytic** bond dissociation energy (BDE) for each single bond in a molecule using Machine Learning Interatomic Potentials (MLIPs).

**Homolytic BDE** (radical fragments):
$$\text{BDE}_\text{homo}(A{-}B) = E(A\bullet) + E(B\bullet) - E(A{-}B)$$

**Heterolytic BDE** (ionic fragments, minimum over both polarity variants):
$$\text{BDE}_\text{hetero}(A{-}B) = \min\!\bigl(E(A^+)+E(B^-),\; E(A^-)+E(B^+)\bigr) - E(A{-}B)$$

> [!IMPORTANT]
> This skill computes BDEs by relaxing both the intact molecule and fragments with an MLIP. For purpose-trained GNN models that predict BDE directly from SMILES (MAE ~0.6 kcal/mol), consider [ALFABET](https://bde.ml.nrel.gov) or BonDNet instead.

## Background

BDE is a fundamental thermodynamic quantity that determines:
- **Drug metabolism**: CYP450 enzymes abstract H from the weakest C–H bond
- **Electrolyte stability**: Which bonds break first under electrochemical voltage
- **Combustion chemistry**: Rate-determining bond-breaking steps in fuel oxidation
- **Polymer degradation**: Weakest links in polymer backbone chains

A 2024 study (Zubatyuk et al., *JCTC*) demonstrated that MACE potentials achieve BDE RMSE of 1.37 kcal/mol for aliphatic C–H bonds in drug-like molecules, outperforming semi-empirical methods and ALFABET for BDE **ranking**.

## 1. Prerequisites

- **Environment**: `mlip` (includes RDKit, ASE, and MACE; commands run through `venv/run mlip ...`)
- **Input**: SMILES string or structure file (`.sdf`, `.mol2`)
- **RDKit**: Required for bond identification and molecular fragmentation

## 2. Choosing a Foundation Potential

Refer to the [foundation-potentials skill](../ml-foundation-potentials/SKILL.md) for model selection.

> [!IMPORTANT]
> **Model requirements by cleavage mode:**
>
> | Mode | Recommended model | `supports_charge_spin` | Validated? |
> |:---|:---|:---|:---|
> | `homolytic` | `MACE-OFF23-small/medium/large` | Not required | ✅ |
> | `heterolytic` or `both` | **`MACE-OMOL-extra-large`** (env: `mlip`) | ✅ Required | ✅ |
> | `heterolytic` or `both` | **`MACE-MH-1`** with omol head (env: `mlip`) | ✅ Required | ✅ |
> | `heterolytic` or `both` | FairChem `uma-s-1p1` with `--task_name omol` (env: `fairchem`) | ✅ Required | ✅ |
>
> **Setting charge/spin on MACE models:** use `atoms.info["charge"]` and `atoms.info["spin"]`
> (the calculator's default `info_keys` maps `"charge"` → `total_charge` / `"spin"` → `total_spin`).
> Both MACE-OMOL and MACE-MH use `joint_embedding` to condition the network on these scalars.
>
> If you request `--cleavage both` with a model that does **not** support charge/spin,
> the skill will log a warning and silently fall back to homolytic-only.
> Using `--cleavage heterolytic` with an unsupported model raises an error.
>
> **Note on single-atom fragments:** When a bond produces a bare H (or other single atom),
> heterolytic BDE is automatically skipped — neither MACE nor FairChem UMA has signed
> single-atom energies (only neutral H, C, N, O… are in the reference tables).

## 3. Calculation Workflow

### Step 1: Provide a molecule

```bash
# SMILES input (most common)
--smiles "CCO"

# Or from a structure file
--structure molecule.sdf
```

### Step 2: Run BDE calculation

**Homolytic only** (default, no charge/spin needed):
```bash
${CLAUDE_SKILL_DIR}/../../venv/run mlip python ${CLAUDE_SKILL_DIR}/scripts/calculate_bde.py \
    --smiles CCO \
    --all_bonds \
    --cleavage homolytic \
    --model_type mace \
    --model_name MACE-OFF23-small \
    --output_dir research/my_folder/bde_results
```

**Both homolytic and heterolytic** (MACE-OMOL):
```bash
${CLAUDE_SKILL_DIR}/../../venv/run mlip python ${CLAUDE_SKILL_DIR}/scripts/calculate_bde.py \
    --smiles CCO \
    --all_bonds \
    --cleavage both \
    --model_type mace \
    --model_name MACE-OMOL-extra-large \
    --output_dir research/my_folder/bde_results_both
```

**Both homolytic and heterolytic** (FairChem UMA omol):
```bash
${CLAUDE_SKILL_DIR}/../../venv/run fairchem python ${CLAUDE_SKILL_DIR}/scripts/calculate_bde.py \
    --smiles CCO \
    --all_bonds \
    --cleavage both \
    --model_type fairchem \
    --model_name uma-s-1p1 \
    --task_name omol \
    --output_dir research/my_folder/bde_results_both
```

**Heterolytic only** with FairChem UMA:
```bash
${CLAUDE_SKILL_DIR}/../../venv/run fairchem python ${CLAUDE_SKILL_DIR}/scripts/calculate_bde.py \
    --smiles CCO \
    --all_bonds \
    --cleavage heterolytic \
    --model_type fairchem \
    --model_name uma-s-1p1 \
    --task_name omol \
    --output_dir research/my_folder/bde_hetero
```

### Key Parameters

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills