# Drug Complex System Builder

> >

- **Type:** Skill
- **Install:** `agentstack add skill-learningmatter-mit-atomisticskills-drug-complex-system-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [learningmatter-mit](https://agentstack.voostack.com/s/learningmatter-mit)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [learningmatter-mit](https://github.com/learningmatter-mit)
- **Source:** https://github.com/learningmatter-mit/AtomisticSkills/tree/main/.agents/skills/drug-complex-system-builder
- **Website:** https://arxiv.org/abs/2605.24002

## Install

```sh
agentstack add skill-learningmatter-mit-atomisticskills-drug-complex-system-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# drug-complex-system-builder

## Goal
To take a prepared protein (PDB) and a validated ligand pose (SDF) and produce a fully parameterized, solvated, ion-neutralized OpenMM simulation bundle ready for [drug-protein-ligand-md](../drug-protein-ligand-md/SKILL.md).

The output bundle includes:
- Serialized OpenMM System XML (force field parameters, constraints)
- Full-precision initial state XML (positions + box vectors for exact restart)
- Solvated PDB with protein + ligand + water + ions (for visualization)
- Provenance JSON recording all build parameters

## Instructions

### 1. Prepare inputs

Required inputs:
- **Receptor PDB**: from [drug-protein-prep](../drug-protein-prep/SKILL.md) (protonated, missing residues resolved).
- **Ligand SDF**: from [drug-pose-validation](../drug-pose-validation/SKILL.md) or [drug-docking-vina](../drug-docking-vina/SKILL.md). Must have 3D coordinates in the receptor frame and explicit hydrogens.

### 2. Build the solvated complex

```bash
# Env: drugmd-agent
python .agents/skills/drug-complex-system-builder/scripts/build_complex.py \
  --receptor docking/inputs/protein_prepared.pdb \
  --ligand docking/validation/valid_poses.sdf \
  --ligand_ff openff-2.2.0 \
  --protein_ff amber/ff14SB \
  --water_model tip3p \
  --box_padding 12.0 \
  --ionic_strength 0.15 \
  --output_dir md/system/
```

Key parameters:
- `--ligand_ff`: Force field for the ligand. Options: `openff-2.2.0` (Sage, recommended), `gaff-2.11`. OpenFF Sage is generally preferred for drug-like molecules.
- `--protein_ff`: Protein force field. Default: `amber/ff14SB`.
- `--water_model`: Water model. Default: `tip3p`. Options: `tip3p`, `tip3pfb`, `tip4pew`, `opc`, `spce`. Use `tip3pfb` or `opc` for better accuracy at higher cost.
- `--box_padding`: Minimum distance from solute to box edge in Angstroms (default: 12.0). Use 10-12 A for production; smaller values risk periodic image artifacts.
- `--ionic_strength`: Target NaCl concentration in mol/L (default: 0.15, physiological). The system is always charge-neutralized first; additional ion pairs are added to reach the target ionic strength. The ionic strength calculation does not count the neutralization ions (they are treated as bound to the solute).
- `--pose_index`: Which pose from the SDF to use (default: 0, the top-ranked pose).
- `--box_shape`: Simulation box geometry (default: `cube`). Options: `cube`, `dodecahedron`, `octahedron`. Dodecahedron and octahedron use ~30% less water for the same minimum solute-edge distance.
- `--hydrogen_mass`: Hydrogen mass in amu for hydrogen mass repartitioning (default: 4.0). With HMR (3-4 amu), the script uses `AllBonds` constraints, enabling 4-5 fs timesteps (OpenMM recommends 5 fs with `LangevinMiddleIntegrator`). Set to 1.008 to disable HMR (uses `HBonds` constraints, requires 2 fs timestep). Note: at 4 amu, methyl carbons become lighter than their bonded hydrogens, which can affect dynamics in some systems (particularly membranes). Use 3 amu if this is a concern. The downstream MD skill **must** use a matching timestep (check `hmr_enabled` and `constraints` in the provenance JSON).

### 3. Inspect outputs

The script produces:
- `md/system/complex_solvated.pdb`: solvated system for visualization (PDB precision: 0.001 A)
- `md/system/system.xml`: serialized OpenMM System (force field parameters, constraints)
- `md/system/state_initial.xml`: full-precision positions and box vectors for simulation restart
- `md/system/build_provenance.json`: records all build parameters, atom counts, box dimensions, HMR status, constraint type

Visually inspect `complex_solvated.pdb` to verify:
- The ligand is in the expected binding pocket
- No steric clashes between protein and ligand
- Water fills the box uniformly
- Ions are distributed (not clustered)

### 4. Troubleshooting

Common issues:
- **Ligand parameterization fails**: ensure the ligand SDF has explicit hydrogens and correct bond orders. Re-run [drug-ligand-prep](../drug-ligand-prep/SKILL.md) if needed. The script assigns AM1-BCC partial charges automatically; any pre-existing charges in the SDF are overwritten to ensure deterministic behavior.
- **Steric clash warning**: the script checks minimum protein-ligand interatomic distances before solvation. If you see a clash warning, the docking pose may need refinement. Mild clashes (1.0-1.5 A) can often be resolved by energy minimization, but severe clashes (100 heavy atoms) or metal-containing compounds, parameterization may require manual intervention.
- **Protein force field**: Only Amber-family force fields (ff14SB, ff19SB) are supported through openmmforcefields. CHARMM support would require a different builder.
- **Box shape**: Defaults to cubic. Dodecahedron and truncated octahedron are supported via `--box_shape` (requires OpenMM 8.0+).

## References

- Maier, J. A.; Martinez, C.; Kasavajhala, K.; Wickstrom, L.; Hauser, K. E.; Simmerling, C. ff14SB: Improving the Accuracy of Protein Side Chain and Backbone Parameters from ff99SB. *J. Chem. Theory Comput.* **2015**, *11*, 3696-3713. https://doi.org/10.1021/acs.jctc.5b00255
- Boothroyd, S.; Behara, P. K.; Madin, O. C.; et al. Development and Benchmarking of Open Force Field 2.0.0: The Sage Small Molecule Force Field. *J. Chem. Theory Comput.* **2023**, *19*, 3251-3275. https://doi.org/10.1021/acs.jctc.3c00039
- Eastman, P.; Swails, J.; Chodera, J. D.; et al. OpenMM 7: Rapid Development of High Performance Algorithms for Molecular Dynamics. *PLoS Comput. Biol.* **2017**, *13*, e1005659. https://doi.org/10.1371/journal.pcbi.1005659

---

**Author:** Matthew Cox
**Contact:** [GitHub @mcox3406](https://github.com/mcox3406)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [learningmatter-mit](https://github.com/learningmatter-mit)
- **Source:** [learningmatter-mit/AtomisticSkills](https://github.com/learningmatter-mit/AtomisticSkills)
- **License:** MIT
- **Homepage:** https://arxiv.org/abs/2605.24002

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-learningmatter-mit-atomisticskills-drug-complex-system-builder
- Seller: https://agentstack.voostack.com/s/learningmatter-mit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.