Peptide Builder

The peptide builder API provides fast peptide construction and mutation capabilities through the warp-pep native bindings. Build peptides from sequences, apply custom backbone angles, and perform residue mutations.

Quick Start

from warp_md.traj_py import pep_build, pep_mutate

# Build a peptide from sequence
pep_build(
    sequence="ACDEFGHIKLMNPQRSTVWY",
    output="peptide.pdb",
    format="pdb"
)

# Mutate residues
pep_mutate(
    input_path="peptide.pdb",
    mutations=["A1G", "C2S"],  # Ala1->Gly, Cys2->Ser
    output="mutated.pdb"
)

CLI Usage

The peptide builder is also available as a command-line tool:

# Build from sequence
warp-pep build -s ACDEFGH -o peptide.pdb

# Build with custom angles
warp-pep build -s GGGG --phi -60,-60,-60 --psi -40,-40,-40 -o helix.pdb

# Mutate residues
warp-pep mutate -i peptide.pdb -m A1G,C2S -o mutated.pdb

Functions

pep_build

Build a peptide from sequence or JSON specification.

sequence

str

Single-letter amino acid sequence (e.g., “ACDEFGH”)

three_letter

str

Three-letter sequence separated by dashes (e.g., “ALA-CYS-ASP”)

json_path

str

Path to JSON file with detailed peptide specification

output

str

required

Output file path

format

str

default:"pdb"

Output format: “pdb”, “pdbqt”, “xyz”, “gro”, etc.

oxt

bool

default:"False"

Add C-terminal OXT oxygen atom

preset

str

Backbone angle preset: “extended”, “helix”, “beta”

phi

List[float]

Phi backbone angles in degrees (one per residue)

psi

List[float]

Psi backbone angles in degrees (one per residue)

omega

List[float]

Omega backbone angles in degrees (one per residue)

detect_ss

bool

default:"False"

Detect and assign secondary structure

Basic Examples:

from warp_md.traj_py import pep_build

# Build from single-letter sequence
pep_build(
    sequence="ACDEFGH",
    output="peptide.pdb"
)

# Build from three-letter codes
pep_build(
    three_letter="ALA-CYS-ASP-GLU",
    output="peptide.pdb"
)

# Build with C-terminal OXT
pep_build(
    sequence="MVHLTPEEK",
    output="peptide.pdb",
    oxt=True
)

Custom Backbone Angles:

# Build alpha helix (phi=-60, psi=-40)
pep_build(
    sequence="AAAAAA",
    phi=[-60.0] * 6,
    psi=[-40.0] * 6,
    output="helix.pdb"
)

# Build beta sheet (phi=-120, psi=120)
pep_build(
    sequence="VVVVVV",
    phi=[-120.0] * 6,
    psi=[120.0] * 6,
    output="sheet.pdb"
)

# Use preset configurations
pep_build(
    sequence="ACDEFGHIK",
    preset="helix",  # or "extended", "beta"
    output="helix.pdb"
)

Mixed Angles:

# First 3 residues helical, last 3 extended
pep_build(
    sequence="AAAAAA",
    phi=[-60, -60, -60, -180, -180, -180],
    psi=[-40, -40, -40, 180, 180, 180],
    output="mixed.pdb"
)

Output Formats:

# PDB format (default)
pep_build(sequence="ACDE", output="pep.pdb", format="pdb")

# GROMACS format
pep_build(sequence="ACDE", output="pep.gro", format="gro")

# XYZ coordinates
pep_build(sequence="ACDE", output="pep.xyz", format="xyz")

pep_mutate

Mutate residues in an existing peptide or build new peptide with mutations.

input_path

str

Input structure file path

sequence

str

Single-letter sequence (alternative to input_path)

three_letter

str

Three-letter sequence (alternative to input_path)

mutations

List[str]

required

Mutation specifications (e.g., [“A1G”, “C2S”])

output

str

required

Output file path

format

str

default:"pdb"

Output format: “pdb”, “pdbqt”, “xyz”, “gro”, etc.

oxt

bool

default:"False"

Add C-terminal OXT oxygen atom

preset

str

Backbone angle preset for newly built sequence

detect_ss

bool

default:"False"

Detect and assign secondary structure

Mutation Format: Mutations use the format {old}{position}{new} where:

old - Original residue (single letter)
position - Residue number (1-based)
new - New residue (single letter)

Examples: "A1G", "C2S", "M1A" Basic Examples:

from warp_md.traj_py import pep_mutate

# Single mutation
pep_mutate(
    input_path="peptide.pdb",
    mutations=["A1G"],  # Ala1 -> Gly
    output="mutated.pdb"
)

# Multiple mutations
pep_mutate(
    input_path="peptide.pdb",
    mutations=["A1G", "C2S", "D3E"],
    output="mutated.pdb"
)

Mutate from Sequence:

# Build sequence and apply mutations in one step
pep_mutate(
    sequence="ACDEFGH",
    mutations=["A1G", "C2S"],
    output="mutated.pdb"
)

# Equivalent with three-letter codes
pep_mutate(
    three_letter="ALA-CYS-ASP-GLU-PHE-GLY-HIS",
    mutations=["A1G", "C2S"],
    output="mutated.pdb"
)

Scanning Mutagenesis:

# Alanine scanning - mutate each position to Ala
sequence = "MVHLTPEEK"

for i, aa in enumerate(sequence, 1):
    if aa != 'A':  # Skip if already Ala
        mutation = f"{aa}{i}A"
        pep_mutate(
            sequence=sequence,
            mutations=[mutation],
            output=f"ala_scan_{i}.pdb"
        )

Combinatorial Mutations:

import itertools

# Generate all combinations of mutations at positions 1 and 2
residues = ['A', 'G', 'V', 'L']
base_seq = "AADEFGH"

for aa1, aa2 in itertools.product(residues, repeat=2):
    mutations = [f"A1{aa1}", f"A2{aa2}"]
    pep_mutate(
        sequence=base_seq,
        mutations=mutations,
        output=f"mutant_{aa1}{aa2}.pdb"
    )

Advanced Usage

JSON Specification

For complex peptides, use JSON input:

{
  "sequence": "ACDEFGH",
  "phi": [-60, -60, -60, -120, -120, -120, -120],
  "psi": [-40, -40, -40, 120, 120, 120, 120],
  "oxt": true,
  "output": "peptide.pdb"
}

pep_build(json_path="peptide.json", output="peptide.pdb")

Secondary Structure Presets

Available presets:

Preset	Phi	Psi	Description
`extended`	-180	180	Extended/random coil
`helix`	-60	-40	Alpha helix
`beta`	-120	120	Beta sheet

# Build helical peptide
pep_build(
    sequence="AAAAAAAAA",
    preset="helix",
    output="helix.pdb"
)

Common Amino Acids

Standard amino acids (single-letter codes):

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

Error Handling

try:
    pep_build(
        sequence="ACDEFGH",
        phi=[-60, -60],  # Wrong length!
        psi=[-40, -40],
        output="peptide.pdb"
    )
except ValueError as e:
    print(f"Invalid angles: {e}")

try:
    pep_mutate(
        input_path="peptide.pdb",
        mutations=["X1Y"],  # Invalid residue codes
        output="mutated.pdb"
    )
except ValueError as e:
    print(f"Invalid mutation: {e}")

CLI Reference

Build Command

warp-pep build [OPTIONS]

Options:

-s, --sequence TEXT - Single-letter sequence
-t, --three-letter TEXT - Three-letter sequence (dash-separated)
-j, --json PATH - JSON configuration file
-o, --output PATH - Output file path
-f, --format TEXT - Output format (default: pdb)
--oxt - Add C-terminal OXT
--preset TEXT - Angle preset (extended/helix/beta)
--phi TEXT - Comma-separated phi angles
--psi TEXT - Comma-separated psi angles
--omega TEXT - Comma-separated omega angles
--detect-ss - Detect secondary structure
--stream - Emit progress events (NDJSON to stderr)

Examples:

# Basic build
warp-pep build -s ACDEFGH -o peptide.pdb

# With custom angles
warp-pep build -s AAAA --phi -60,-60,-60,-60 --psi -40,-40,-40,-40 -o helix.pdb

# From JSON
warp-pep build -j config.json -o peptide.pdb

# With progress tracking
warp-pep build -s ACDEFGH -o peptide.pdb --stream

Mutate Command

warp-pep mutate [OPTIONS]

Options:

-i, --input PATH - Input structure file
-S, --sequence TEXT - Build from sequence instead
-t, --three-letter TEXT - Three-letter sequence
-m, --mutations TEXT - Comma-separated mutations (required)
-o, --output PATH - Output file path
-f, --format TEXT - Output format (default: pdb)
--oxt - Add C-terminal OXT
--preset TEXT - Angle preset for sequence building
--detect-ss - Detect secondary structure
--stream - Emit progress events

Examples:

# Mutate existing structure
warp-pep mutate -i peptide.pdb -m A1G,C2S -o mutated.pdb

# Build and mutate
warp-pep mutate -S ACDEFGH -m A1G -o mutated.pdb

# Multiple mutations
warp-pep mutate -i peptide.pdb -m A1G,C2S,D3E,F4Y -o multi_mutant.pdb

Integration with warp-md

import warp_md as wp
from warp_md.traj_py import pep_build

# Build peptide
pep_build(sequence="ACDEFGH", output="peptide.pdb")

# Load into warp-md system
sys = wp.System("peptide.pdb")

# Add to simulation
integrator = sys.integrator(
    wp.INTEGRATOR_LANGEVIN,
    timestep=0.002,
    temperature=300.0
)

sys.simulate(integrator, steps=1000)

Core API

Analysis Plans

Utilities

Peptide Builder

Quick Start

CLI Usage

Functions

pep_build

pep_mutate

Advanced Usage

JSON Specification

Secondary Structure Presets

Common Amino Acids

Error Handling

CLI Reference

Build Command

Mutate Command

Integration with warp-md

See Also

Build docs developers (and LLMs) love

Core API

Analysis Plans

Utilities

​Quick Start

​CLI Usage

​Functions

​pep_build

​pep_mutate

​Advanced Usage

​JSON Specification

​Secondary Structure Presets

​Common Amino Acids

​Error Handling

​CLI Reference

​Build Command

​Mutate Command

​Integration with warp-md

​See Also

Build docs developers (and LLMs) love

Quick Start

CLI Usage

Functions

pep_build

pep_mutate

Advanced Usage

JSON Specification

Secondary Structure Presets

Common Amino Acids

Error Handling

CLI Reference

Build Command

Mutate Command

Integration with warp-md

See Also