synth-pdb 1.19.2
Generate realistic PDB files with mixed secondary structures for bioinformatics testing, education, and tool development
License: MIT
Requires Python: >=3.8
Keywords: pdb, protein, structure, bioinformatics, testing, peptide-generation, molecular-modeling, ramachandran, secondary-structure, structural-biology, protein-folding, educational-tool

# synth-pdb

A command-line tool to generate Protein Data Bank (PDB) files with full atomic representation for testing, benchmarking and educational purposes.

[![PyPI version](https://img.shields.io/badge/pypi-v1.19.2-blue)](https://pypi.org/project/synth-pdb/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/elkins/synth-pdb/actions/workflows/test.yml/badge.svg)](https://github.com/elkins/synth-pdb/actions/workflows/test.yml)
[![Documentation](https://img.shields.io/badge/docs-live-brightgreen)](https://elkins.github.io/synth-pdb/)

📚 **[Read the full documentation](https://elkins.github.io/synth-pdb/)** | [Getting Started](https://elkins.github.io/synth-pdb/getting-started/quickstart/) | [API Reference](https://elkins.github.io/synth-pdb/api/overview/) | [Tutorials](https://elkins.github.io/synth-pdb/tutorials/gfp_molecular_forge/)

## 📚 Interactive Tutorials

### Prerequisites
- **Python 3.8+** and basic Python knowledge
- **Google Colab** account (free) or local Jupyter environment
- Specific tutorials may require domain knowledge (noted in difficulty levels)

### Tutorial Catalog

| Tutorial | Difficulty | Time | Action |
| :--- | :---: | :---: | :--- |
| **🤖 AI Protein Data Factory** | ⭐ Beginner | 15 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/ml_handover_demo.ipynb) |
| **🏭 Bulk Dataset Factory** | ⭐ Beginner | 15 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/dataset_factory.ipynb) |
| **🔗 Framework Handover** | ⭐ Beginner | 10 min | [View JAX/PyTorch/MLX Examples](https://github.com/elkins/synth-pdb/tree/master/examples/ml_loading) |
| **⭕ Macrocycle Design Lab** | ⭐⭐ Intermediate | 20 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/macrocycle_lab.ipynb) |
| **💊 Bio-Active Hormone Lab** | ⭐⭐ Intermediate | 20 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/hormone_lab.ipynb) |
| **🔍 Protein Quality Assessment** | ⭐⭐ Intermediate | 25 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/protein_quality_assessment.ipynb) |
| **🔬 The Virtual NMR Spectrometer** | ⭐⭐ Intermediate | 25 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/virtual_nmr_spectrometer.ipynb) |
| **📡 Neural NMR Pipeline** | ⭐⭐ Intermediate | 25 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/neural_nmr_pipeline.ipynb) |
| **🔗 The NeRF Geometry Lab** | ⭐⭐ Intermediate | 25 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/nerf_geometry_lab.ipynb) |
| **🧪 The GFP Molecular Forge** | ⭐⭐ Intermediate | 30 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/gfp_molecular_forge.ipynb) |
| **🧬 PLM Embeddings (ESM-2)** | ⭐⭐ Intermediate | 30 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/docs/tutorials/plm_embeddings.ipynb) |
| **📐 6D Orientogram Lab** | ⭐⭐⭐ Advanced | 30 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/orientogram_lab.ipynb) |
| **🎯 The Hard Decoy Challenge** | ⭐⭐⭐ Advanced | 35 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/hard_decoy_challenge.ipynb) |
| **💊 Drug Discovery Pipeline** | ⭐⭐⭐ Advanced | 35 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/drug_discovery_pipeline.ipynb) |
| **🌌 AI Latent Space Explorer** | ⭐⭐⭐ Advanced | 35 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/latent_space_explorer.ipynb) |
| **🏔️ The Live Folding Landscape** | ⭐⭐⭐ Advanced | 40 min | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/interactive_tutorials/folding_landscape.ipynb) |

### 🎓 Learning Paths

Choose a path based on your background and goals:

#### 🤖 **For ML Engineers**
*Build AI models with synthetic protein data*

1. **🤖 AI Protein Data Factory** (15 min) - Learn zero-copy data handover to PyTorch/JAX
2. **🏭 Bulk Dataset Factory** (15 min) - Generate thousands of training samples
3. **🔗 Framework Handover** (10 min) - Integrate with your ML framework
4. **🎯 Hard Decoy Challenge** (35 min) - Create negative samples for robust training
5. **🧬 PLM Embeddings (ESM-2)** (30 min) - Add evolutionary context as per-residue node features
6. **📐 6D Orientogram Lab** (30 min) - Work with rotation-invariant representations

#### 🔬 **For Biophysicists**
*Understand structure, dynamics, and spectroscopy*

1. **🔗 NeRF Geometry Lab** (25 min) - Learn internal coordinate systems
2. **🔬 Virtual NMR Spectrometer** (25 min) - Predict relaxation rates and chemical shifts
3. **🔍 Protein Quality Assessment** (25 min) - Validate structure quality and geometry
4. **🧪 GFP Molecular Forge** (30 min) - Explore chromophore chemistry
5. **🏔️ Live Folding Landscape** (40 min) - Visualize energy surfaces and Ramachandran space
6. **📡 Neural NMR Pipeline** (25 min) - Connect structure to NMR observables
7. **🧬 PLM Embeddings (ESM-2)** (30 min) - See how sequence encodes secondary structure context

#### 💊 **For Drug Designers**
*Design and optimize therapeutic peptides*

1. **💊 Drug Discovery Pipeline** (35 min) - End-to-end peptide library to lead selection
2. **⭕ Macrocycle Design Lab** (20 min) - Create head-to-tail cyclic peptides
3. **💊 Bio-Active Hormone Lab** (20 min) - Model bioactive peptide hormones
4. **🎯 Hard Decoy Challenge** (35 min) - Generate decoys for docking validation
5. **🌌 AI Latent Space Explorer** (35 min) - Navigate chemical space with ML
6. **🔬 Virtual NMR Spectrometer** (25 min) - Predict experimental observables


## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [Command-Line Arguments](#command-line-arguments)
  - [Examples](#examples)
  - [ML Integration (AI Research)](#ml-integration-ai-research)
- [Validation & Refinement](#validation--refinement)
- [Output PDB Format](#output-pdb-format)
- [Scientific Context](#scientific-context)
- [Limitations](#limitations)
- [Development](#development)
- [Glossary of Scientific Terms & Acronyms](#glossary-of-scientific-terms--acronyms)
- [License](#license)

## Features

✨ **Structure Generation**
- Full atomic representation with backbone and side-chain heavy atoms + hydrogens
- Customizable sequence (1-letter or 3-letter amino acid codes)
- Random sequence generation with uniform or biologically plausible frequencies
- **Conformational diversity**: Generate alpha helices, beta sheets, extended chains, or random conformations
- **Backbone-Dependent Rotamers**: Side-chain conformations are selected based on local secondary structure (Helix/Sheet) to minimize steric clashes (Dunbrack library).
- **Bulk Dataset Generation**: Generate thousands of (Structure, Sequence, Contact Map) triplets for AI training via `--mode dataset`.
- **Metal Ion Coordination**: Automatic detection and structural injection of cofactors like **Zinc (Zn2+)** with physics-aware harmonic constraints. ✅
- **Disulfide Bonds**: Automatic detection and annotation of **SSBOND** records for Cysteine pairs. ✅
- **Salt Bridge Stabilization**: Automatic detection of ionic interactions with harmonic restraints in OpenMM. ✅
- **Advanced Chemical Shifts**: SPARTA-lite prediction + **Ring Current Effects** (shielding/deshielding from aromatic rings). ✅
- **Relaxation Rates**: Lipari-Szabo Model-Free formalism with **SASA-modulated Order Parameters** ($S^2$), allowing "buried" residues to be more rigid than "exposed" ones. ✅
- **Biophysical Realism**: 
    - **Backbone-Dependent Rotamers**: Chi angles depend on secondary structure.
    - **Pre-Proline Bias**: Residues preceding Proline automatically adopt restricted conformations (extended/beta). ✅
    - **Cis-Proline Isomerization**: X-Pro bonds can adopt cis conformations (~5% probability). ✅
    - **Post-Translational Modifications**: Support for Phosphorylation (SEP, TPO, PTR) with valid physics parameters. ✅
- **Cyclic Peptides (Macrocycles)**: Support for **Head-to-Tail cyclization**. Closes the peptide bond between N- and C-termini using physics-based minimization. ✅
- **NMR Functionality**: As of v1.16.0, all NMR-related features (chemical shifts, relaxation, NOEs, J-couplings) have been refactored into the separate [`synth-nmr`](https://pypi.org/project/synth-nmr/) Python package. This allows for independent use and development of NMR tools.

🚀 **High Performance Physics**
- **Hardware Acceleration**: Automatically detects and uses **GPU acceleration** (CUDA, OpenCL/Metal) if available.
    - **Apple Silicon Support**: Fully supported on M1/M2/M3/M4 chips via OpenCL driver (5x speedup over CPU).
- **Vectorized Geometry**: Construction kernels are optimized with NumPy vectorization for fast validation.
- **Tunable Minimization**: Control `tolerance` and `max_iterations` to balance speed/quality for bulk datasets.

🔬 **Validation Suite**
- Bond length validation
- Bond angle validation
- Ramachandran angle checking (phi/psi dihedral angles)
- Side-Chain Rotamer validation (Chi1/Chi2 angles checked against backbone-dependent library)
- Steric clash detection (minimum distance + van der Waals overlap)
- Peptide plane planarity (omega angle)
- Sequence improbability detection (charge clusters, hydrophobic stretches, etc.)

⚙️ **Quality Control**
- `--best-of-N`: Generate multiple structures and select the one with fewest violations
- `--guarantee-valid`: Iteratively generate until a violation-free structure is found
- `--refine-clashes`: Iteratively adjust atoms to reduce steric clashes
- `--quality-filter`: Use Random Forest-based Structure Quality Filter to validate structure geometry
- `--quality-score-cutoff`: Set minimum confidence score for quality filter (0.0-1.0)

📝 **Reproducibility**
- Command-line parameters stored in PDB header (REMARK 3 records)
- Timestamps in generated filenames and headers

## 📚 Understanding PDB Output - Educational Guide

### Biophysical Realism

**synth-pdb** generates structures with realistic properties that mimic real experimental data:

#### 🌡️ B-factors (Temperature Factors)
**What**: Measure atomic mobility/flexibility (columns 61-66)  
**Formula**: B = 8π²⟨u²⟩ (mean square displacement)  
**Range**: 5-60 Ų  
**Pattern**: Backbone (15-25) < Side chains (20-35) < Termini (30-50)

#### 📊 Occupancy Values  
**What**: Fraction of molecules with atom at position (columns 55-60)  
**Range**: 0.85-1.00  
**Correlation**: High B-factor ↔ Low occupancy  
**Pattern**: Backbone (0.95-1.00) > Side chains (0.85-0.95)

#### 🔄 Backbone-Dependent Rotamer Libraries
**Definition**: A **Rotamer** (Rotational Isomer) is a low-energy, stable conformation of an amino acid side chain defined by specific values of its side-chain dihedral angles ($\chi_1, \chi_2...$). Side chains are not flopping randomly; they snap into these discrete "preset" shapes.

**The "Backbone-Dependent" Twist**:
The preferred shape of a side chain strongly depends on the shape of the backbone behind it (Alpha Helix vs Beta Sheet).
*   **Helix ($\alpha$)**: Side chains pack tightly. Bulky rotamers (like 'trans' chi1 for Val/Ile) often crash into the backbone (steric clash).
*   **Sheet ($\beta$)**: The backbone is extended, creating more room for different rotamers.

**Implementation**: Synth-PDB uses a simplified version of the **Dunbrack Library**. It intelligently checks the backbone geometry ($\phi, \psi$) before picking a side chain shape, ensuring biophysical realism.

#### ⭕ Macrocyclization (Cyclic Peptides)
**What**: Creating a covalent bond between the N-terminal Amine and the C-terminal Carboxyl group to form a closed ring.
**Biophysical Magnitude**:
*   **Conformational Entropy**: Rigidifies the peptide. A linear peptide is a "floppy" string; a cyclic peptide is a "locked" ring. This reduces the entropy loss upon binding to a receptor, significantly increasing affinity.
*   **Metabolic Stability**: Most degradation in the blood happens via *exopeptidases* (enzymes that clip ends). With no ends to clip, macrocycles are much more stable and long-lived in biological systems.
*   **Pre-organization**: Cyclic peptides are "pre-organized" for their biological function, making them excellent drug scaffolds.
**Coverage**: Supports **All 20 Standard Amino Acids** (including charged/polar residues).

#### 🧬 D-Amino Acids (Inverted Stereochemistry)
**What**: Mirror-images of standard L-amino acids.
**Biophysical Magnitude**:
*   **Protease Resistance**: Most enzymes that degrade proteins (proteases) are "evolutionarily locked" to only recognize L-amino acids. By replacing a single L-amino acid with a D-amino acid, a peptide can become hundreds of times more stable in human blood.
*   **Bacterial Cell Walls**: Bacteria uniquely use D-amino acids (like D-Ala and D-Glu) in their cross-linked peptidoglycan cell walls. This is why many antibiotics (like Penicillin) target these non-L structures.
*   **Non-Natural Foldamers**: D-amino acids allow for the creation of "mirror-image" helices and unique turns (e.g., Beta-turns involving D-Pro) that are impossible with standard biology.
**Implementation**: **synth-pdb** mirrors sidechain coordinates across the N-CA-C backbone plane and uses standard PDB 3-letter codes (e.g., `DAL`, `DPH`).

#### 🧬 Secondary Structures
**What**: Regular backbone patterns (helices, sheets)  
**Control**: Per-region via `--structure` parameter  
**Example**: `--structure "1-10:alpha,11-15:random,16-25:alpha"`

#### 🧪 Residue-Specific Ramachandran Validation (MolProbity-Style)
> [!TIP]
> **Realism Equals Efficiency**: By using valid backbone angles (Pre-Proline bias) and correct side-chain rotamers, `synth-pdb` structures start much closer to a physical energy minimum. Validation experiments show this reduces Energy Minimization time by **>60%** due to fewer initial steric clashes.

**Status**: Fully Implemented ✅
**What**: Realistic backbone geometry validation based on amino acid type using MolProbity/Top8000 data.
- **Glycine (GLY)**: Correctly allowed in left-handed alpha region (phi > 0).
- **Proline (PRO)**: Checks against restricted phi angles.
- **General**: All other residues are checked against standard Favored/Allowed polygons.
- **Precision**: Uses point-in-polygon algorithms for accurate classification (Favored, Allowed, Outlier).

#### 📐 NeRF Geometry (The Construction Engine)
**What**: Natural Extension Reference Frame algorithm  
**Term**: Building 3D structures from "Internal Coordinates" (Z-Matrix)  
**Mechanism**: Places each atom (N, CA, C, O) relative to the local coordinate system of the three previous atoms.  
**Educational Value**: Teaches how math converts 1D sequences + 2D angles into 3D shapes.

#### ⛓️ Metal Coordination (Cofactors)
**What**: Structural integration of inorganic ions (e.g. Zinc).
**Motifs**: Detected via ligand clustering (Cys/His sites).
**Physics**: Applied via Harmonic Constraints in Energy Minimization.
**Importance**: Models structural stability of Zinc Fingers and enzymatic sites.

#### 🧲 Salt Bridge Stabilization
**What**: Automatic detection of ionic interactions (e.g., LYS+ and ASP-).
**Criteria**: Distance-based detection between charged side-chain atoms (cutoff 5.0 Å).
**Physics**: Stabilized via harmonic restraints during energy minimization.
**Importance**: Maintains tertiary structure integrity in synthetic protein models.

#### 🔗 Disulfide Bonds (SSBOND)
**What**: Covalent bonds between Cysteine residues
**Detection**: Automatic detection of close CYS-CYS pairs (SG-SG distance 2.0-2.2 Å)
**Output**: SSBOND records added to PDB header
**Importance**: Annotates stabilizing post-translational modifications

#### ⭕ Cyclic Peptides (Macrocyclization)
**What**: Binds the N-terminal Nitrogen to the C-terminal Carbon to form a closed ring.
**Mechanism**: Uses OpenMM's physics engine to regularize the covalent bond and minimize ring strain.
**Bio-Context**: Many potent drugs (e.g., Cyclosporine) and toxins are cyclic peptides. Cyclization increases metabolic stability and reduces conformational entropy, improving binding affinity.

### Educational Philosophy & Integrity

`synth-pdb` is built on the principle of **"Code as Textbook"**. 

*   **Pedagogical Comments**: Key source files (`generator.py`, `test_bfactor.py`) contain detailed block comments explaining the *why* alongside the *how* (e.g., explaining Lipari-Szabo stiffness vs. B-factor flexibility).
*   **Integrity Safeguards**: We include a specialized test suite (`tests/test_docs_integrity.py`) that strictly enforces the presence of these educational notes. This ensures that future refactoring never accidentally deletes the scientific context.
*   **Visual Learning**: We believe that seeing is understanding. The integrated `--visualize` tool connects biophysical theory (minimized energy, restrained dynamics) to immediate visual feedback, helping visual learners grasp complex 3D relationships.
*   **Universal Patterns**: The generator is tuned to reproduce universal biophysical phenomena (like terminal fraying and backbone rigidity) rather than just random noise, making it a valid tool for teaching structural biology concepts.

## Installation

### From PyPI (Recommended)

Install the latest stable release from PyPI:

```bash
pip install synth-pdb
```

This installs the `synth-pdb` package and makes the `synth-pdb` command available system-wide.

### From Source (For Development)

Install directly from the project directory:

```bash
git clone https://github.com/elkins/synth-pdb.git
cd synth-pdb
pip install .
```

### Requirements
- Python 3.8+
- NumPy
- Biotite (for residue templates and structure manipulation)

Dependencies are automatically installed with pip.

## Quick Start

Generate a simple 10-residue peptide:
```bash
synth-pdb --length 10
```

Generate and validate a specific sequence:
```bash
synth-pdb --sequence "ACDEFGHIKLMNPQRSTVWY" --validate --output my_peptide.pdb
```

Generate with mixed secondary structures and visualize:
```bash
synth-pdb --structure "1-10:alpha,11-20:beta" --visualize
```

Generate the best of 10 attempts with clash refinement:
```bash
synth-pdb --length 20 --best-of-N 10 --refine-clashes 5 --output refined_peptide.pdb
```

## 🤖 Feature Spotlight: AI Model Support & Hard Decoys

Generating "good" structures is only half the battle. To train robust AI models (like AlphaFold-3 or RosettaFold), researchers need **High-Quality Negative Samples**—structures that look physically plausible but are biologically or topologically incorrect.

**Synth-PDB** provides three powerful mechanisms for generating these "Hard Decoys":

### 1. Sequence Threading (Fold Mismatch)
Force a specific sequence onto the backbone "fold" of a completely different sequence. This creates a realistic-looking structure where the side-chain packing is fundamentally incompatible with the backbone.
```bash
# Thread Poly-Ala sequence onto a backbone generated for Poly-Pro
synth-pdb --mode decoys --sequence AAAAA --template-sequence PPPPP --hard
```

### 2. Torsion Angle Drift (Conformational Noise)
Add controlled, random noise to ideal Ramachandran angles. This creates "near-native" decoys—structures that are *almost* correct but have subtle, realistic errors.
```bash
# Add 5 degrees of maximum drift to all phi/psi angles
synth-pdb --mode decoys --drift 5.0
```

### 3. Label Shuffling (Sequence Mismatch)
Generate a perfectly valid structure for a sequence, then randomly shuffle the identity of the residues in the final PDB. This tests if an AI model can detect that a residue (e.g., Trp) is in an environment meant for another (e.g., Gly).
```bash
synth-pdb --mode decoys --sequence ACDEF --hard --shuffle-sequence
```

---

## 🌟 Feature Spotlight: "Spectroscopically Realistic" Dynamics

Most synthetic PDB generators create static bricks. They might create reasonable geometry, but the "B-factor" column (Column 11) is often just zero or random noise.

**Synth-PDB is different.** It simulates the **physics of protein motion** to generate a unified model of structure AND dynamics.

### The "Structure-Dynamics Link"
We implement the **Lipari-Szabo Model-Free formalism** (Nobel-adjacent physics) directly into the generator:
1.  **Structure Awareness**: The engine analyzes the generated geometry (`alpha-helix` vs `random-coil`).
2.  **Order Parameter ($S^2$) Prediction**: It assigns specific rigidity values:
    *   **Helices**: $S^2 \approx 0.85$ (Rigid H-bond network)
    *   **Loops**: $S^2 \approx 0.65$ (Flexible nanosecond motions)
    *   **Termini**: $S^2 \approx 0.45$ (Disordered fraying)
3.  **Unified Output**:
    *   **PDB B-Factors**: Calculated via $B \propto (1 - S^2)$. When you visualize the PDB in PyMOL, flexible regions *visually* appear thicker/redder, matching real crystal data distributions.
    *   **NMR Relaxation**: $R_1, R_2, NOE$ rates are calculated from the *same* parameters.

**Why this matters**:
> "The correlation between NMR order parameters ($S^2$) and crystallographic B-factors is a bridge between solution-state and solid-state dynamics." — *Fenwick et al., PNAS (2014)*

This feature allows you to test **bioinformatics pipelines** that rely on correlation between sequence, structure, and experimental observables, without needing expensive Molecular Dynamics (MD) simulations.

### 4. Relax (Simulate Dynamics)
Generate relaxation rates ($R_1, R_2, NOE$) with **realistic internal dynamics**:
```bash
python main.py relax --input output/my_peptide.pdb --output output/relaxation_data.nef --field 600 --tm 10.0
```
This module now implements the **Lipari-Szabo Model-Free** formalism with structure-based Order Parameter ($S^2$) prediction:
*   **Helices/Sheets**: $S^2 \approx 0.85$ (Rigid, high $R_1/R_2$)
*   **Loops/Turns**: $S^2 \approx 0.65$ (Flexible, lower $R_1/R_2$)
*   **Termini**: $S^2 \approx 0.45$ (Highly disordered)

This creates realistic "relaxation gradients" along the sequence, perfect for testing dynamics software.

## 🚀 Quick Visual Demo

Want to see the **Physics + Visualization** capabilities in action?

Run this command to generate a **Leucine Zipper** (classic alpha helix), **minimize** its energy using OpenMM, and immediately **visualize** it in your browser:

```bash
synth-pdb --sequence "LKELEKELEKELEKELEKELEKEL" --conformation alpha --minimize --visualize
```

This effectively demonstrates:
1.  **Generation**: Creating the alpha-helical backbone.
2.  **Minimization**: "Relaxing" the structure (geometry regularization).
3.  **Visualization**: Launching the interactive 3D viewer.

## Usage

### Command-Line Arguments

#### **Structure Definition**

- `--length <LENGTH>`: Number of residues in the peptide chain
  - Type: Integer
  - Default: `10`
  - Example: `--length 50`

- `--sequence <SEQUENCE>`: Specify an exact amino acid sequence
  - Formats: 
    - 1-letter codes: `"ACDEFG"`
    - 3-letter codes: `"ALA-CYS-ASP-GLU-PHE-GLY"`
  - Overrides `--length`
  - Example: `--sequence "MVHLTPEEK"`

- `--plausible-frequencies`: Use biologically realistic amino acid frequencies for random generation
  - Based on natural protein composition
  - Ignored if `--sequence` is provided

- `--conformation \u003cCONFORMATION\u003e`: Secondary structure conformation to generate
  - Options: `alpha`, `beta`, `ppii`, `extended`, `random`
  - Default: `alpha` (alpha helix)
  - Choices:
    - `alpha`: Alpha helix (φ=-57°, ψ=-47°)
    - `beta`: Beta sheet (φ=-135°, ψ=135°)
    - `ppii`: Polyproline II helix (φ=-75°, ψ=145°)
    - `extended`: Extended/stretched conformation (φ=-120°, ψ=120°)
    - `random`: Random sampling from allowed Ramachandran regions
  - Example: `--conformation beta`

#### 🤖 AI & Machine Learning: Bulk Dataset Generation

`synth-pdb` serves as valid data generator for training Deep Learning models (GNNs, Transformers, Diffusion Models). It can generate massive, diverse, and labeled datasets.

**Command:**
```bash
synth-pdb --mode dataset --dataset-format npz --num-samples 1000 --output my_training_data
```

**Features:**
*   **Formats**: 
    *   `npz`: (Recommended) Compressed NumPy archives. Contains `coords` (L,5,3), `sequence` (One-hot), and `contact_map` (LxL). Ideal for PyTorch/TensorFlow dataloaders.
    *   `pdb`: Writes individual PDB files and CASP contact maps (slower, for legacy tools).
*   **Multiprocessing**: Automatically uses all available CPU cores.
*   **Manifest**: Generates a `dataset_manifest.csv` tracking all samples and their metadata (split, length, conformation).

**Output Structure (`--dataset-format npz`)**:
```
my_training_data/
├── dataset_manifest.csv
├── train/
│   ├── synth_000001.npz
│   ├── synth_000002.npz
│   ...
└── test/
    ├── synth_000801.npz
    ...
```

### 🔍 Visualization & Analysis
#### **Validation & Quality Control**

- `--validate`: Run validation checks on the generated structure
  - Checks: bond lengths, bond angles, Ramachandran, steric clashes, peptide planes, sequence improbabilities
  - Reports violations to console

- `--guarantee-valid`: Generate structures until one with zero violations is found
  - Implies `--validate`
  - Use with `--max-attempts` to limit iterations
  - Example: `--guarantee-valid --max-attempts 100`

- `--max-attempts <N>`: Maximum generation attempts for `--guarantee-valid`
  - Default: `100`

- `--best-of-N <N>`: Generate N structures and select the one with fewest violations
  - Implies `--validate`
  - Overrides `--guarantee-valid`
  - Example: `--best-of-N 20`

- `--refine-clashes <ITERATIONS>`: Iteratively adjust atoms to reduce steric clashes
  - Applies after structure selection
  - Iterates until improvements stop or max iterations reached
  - Example: `--refine-clashes 10`

#### **Structure Quality Filter (Random Forest)**

> [!NOTE]
> Despite the flag name history, this feature uses a **classical Random Forest classifier** (scikit-learn), not a neural network or generative AI. It scores structures on geometric quality metrics derived from Ramachandran angles, steric clashes, bond lengths, and radius of gyration.

- `--quality-filter`: Enable the **Structure Quality Filter** to screen generated structures.
  - Using a Random Forest classifier trained on thousands of samples, this filter automatically rejects "low quality" structures (clashing, distorted geometry).
  - It considers Ramachandran angles, steric clashes, bond lengths, and radius of gyration.
  - Useful for filtering out failed minimization attempts in bulk generation.

- `--quality-score-cutoff <FLOAT>`: Minimum probability score (0.0-1.0) for a structure to be considered "Good".
  - Higher values = stricter filtering (fewer false positives, more false negatives).
  - Default: `0.5`
  - Example: `--quality-score-cutoff 0.8` (Only keep highly confident good structures)
  - Scores below `0.5` are typically rejected as "Bad".

#### **Physics & Advanced Refinement **

- `--minimize`: Run physics-based energy minimization (OpenMM).
  - Uses implicit solvent (OBC2) and AMBER forcefield.
  - Highly recommended for "realistic" geometry.
  - Example: `--minimize`

- `--optimize`: Run Monte Carlo side-chain optimization.
  - Reduces steric clashes by rotating side chains.
  - Example: `--optimize`

- `--forcefield <NAME>`: Specify OpenMM forcefield.
  - Default: `amber14-all.xml`
  - Example: `--forcefield amber14-all.xml`
  - Default: `amber14-all.xml`

- `--minimization-k <FLOAT>`: Energy minimization tolerance (kJ/mole/nm).
  - Higher values = Faster but less precise.
  - Recommended for bulk generation: `100.0`
  - Default: `10.0` (High Precision)

- `--minimization-max-iter <INT>`: Max iterations for minimization.
  - `0` = Unlimited (Convergence based on tolerance)
  - Recommended for bulk generation: `1000`
  - Default: `0`

#### **Synthetic NMR Data**

> **📦 NMR Functionality Powered by [`synth-nmr`](https://github.com/elkins/synth-nmr)**  
> As of version 1.17.0, all NMR-related functionality (NOE calculation, relaxation rates, chemical shifts, J-couplings) is provided by the standalone [`synth-nmr`](https://pypi.org/project/synth-nmr/) package. This package can be used independently for NMR data generation in your own projects. The integration is fully backward compatible—all existing code continues to work without changes.


- `--gen-nef`: Generate synthetic NOE restraints in NEF format.
  - Scans structure for H-H pairs < cutoff.
  - Outputs `.nef` file.
  - Note: Requires hydrogens (use with `--minimize` or internal default).

- `--noe-cutoff <DIST>`: Cutoff distance for NOEs in Angstroms.
  - Default: `5.0`
  - Example: `--noe-cutoff 6.0`

- `--nef-output <FILE>`: Custom output filename for NEF.

#### **Synthetic Relaxation Data **

- `--gen-relax`: Generate synthetic NMR relaxation data ($R_1, R_2, \{^1H\}-^{15}N\ NOE$) in NEF format.
  - Calculates Model-Free parameters ($S^2 \approx 0.85$ for core, $0.5$ for flexible termini).
  - Outputs `_relax.nef` file.
  - **Physics Note**: $NOE$ values depend on tumbling time, not just internal flexibility.

- `--field <MHZ>`: Proton Larmor frequency in MHz.
  - Default: `600.0`
  - Calculates proper spectral density frequencies for this field.

- `--tumbling-time <NS>`: Global rotational correlation time ($\tau_m$) in nanoseconds.
  - Default: `10.0`
  - Controls the overall magnitude of relaxation rates. Larger proteins have larger $\tau_m$.

#### **Constraints Export **

- `--export-constraints <FILE>`: Export contact map constraints for modeling/folding.
  - Useful for checking agreement with AlphaFold/CASP predictions.
  - Outputs a file containing residue-residue contacts.
  - Example: `--export-constraints constraints.casp`

- `--constraint-format {casp,csv}`: Format for the exported constraints.
  - `casp`: Critical Assessment of Structure Prediction (RR) format.
  - `csv`: Comma-separated values (i, j, distance).
  - Default: `casp`

- `--constraint-cutoff <DIST>`: Distance cutoff for defining binary contacts (Angstroms).
  - Default: `8.0`

#### **Torsion Angle Export **

- `--export-torsion <FILE>`: Export backbone torsion angles (Phi, Psi, Omega) for every residue.
  - Useful for training ML models on backbone geometry.
  - Outputs a CSV or JSON file.
  - Example: `--export-torsion angles.csv`

- `--torsion-format {csv,json}`: Format for the exported data.
  - Default: `csv`

#### **Synthetic MSA (Evolution) **

- `--gen-msa`: Generate a Multiple Sequence Alignment (MSA) by simulating neutral drift.
  - Conserves hydrophobic core residues while mutating surface residues.
  - Outputs a FASTA file useful for testing co-evolution signals in AI models.

- `--msa-depth <N>`: Number of sequences to generate.
  - Default: `100`

- `--mutation-rate <RATE>`: Probability of mutation per position per sequence.
  - Default: `0.1` (10% divergence per sequence).

#### **Distogram Export (Spatial Relationships) **
- `--export-distogram <FILE>`: Export NxN Distance Matrix representing the protein geometry.
  - Rotation-invariant representation ideal for AI model training/validation.
  - Supports `json`, `csv`, or `npz` (NumPy) formats.
  - Example: `--export-distogram dist.json`

- `--distogram-format {json,csv,npz}`: Output format.
  - Default: `json`

#### **Biophysical Realism (Physics) **
- `--ph <VAL>`: Set pH for titration (default 7.4).
  - Automatically adjusts Histidine protonation (`HIS` $\rightarrow$ `HIP` if pH < 6.0).
  - Critical for realistic electrostatics and NMR chemical shifts.

- `--cap-termini`: Add terminal blocking groups.
  - N-terminus: Acetyl (`ACE`)
  - C-terminus: N-methylamide (`NME`)
  - Removes charged termini ($\text{NH}_3^+$/$\text{COO}^-$) for realistic peptide modeling.

- `--cyclic`: Generate a **Head-to-Tail cyclic peptide**.
  - Connects the N-terminus and C-terminus with a covalent peptide bond.
  - **Requirement**: Automatically implies `--minimize` to ensure proper closure.
  - **Incompatibility**: Disables `--cap-termini`.

- `--equilibrate`: Run Molecular Dynamics (MD) equilibration.
  - Simulates the protein at **300 Kelvin** (solution state).
  - Uses Langevin Dynamics to shake atoms out of local minima.
  - Generates a "thermalized" structure closer to NMR conditions.
  - Options: `--md-steps <INT>` (default 1000, $\approx$ 2 ps).

- `--metal-ions {auto,none}`: Control metal ion coordination.
  - `auto` (default): Scans for binding sites and injects ions.
  - `none`: Disables automatic coordination.
  
- `--phosphorylation-rate <FLOAT>`: Probability of phosphorylating S/T/Y residues.
  - Value between 0.0 and 1.0.
  - Converts SER->SEP, THR->TPO, TYR->PTR.
  - Mimics kinase activity for regulatory simulation.
  - Example: `--phosphorylation-rate 0.5`
  
- `--cis-proline-frequency <FLOAT>`: Probability of X-Pro peptide bond being Cis.
  - Default: `0.05` (5%)
  - Cis-Proline is critical for tight turns and folding.
  - Set to `0.0` for all-Trans, `1.0` for all-Cis.

#### **Bulk Dataset Generation (AI)**

- `--mode dataset`: Enable bulk generation mode.
- `--num-samples <N>`: Number of samples to generate (default 100).
- `--min-length <N>`, `--max-length <N>`: Range for random sequence lengths (default 10-50).
- `--train-ratio <FLOAT>`: Fraction of samples for the training set (default 0.8).
- `--output <DIR>`: Directory to save the dataset.






#### **Output Options**

- `--output <FILENAME>`: Custom output filename
  - If omitted, auto-generates: `random_linear_peptide_<length>_<timestamp>.pdb`
  - Example: `--output my_protein.pdb`

- `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}`: Logging verbosity
  - Default: `INFO`
  - Use `DEBUG` for detailed validation reports

- `--seed <INT>`: Random seed for reproducible generation
  - Default: `None` (Random)
  - Example: `--seed 42`
  - Guarantees identical output for the same command.

- `--help`: Show the help message and exit.

### Examples

#### Basic Generation

```bash
# Simple 25-residue peptide
synth-pdb --length 25

# Custom sequence with validation
synth-pdb --sequence "ELVIS" --validate --output elvis.pdb

# Use biologically realistic frequencies
synth-pdb --length 100 --plausible-frequencies

# Generate a random 20-residue alpha helix
synth_pdb --length 20 --conformation alpha --output random_helix.pdb

# Generate a high-quality, physically realistic structure (Recommended)
# Includes: Minimization, Terminal Capping, and Thermal Equilibration (MD)
synth_pdb --length 20 --minimize --cap-termini --equilibrate --output best_structure.pdb

# Generate beta sheet conformation
synth-pdb --length 20 --conformation beta --output beta_sheet.pdb

# Generate extended conformation
synth-pdb --length 15 --conformation extended

# Generate random conformation (mixed alpha/beta regions)
synth-pdb --length 30 --conformation random

# 🤖 Bulk dataset generation for AI training
synth-pdb --mode dataset --num-samples 500 --min-length 10 --max-length 40 --output ./my_dataset

# ⛓️ Generate a Zinc Finger with structural cofactors
synth-pdb --sequence "CPHCGKSFSQKSDLVKHQRT" --minimize --metal-ions auto --output zinc_finger.pdb
```

#### Quality Control

```bash
# Generate until valid (may take time!)
synth-pdb --length 15 --guarantee-valid --max-attempts 200 --output valid.pdb

# Best of 50 attempts
synth-pdb --length 20 --best-of-N 50 --output best_structure.pdb
```

## ML Integration (AI Research)

**synth-pdb** is designed to be a high-performance "Data Factory" for Training Protein AI models. It can generate thousands of unique, physically plausible protein structures in seconds—bypassing the bottleneck of parsing millions of PDB files from disk.

### 🤖 The Batch Walk (Vectorized Performance)
Using the `BatchedGenerator` module, the tool uses SIMD/Vectorized math (NeRF algorithm) to build peptide backbones in parallel.

### ⚡ Zero-Copy Handover
Transition from biological coordinates to Deep Learning tensors instantly. Our `BatchedPeptide` output is **C-Contiguous**, allowing tools like PyTorch and JAX to map the memory without copying data.

```python
from synth_pdb.batch_generator import BatchedGenerator
import torch

# Generate 1,000 structures in milliseconds
bg = BatchedGenerator("ALA-GLY-SER-TRP", n_batch=1000)
batch = bg.generate_batch()

# Instant PyTorch Handover (Shared RAM)
coords_tensor = torch.from_numpy(batch.coords).float()
```

### 🚀 Try it in the Cloud
- **AI Protein Data Factory:** [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-pdb/blob/master/examples/ml_integration/ml_handover_demo.ipynb)

### 🧩 Framework Specifics
For detailed examples of how to load generated data into your favorite framework without any performance overhead, see our specialized handover notebooks:
- [JAX Handover](file:///Users/georgeelkins/nmr/synth-pdb/examples/ml_loading/jax_handover.ipynb) - Zero-copy using `jax.numpy.asarray`.
- [PyTorch Handover](file:///Users/georgeelkins/nmr/synth-pdb/examples/ml_loading/pytorch_handover.ipynb) - Unified memory mapping with `torch.from_numpy`.
- [MLX Handover](file:///Users/georgeelkins/nmr/synth-pdb/examples/ml_loading/mlx_handover.ipynb) - Optimized for Apple Silicon (M-series CPUs/GPUs).

#### Quality Control (Continued)

```bash
# Refine steric clashes (5 iterations)
synth-pdb --length 30 --refine-clashes 5 --output refined.pdb

# Combined: best of 10 + refinement
synth-pdb --length 25 --best-of-N 10 --refine-clashes 3 --output optimized.pdb
```

#### Biologically-Inspired Examples

Generate structures that mimic real protein motifs for educational demonstrations:

```bash
# Collagen-like triple helix motif (polyproline II)
# Collagen is rich in proline and glycine with PPII conformation
synth-pdb --sequence "GPGPPGPPGPPGPPGPPGPP" --conformation ppii --output collagen_like.pdb

# Silk fibroin-like beta sheet
# Silk proteins contain repeating (GAGAGS) motifs forming beta sheets
synth-pdb --sequence "GAGAGSGAGAGS