---
name: cohp-analysis
description: >
  Use when the user asks about COHP (Crystal Orbital Hamilton Population),
  chemical bonding analysis, LOBSTER output, orbital-resolved bonding,
  or bonding/antibonding character between atoms.
tags: [analysis, bonding, COHP, LOBSTER, orbital]
---

# COHP Analysis

## Overview

Crystal Orbital Hamilton Population (COHP) analysis quantifies bonding and
antibonding interactions between atom pairs in a crystal. COHP data is
generated by LOBSTER from DFT output (typically VASP). CatGo reads
COHPCAR.lobster files and provides interactive visualization and data
extraction.

Key applications:
- **Bonding character**: Identify bonding (negative COHP) vs antibonding (positive COHP) regions
- **Orbital-resolved analysis**: Decompose into s-s, p-d, d-d contributions
- **Catalyst design**: Understand adsorbate-surface bonding (e.g., CO-Pt d-band interactions)
- **Integrated COHP (ICOHP)**: Quantitative bond strength from ICOHPLIST.lobster

## MCP Tool: catgo_analyze (workflow node: cohp_analysis)

COHP analysis in the Claude Code MCP uses the workflow node `cohp_analysis`
or the dedicated `catgo_cohp_data` tool (in the full MCP server). The
workflow engine automatically reads LOBSTER output from a parent
calculation step.

### Workflow-Based COHP Analysis

Add a `cohp_analysis` node downstream of a VASP calculation that produces
LOBSTER output:

```json
{"tool": "catgo_workflow", "arguments": {
  "action": "add_node", "workflow_id": "wf_bonding",
  "node_type": "cohp_analysis",
  "params": {"source": "parent_step"}
}}
```

### Upload COHPCAR File Directly

If you have a COHPCAR.lobster file, upload it to create a session:

```json
{"tool": "catgo_analyze", "arguments": {
  "action": "dos",
  "params": {"file_type": "COHPCAR", "remote_path": "/path/to/COHPCAR.lobster"}
}}
```

The upload returns a `session_id` along with metadata: `nspin`, `npoints`,
`efermi`, and a list of available bonds with atom labels and distances.

### Retrieve COHP Data for Specific Bonds

Once you have a `session_id`, query COHP data for specific bonds:

```json
{"tool": "catgo_analyze", "arguments": {
  "action": "dos",
  "params": {
    "session_id": "abc-123",
    "bond_indices": [1, 3],
    "include_orbitals": false
  }
}}
```

### Orbital-Resolved COHP

To decompose bonding into orbital contributions (e.g., p-d interactions):

```json
{"tool": "catgo_analyze", "arguments": {
  "action": "dos",
  "params": {
    "session_id": "abc-123",
    "bond_indices": [1],
    "include_orbitals": true,
    "orbital_filter": ["p-d", "s-d"]
  }
}}
```

### Aggregate Orbital COHP

Sum orbital contributions for a cleaner view:

```json
{"tool": "catgo_analyze", "arguments": {
  "action": "dos",
  "params": {
    "session_id": "abc-123",
    "bond_indices": [1],
    "aggregate_orbitals": true,
    "orbital_filter": ["d-d"]
  }
}}
```

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| session_id | string | Session ID from COHPCAR upload |
| bond_indices | int[] | 1-based bond numbers to retrieve (from upload metadata) |
| include_orbitals | bool | Include orbital-decomposed COHP (default false) |
| orbital_filter | string[] | Filter orbital pairs, e.g. `["p-d", "s-d"]` |
| aggregate_orbitals | bool | Sum filtered orbital contributions (default false) |

## Complete Workflow: VASP + LOBSTER COHP

### 1. Run VASP static calculation with LOBSTER-compatible settings

```json
{"tool": "catgo_workflow", "arguments": {
  "action": "create", "name": "COHP bonding analysis"
}}
```

```json
{"tool": "catgo_workflow", "arguments": {
  "action": "add_node", "workflow_id": "wf_cohp",
  "node_type": "single_point",
  "params": {
    "software": "vasp",
    "ENCUT": 520,
    "ISYM": -1,
    "NBANDS": 200,
    "system_name": "static for LOBSTER"
  }
}}
```

### 2. Add COHP analysis node

```json
{"tool": "catgo_workflow", "arguments": {
  "action": "add_node", "workflow_id": "wf_cohp",
  "node_type": "cohp_analysis",
  "params": {"source": "parent_step"}
}}
```

### 3. Connect and run

```json
{"tool": "catgo_workflow", "arguments": {
  "action": "connect",
  "workflow_id": "wf_cohp",
  "from_id": "static_node_id",
  "to_id": "cohp_node_id",
  "from_handle": "data",
  "to_handle": "data"
}}
```

## Return Format

COHP data is returned as:

```json
{
  "energies": [-10.0, -9.95, ...],
  "series": [
    {
      "label": "Fe1-O2 (2.01 A)",
      "spin_up": [0.12, 0.15, ...],
      "spin_down": [-0.08, -0.10, ...],
      "bond_index": 1,
      "is_total": true
    }
  ],
  "efermi": -2.35
}
```

Negative COHP values indicate bonding interactions; positive values indicate
antibonding.

## Common Pitfalls

1. LOBSTER requires specific VASP settings: `ISYM = -1` (no symmetry),
   sufficient `NBANDS`, and `LWAVE = .TRUE.` for wavefunction output.
2. Bond indices are 1-based (matching LOBSTER convention). Index 0 is
   the "Average" across all bonds.
3. Large COHPCAR files (>100 MB) may take several seconds to parse.
   The session is cached for 30 minutes after last access.
4. For spin-polarized calculations, both `spin_up` and `spin_down`
   channels are returned. Non-magnetic calculations have `spin_down = null`.
5. ICOHP (integrated COHP) from ICOHPLIST.lobster provides a single
   number per bond -- use it for quick bond strength comparisons
   without needing the full energy-resolved COHP.