warp-pep Command Reference

All-atom peptide structure builder and mutation tool using internal coordinate geometry.

Synopsis

warp-pep [--stream] <command> [options]

Global Options

--stream

flag

Emit NDJSON progress events to stderr

Commands

build - Build Peptide Structure

Construct all-atom peptide structures from amino acid sequences.

warp-pep build [INPUT] [OPTIONS]

Input Options (Choose One)

-s, --sequence

string

One-letter amino acid sequence (e.g., ACDEFGH)

-t, --three-letter

string

Three-letter codes, hyphen-separated (e.g., ALA-CYX-HID-GLU)

-j, --json

string

Path to JSON configuration file

Output Options

-o, --output

string

Output file path

-f, --format

string

Output format: pdb, cif, xyz, gro, mol2, crd, lammps

Structure Options

--oxt

flag

Add terminal carboxyl oxygen (OXT)

--detect-ss

flag

Auto-detect disulfide bonds (Sγ-Sγ < 2.5 Å) and relabel CYS → CYX

--preset

string

Ramachandran preset:

extended / ext (φ=180°, ψ=180°, default)
alpha-helix / alpha / helix (φ=-57°, ψ=-47°)
beta-sheet / beta / sheet (φ=-120°, ψ=+130°)
polyproline / ppii (φ=-75°, ψ=+145°)

Backbone Angle Customization

--phi

string

Comma-separated phi angles (degrees, length = residues-1)

--psi

string

Comma-separated psi angles (degrees, length = residues-1)

--omega

string

Comma-separated omega angles (degrees, length = residues-1, default=180)

--stream

flag

Emit progress events to stderr

Examples

Build alpha helix:

warp-pep build -s AAAAA --preset alpha-helix --oxt -o helix.pdb

Build from three-letter codes with disulfide detection:

warp-pep build -t ALA-CYX-HID-GLU --detect-ss --oxt -o peptide.pdb

Build with custom backbone angles:

warp-pep build -s AAA --phi=-60,-60 --psi=-45,-45 --omega=180,180 -o custom.pdb

Build from JSON spec:

warp-pep build -j peptide_spec.json

mutate - Mutate Residues

Mutate one or more residues in an existing structure or sequence.

warp-pep mutate [INPUT] -m MUTATIONS [OPTIONS]

Input Options (Choose One)

-i, --input

string

Input structure file (PDB, etc.)

-S, --sequence

string

One-letter amino acid sequence

-t, --three-letter

string

Three-letter codes, hyphen-separated

Mutation Specification

-m, --mutations

string

required

Comma-separated mutations in format <from><position><to>:

A5G - Mutate residue 5 from Ala to Gly
W123A - Mutate residue 123 from Trp to Ala
A5G,L10W,C15M - Multiple mutations

Output Options

-o, --output

string

Output file path

-f, --format

string

Output format: pdb, cif, xyz, gro, mol2, crd, lammps

Structure Options

--oxt

flag

Add terminal carboxyl oxygen (OXT)

--detect-ss

flag

Auto-detect disulfide bonds after mutation

--preset

string

Ramachandran preset (same options as build)

--stream

flag

Emit progress events to stderr

Examples

Mutate single residue:

warp-pep mutate -i input.pdb -m A2G -o mutated.pdb

Multiple mutations:

warp-pep mutate -i helix.pdb -m A2G,A3W,A5M -o multi_mutant.pdb

Build and mutate in one step:

warp-pep mutate -s ACDEF -m C2G,D3W --oxt -o out.pdb

JSON Configuration

Single-Chain Specification

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

residues

array

required

Three-letter amino acid codes

preset

string

Ramachandran preset name

oxt

boolean

default:"false"

Add terminal oxygen

detect_ss

boolean

default:"false"

Auto-detect disulfide bonds

mutations

array

List of mutation strings

output

string

Output file path

format

string

Output format

Multi-Chain Specification

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

chains

array

required

Array of chain specifications

chains[].id

string

required

Chain identifier (A-Z)

chains[].residues

array

required

Three-letter amino acid codes for this chain

chains[].preset

string

Ramachandran preset for this chain

Supported Amino Acids

Standard 20

One-letter codes: A C D E F G H I K L M N P Q R S T V W Y

Code	Residue	Code	Residue	Code	Residue	Code	Residue
A	Alanine	F	Phenylalanine	L	Leucine	R	Arginine
C	Cysteine	G	Glycine	M	Methionine	S	Serine
D	Aspartate	H	Histidine	N	Asparagine	T	Threonine
E	Glutamate	I	Isoleucine	P	Proline	V	Valine
		K	Lysine	Q	Glutamine	W	Tryptophan
						Y	Tyrosine

Amber Force Field Variants

Code	Residue	Description
CYX	Cysteine	Disulfide-bonded (SS bridge)
HID	Histidine	Nδ-H tautomer
HIE	Histidine	Nε-H tautomer
HIP	Histidine	Doubly protonated (+1)
ASH	Aspartate	Protonated (neutral)
GLH	Glutamate	Protonated (neutral)
LYN	Lysine	Neutral (deprotonated)

Non-Standard Residues

Code	Canonical	Description
MSE	MET	Selenomethionine (Se replaces S)
PCA	GLU	Pyroglutamic acid (cyclic)

D-Amino Acids

Use lowercase one-letter codes for D-enantiomers:

a c d e f g h i k l m n p q r s t v w y

Example: aGlA = D-Ala, Gly, Leu, Ala

Ramachandran Presets

Preset	φ (phi)	ψ (psi)	Description
`extended` / `ext`	180°	180°	Extended conformation (default)
`alpha-helix` / `alpha` / `helix`	-57°	-47°	Right-handed α-helix
`beta-sheet` / `beta` / `sheet`	-120°	+130°	Anti-parallel β-sheet
`polyproline` / `ppii`	-75°	+145°	Polyproline-II helix

Supported Output Formats

pdb

format

Protein Data Bank format (CONECT, TER supported)

cif / mmcif / pdbx

format

Crystallographic Information File

xyz

format

Simple XYZ coordinate format

gro

format

GROMACS format (nm → Å conversion)

mol2

format

Tripos MOL2 format

crd

format

Amber coordinate format

lammps / lmp

format

LAMMPS data format

Streaming Mode

When --stream is enabled, warp-pep emits NDJSON events to stderr: operation_started:

{
  "event": "operation_started",
  "operation": "build",
  "input_path": "AAAAA",
  "total_chains": 1,
  "total_residues": 5,
  "total_mutations": null
}

operation_complete:

{
  "event": "operation_complete",
  "operation": "build",
  "total_atoms": 67,
  "total_residues": 5,
  "total_chains": 1,
  "output_path": "helix.pdb",
  "elapsed_ms": 123
}

error:

{
  "event": "error",
  "message": "invalid amino acid code: X"
}

Advanced Features

Custom Backbone Angles

Specify per-residue backbone dihedrals:

warp-pep build -s AAA \
  --phi=-60,-60 \
  --psi=-45,-45 \
  --omega=180,180 \
  --oxt -o custom.pdb

Note: Angle arrays must have length num_residues - 1 (inter-residue junctions).

Disulfide Bond Detection

Auto-detect Sγ-Sγ distances < 2.5 Å and relabel CYS → CYX:

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

Also writes SSBOND records to PDB output.

Cis Peptide Bonds

For cis bonds (e.g., preceding proline):

warp-pep build -s GPP --omega=180,0 -o cis_bond.pdb

Terminal Capping

Note: ACE (N-terminal) and NME (C-terminal) caps are supported in the Rust library API but not currently exposed via CLI flags. Use the Python/Rust API directly for capping workflows.

Exit Codes

Code	Meaning
0	Success
1	Invalid input, configuration error, or runtime failure

Notes

All bond lengths, angles, and dihedrals use standard peptide geometry
Peptide bonds default to trans (ω = 180°)
Internal units are Angstrom
Multi-chain structures renumber residues globally (sequential seq_id)
JSON spec is self-contained (may include output path and format)

Integration Examples

Build and Solvate with warp-pack

# Build peptide
warp-pep build -s ACDEFGHIKLM --preset alpha-helix -o peptide.pdb

# Create packing config
cat > solvate.json <<EOF
{
  "box": {"size": [40.0, 40.0, 40.0]},
  "min_distance": 2.0,
  "add_box_sides": true,
  "output": {"path": "solvated.pdb"},
  "structures": [
    {"path": "peptide.pdb", "count": 1, "rotate": false},
    {"path": "tip3p.pdb", "count": 1000}
  ]
}
EOF

# Pack with water
warp-pack --config solvate.json

Python Subprocess Wrapper

import subprocess

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

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

# Mutate residue
subprocess.run([
    "warp-pep", "mutate",
    "-i", "helix.pdb",
    "-m", "A2G",
    "-o", "mutated.pdb"
], check=True)

Peptide Builder Guide

Complete guide to peptide building workflows

warp-pack Reference

Molecule packing for solvation

Commands

​warp-pep Command Reference

​Synopsis

​Global Options

​Commands

​build - Build Peptide Structure

​Input Options (Choose One)

​Output Options

​Structure Options

​Backbone Angle Customization

​Examples

​mutate - Mutate Residues

​Input Options (Choose One)

​Mutation Specification

​Output Options

​Structure Options

​Examples

​JSON Configuration

​Single-Chain Specification

​Multi-Chain Specification

​Supported Amino Acids

​Standard 20

​Amber Force Field Variants

​Non-Standard Residues

​D-Amino Acids

​Ramachandran Presets

​Supported Output Formats

​Streaming Mode

​Advanced Features

​Custom Backbone Angles

​Disulfide Bond Detection

​Cis Peptide Bonds

​Terminal Capping

​Exit Codes

​Notes

​Integration Examples

​Build and Solvate with warp-pack

​Python Subprocess Wrapper

Peptide Builder Guide

warp-pack Reference

Build docs developers (and LLMs) love

warp-pep Command Reference

Synopsis

Global Options

Commands

build - Build Peptide Structure

Input Options (Choose One)

Output Options

Structure Options

Backbone Angle Customization

Examples

mutate - Mutate Residues

Input Options (Choose One)

Mutation Specification

Output Options

Structure Options

Examples

JSON Configuration

Single-Chain Specification

Multi-Chain Specification

Supported Amino Acids

Standard 20

Amber Force Field Variants

Non-Standard Residues

D-Amino Acids

Ramachandran Presets

Supported Output Formats

Streaming Mode

Advanced Features

Custom Backbone Angles

Disulfide Bond Detection

Cis Peptide Bonds

Terminal Capping

Exit Codes

Notes

Integration Examples

Build and Solvate with warp-pack

Python Subprocess Wrapper