Peptide Builder (warp-pep)

warp-pep is your agent’s peptide construction toolkit - build all-atom structures from sequences, apply mutations, and export to any format.

warp-pep builds peptides from internal coordinate geometry (bond lengths, angles, dihedrals) for all 20 standard amino acids plus Amber force field variants.

The warp-md wheel exposes warp-pep as a CLI entry point. Python workflows drive the CLI via subprocess.

pip install warp-md

Quick Start

CLI
Python

# Build a 5-residue alpha-helix
warp-pep build -s AAAAA --preset alpha-helix --oxt -o helix.pdb

# Build with Amber naming and disulfide detection
warp-pep build -t ALA-CYX-HID-GLU --oxt --detect-ss -o out.pdb

# Mutate residue 2 from Ala to Gly
warp-pep mutate -i input.pdb -m A2G -o mutated.pdb

import subprocess

subprocess.run([
    "warp-pep", "build", 
    "-s", "AAAA", 
    "--preset", "alpha-helix", 
    "--oxt", 
    "-o", "peptide.pdb"
], check=True)

subprocess.run([
    "warp-pep", "mutate", 
    "-i", "peptide.pdb", 
    "-m", "A2G", 
    "-o", "peptide_mutated.pdb"
], check=True)

Input Modes

One-Letter Codes

The simplest way to build peptides:

warp-pep build -s ACDEFGHIKLMNPQRSTVWY -o all20.pdb

D-Amino acids: Use lowercase for D-form variants (e.g., a = D-Ala). Mixed sequences work: "aGlA" = D-Ala, Gly, Leu, Ala.

Three-Letter Codes with Amber Variants

For force field precision:

warp-pep build -t ALA-CYX-HID-HIP-ASH-GLH-LYN -o amber.pdb

Code	Residue	When to Use
CYX	Cysteine	Disulfide-bonded CYS
HID	Histidine	Nδ protonated (default in many FF)
HIE	Histidine	Nε protonated
HIP	Histidine	Double protonated (charged)
ASH	Aspartate	Protonated (neutral)
GLH	Glutamate	Protonated (neutral)
LYN	Lysine	Neutral (deprotonated)

JSON Specification

For full control:

spec.json

{
  "residues": ["ALA", "CYX", "HID", "GLU"],
  "preset": "alpha-helix",
  "oxt": true,
  "detect_ss": true,
  "mutations": ["A1G"],
  "output": "out.pdb"
}

warp-pep build -j spec.json

Ramachandran Presets

Choose your secondary structure:

warp-pep build -s AAAAA --preset alpha-helix

Preset	φ	ψ	Structure
`extended`	180°	180°	Extended strand
`alpha-helix`	-57°	-47°	Right-handed α-helix
`beta-sheet`	-120°	+130°	Anti-parallel β-sheet
`polyproline`	-75°	+145°	Polyproline-II helix

Custom Backbone Angles

For precise control, specify per-junction angles:

# 3 residues = 2 junctions
warp-pep build -s AAA \
  --phi=-60,-60 \
  --psi=-45,-45 \
  --omega=180,180 \
  --oxt

Angle arrays must have length num_residues - 1. Use --omega ~0 for cis peptide bonds (rare, usually preceding proline).

Mutations

CLI

# Single mutation
warp-pep mutate -i input.pdb -m A5G -o out.pdb

# Multiple mutations
warp-pep mutate -i input.pdb -m A5G,L10W,C15M -o out.pdb

# Build and mutate in one shot
warp-pep mutate -s ACDEF -m C2G,D3W --oxt -o out.pdb

Mutation format: <from><position><to>

A5G = Ala at position 5 → Gly
W123A = Trp at position 123 → Ala

Python

import subprocess

# Mutate position 5 Ala -> Gly
subprocess.run([
    "warp-pep", "mutate", 
    "-i", "input.pdb", 
    "-m", "A5G", 
    "-o", "out.pdb"
], check=True)

# Multiple mutations
subprocess.run([
    "warp-pep", "mutate", 
    "-i", "input.pdb", 
    "-m", "A5G,L10W", 
    "-o", "out_multi.pdb"
], check=True)

Multi-Chain Structures

Build complexes with multiple chains:

multi.json

{
  "chains": [
    {
      "id": "A",
      "residues": ["ALA", "CYS", "GLU"],
      "preset": "alpha-helix"
    },
    {
      "id": "B",
      "residues": ["GLY", "VAL", "TRP"],
      "preset": "beta-sheet"
    }
  ],
  "oxt": true,
  "detect_ss": true
}

warp-pep build -j multi.json -o complex.pdb

import json
import subprocess

spec = {
    "chains": [
        {"id": "A", "residues": ["ALA", "GLU", "VAL"], "preset": "alpha-helix"},
        {"id": "B", "residues": ["GLY", "TRP", "SER"], "preset": "beta-sheet"},
    ],
    "oxt": True,
}
with open("multi.json", "w", encoding="utf-8") as f:
    json.dump(spec, f)

subprocess.run(["warp-pep", "build", "-j", "multi.json", "-o", "complex.pdb"], check=True)

Disulfide Bonds

Auto-detect and label disulfide bonds:

warp-pep build -t ALA-CYS-CYS-ALA --detect-ss -o out.pdb

import subprocess

subprocess.run([
    "warp-pep", "build", 
    "-t", "ALA-CYS-CYS-ALA", 
    "--detect-ss", 
    "-o", "out.pdb"
], check=True)

Scans for CYS pairs with Sγ–Sγ distance < 2.5 Å and:

Relabels as CYX (Amber convention)
Writes SSBOND records to PDB

Terminal OXT

Add the carboxyl terminal oxygen:

warp-pep build -s AAA --oxt -o out.pdb

import subprocess

subprocess.run(["warp-pep", "build", "-s", "AAA", "--oxt", "-o", "out.pdb"], check=True)

OXT is added to the last residue of each chain, excluding C-terminal caps (NME).

Non-Standard Residues

warp-pep supports common non-standard amino acids:

Code	Canonical	Special Atoms
MSE	MET	SE instead of SD (selenium)
PCA	GLU	Pyroglutamic acid (cyclic, no OE2)

warp-pep build -t ALA-MSE-PCA -o nonstd.pdb

Output Formats

Export to any major format:

warp-pep build -s AAA -o peptide.pdb    # PDB
warp-pep build -s AAA -o peptide.cif    # PDBx/mmCIF
warp-pep build -s AAA -o peptide.gro    # GROMACS
warp-pep build -s AAA -o peptide.mol2   # Tripos MOL2
warp-pep build -s AAA -o peptide.lmp    # LAMMPS

import subprocess

subprocess.run(["warp-pep", "build", "-s", "AAA", "-o", "peptide.pdb"], check=True)

Complete Workflow Example

Build a disulfide-bonded peptide and solvate:

import subprocess
from warp_md.pack import Box, PackConfig, Structure, water_pdb
from warp_md.pack.export import export
from warp_md.pack.runner import run

# Build with disulfide detection
subprocess.run([
    "warp-pep", "build", 
    "-t", "ALA-CYS-CYS-GLU", 
    "--preset", "alpha-helix", 
    "--detect-ss", 
    "-o", "peptide.pdb"
], check=True)

# Solvate with warp-pack
cfg = PackConfig(
    structures=[
        Structure("peptide.pdb", count=1),
        Structure(water_pdb("tip3p"), count=800),
    ],
    box=Box((36.0, 36.0, 36.0)),
    min_distance=2.0,
)
result = run(cfg)
export(result, "pdb", "solvated_peptide.pdb")
print(f"Built and solvated peptide: {result.total_atoms} atoms")

Streaming Progress

Real-time progress events for agent integration:

warp-pep build -s ACDEFGHIKLMNPQRSTVWY --stream -o peptide.pdb

Emits NDJSON to stderr:

{"event":"operation_started","operation":"build","total_residues":20}
{"event":"operation_complete","operation":"build","total_atoms":310,"elapsed_ms":45}

See Streaming Progress API for full event reference.

Get Started

Core Concepts

Guides

AI Agents

Peptide Builder (warp-pep)

Quick Start

Input Modes

One-Letter Codes

Three-Letter Codes with Amber Variants

JSON Specification

Ramachandran Presets

Custom Backbone Angles

Mutations

CLI

Python

Multi-Chain Structures

Disulfide Bonds

Terminal OXT

Non-Standard Residues

Output Formats

Complete Workflow Example

Streaming Progress

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

AI Agents

​Quick Start

​Input Modes

​One-Letter Codes

​Three-Letter Codes with Amber Variants

​JSON Specification

​Ramachandran Presets

​Custom Backbone Angles

​Mutations

​CLI

​Python

​Multi-Chain Structures

​Disulfide Bonds

​Terminal OXT

​Non-Standard Residues

​Output Formats

​Complete Workflow Example

​Streaming Progress

​See Also

Build docs developers (and LLMs) love

Quick Start

Input Modes

One-Letter Codes

Three-Letter Codes with Amber Variants

JSON Specification

Ramachandran Presets

Custom Backbone Angles

Mutations

CLI

Python

Multi-Chain Structures

Disulfide Bonds

Terminal OXT

Non-Standard Residues

Output Formats

Complete Workflow Example

Streaming Progress

See Also