---
title: MM-GBSA inputs and parameters
description: >-
  Complex structures, the solvent model, and minimization toggle for
  MM-GBSA calculations.
tags:
  - mmgbsa
  - inputs
---

You provide a docked protein-ligand complex — most often straight from a DiffDock job — and can choose the implicit solvent model. The pose quality matters most: without MD sampling, MM-GBSA scores the input pose as given, so a clean, non-clashing complex is what makes the energy meaningful.

## Webapp input methods

The .bloom* webapp provides several input methods for MM-GBSA calculations.

## Input type selection

| Input Type | Description | Example |
|------------|-------------|---------|
| **From DiffDock** | Docked complex from a previous DiffDock job — Ivy carries the pose's PDB text into `complex_pdb` | Select job from canvas or panel |
| **Complex PDB** (`complex_pdb`) | Single PDB file with protein and ligand | Upload `complex.pdb` |
| **Protein + Ligand** (`protein_pdb` + `ligand_sdf`) | Separate protein PDB and ligand SDF | Upload `protein.pdb` + `ligand.sdf` |
| **From previous job** | Complex from any docking tool output, carried into `complex_pdb` the same way | Select from completed jobs |

There's no separate S3-URI parameter — this backend takes structure content directly, so a stored complex is read and its text passed as `complex_pdb`.

## Structure requirements

### Protein requirements
- **Standard amino acids**: All 20 canonical residues fully supported
- **Non-standard residues**: Modified amino acids (phosphoserine, methylated lysine, etc.) may cause parameterization failures; remove or replace with standard equivalents
- **Missing atoms**: All heavy atoms in binding site residues must be present; missing atoms cause errors
- **Protonation**: Histidine tautomers (HID, HIE, HIP) and cysteine protonation affect results significantly
- **Disulfide bonds**: Detected automatically from PDB SSBOND records or distance-based criteria

### Ligand requirements
- **Supported elements**: C, H, N, O, S, P, F, Cl, Br, I
- **Charge states**: Formal charges on the ligand must be correct for the binding site pH
- **Hydrogen atoms**: Added automatically if missing; explicit hydrogens preferred for accuracy
- **Metal coordination**: Metal-containing ligands require special handling and may not be fully supported

### Complex requirements
- **Proximity**: Ligand must be within the protein binding site (not solvent-exposed)
- **Single ligand**: One ligand per calculation; multi-ligand complexes require separate runs
- **Chain selection**: For multi-chain proteins, all chains in contact with the ligand are included
- **Water molecules**: Crystallographic waters are removed by default (implicit solvent replaces them)

## Force field

The tool always parameterizes with **AMBER14** (ff14SB for the protein, GAFF2 for the ligand) — there is no force-field parameter to change it.

## Implicit solvent models

`solvent_model` selects the Generalized Born term:

| Value | Full Name | Speed | Accuracy | Description |
|-------|-----------|-------|----------|-------------|
| **`gb_obc2`** (default) | Onufriev-Bashford-Case II | Fast | Good | Best general-purpose GB model; accurate for most systems |
| **`gb_obc1`** | Onufriev-Bashford-Case I | Fast | Slightly lower | Earlier OBC generation; kept for comparison |
| **`gb_hct`** | Hawkins-Cramer-Truhlar | Fastest | Approximate | Legacy option; lower accuracy for polar interactions |

### Choosing a solvent model

- The "accuracy" column above is a general characterization of the GB models, not a measurement on this tool. Where it has been tested head to head, **GB_OBC1 outperformed GB_OBC2** on four of six protein systems and was the best of the three models overall — see [agreement with wet lab](/docs/mmgbsa/translatability#agreement-with-wet-lab). Do not read `gb_obc2` as the most accurate option simply because it is the default
- Use **`gb_hct`** only for rapid screening when speed is more important than precision

## Calculation parameters

These are the actual parameters this tool accepts:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| **complex_pdb** | string | — | Protein-ligand complex PDB content. Supply this, or `protein_pdb` + `ligand_sdf` |
| **protein_pdb** | string | — | Protein PDB content (use with `ligand_sdf`) |
| **ligand_sdf** | string | — | Ligand SDF content, with 3D coordinates (use with `protein_pdb`) |
| **solvent_model** | string | `gb_obc2` | Implicit solvent model: `gb_obc2`, `gb_obc1`, or `gb_hct` |
| **ionic_strength** | float | 0.15 | Ionic strength in mol/L, range 0–1.0 |
| **minimize_complex** | boolean | true | Run energy minimization before evaluation |
| **decompose_residues** | boolean | true | **Inert.** Per-residue decomposition is not implemented — there is no ΔG_bind to decompose. The backend does not declare this parameter, so it is dropped; the backend's own `include_per_residue` stays `false` and is rejected with an error if set true |

Each call scores one complex. To score several DiffDock poses (top 1, top 5, or all), Ivy makes one `mmgbsa_calculate` call per pose — there's no `poses` selector on the tool itself. There's also no way to choose a force field, tune minimization steps/algorithm/tolerance, or set backbone restraints, surface tension, or a non-bonded cutoff — those aren't exposed parameters here.

## Input preprocessing

### Automatic preprocessing steps

When a complex is submitted, .bloom* performs:

1. **Hydrogen addition**: Missing hydrogens are added based on pH 7.4
2. **Protonation assignment**: Histidine tautomers assigned based on local hydrogen bonding
3. **Water removal**: Crystallographic waters removed (implicit solvent)
4. **Ion removal**: Counter-ions and buffer molecules removed
5. **Ligand parameterization**: GAFF2 parameters assigned automatically
6. **Charge calculation**: AM1-BCC charges computed for the ligand

### Manual preprocessing recommendations

- **Protonation**: If your binding site has unusual pH, manually set protonation states before submission
- **Missing loops**: Rebuild missing protein loops before MM-GBSA (low-confidence ESMFold regions may affect results)
- **Alternate conformations**: Remove alternate conformers; keep the A conformation
- **Multi-model PDB**: Only the first model is used; split NMR ensembles if needed

## Previous job integration

### Compatible tools
- **DiffDock**: Primary source of docked poses (most common workflow)
- **Chained docking runs**: complexes from a structure → docking chain the orchestrator ran for you
- **Other docking tools**: Any tool producing PDB-format complexes

### Data handling
- **Pose selection**: Choose specific poses from multi-pose docking results
- **Batch scoring**: Score multiple complexes from a virtual screening campaign
- **Provenance tracking**: Maintains connection to the original docking job

## Batch processing strategies

### Single complex scoring
- Recommended for detailed analysis with per-residue decomposition
- Use all available poses from DiffDock for comprehensive ranking

### Compound series scoring
- Score one pose per compound against the same target
- Use consistent force field and solvent model across all compounds
- Compare relative binding energies rather than absolute values

### Virtual screening rescoring
- Score top hits from a docking campaign
- Use `gb_obc2` for the best accuracy-speed tradeoff, or `gb_hct` when speed matters more than precision
- Filter by DeltaG_bind threshold before detailed analysis

## Read next