feat: Add covalent polymer-enzyme attachment support

[joelaforet]

Summary

Add support for covalently attaching polymers directly to enzyme residues, enabling simulation of polymer-conjugated enzymes (e.g., polymer brushes bound to lysine residues via NHS ester chemistry).

Motivation

Current PolyzyMD workflow only places free polymers around the enzyme-substrate complex. For studying enzyme-polymer conjugates (a key research focus), we need to:

• Define attachment points on enzyme surface
• Generate polymers with reactive terminal groups
• Form covalent bonds between polymers and specific residues

Proposed Config Schema

polymer_attachments:
  enabled: true
  count: 3                          # Number of polymers to attach
  polymer:
    type_prefix: "pSBMA"
    monomers:
      - label: "A"
        probability: 1.0
    length: 5
    sdf_directory: "polymers/"
  
  linker:
    chemistry: "nhs_ester"          # NHS ester → Lys ε-amino
  
  attachment_sites:
    residue_types:
      - residue: "LYS"
        probability: 1.0
    exclude_residues: []            # Optionally exclude specific residue IDs
    surface_only: true              # Only consider surface-exposed residues
    min_distance: 15.0              # Min distance between sites (Å)

Technical Approach

Option A: OpenFF Pablo Integration (Recommended for long-term)

• Use Pablo's ResidueDefinition with crosslink attribute
• Leverage existing infrastructure for leaving atoms and bond formation
• Well-tested chemistry handling
• Pros: Robust, maintained by OpenFF team, handles edge cases
• Cons: Additional dependency, learning curve, may need to adapt to our use case

Option B: Manual Bond Formation

• Directly modify OpenFF Topology to add bonds and remove atoms
• Simpler initial implementation
• Pros: Full control, no new dependencies
• Cons: Must handle all chemistry edge cases ourselves, potential for bugs

Option C: Hybrid Approach (Recommended for MVP)

• Use Pablo's ResidueDefinition classes for chemistry specification
• Implement our own bond formation logic initially
• Migrate to full Pablo integration later
• Pros: Get working feature faster, can refine based on real usage

Implementation Phases

Phase 1: Config & Schema

• Add PolymerAttachmentConfig to schema.py
• Create LinkerConfig for chemistry types
• Update config_template.yaml
• Validate schema with test configs

Phase 2: Linker Chemistry Library

• Create src/polyzymd/data/linker_library.py
• Define NHS ester chemistry (SMILES, leaving atoms, bond specs)
• Document reaction mechanism

Phase 3: Attachment Site Selection

• Implement surface residue detection (SASA-based)
• Filter by residue type
• Probabilistic sampling with distance constraints
• Return selected residue IDs + atom names

Phase 4: Polymer Terminal Modification

• Add linker group to polymer terminal
• Mark appropriate leaving atoms
• Generate/load modified polymer structures

Phase 5: Bond Formation

• Create AttachmentBuilder class
• Implement topology modification (add bond, remove leaving atoms)
• Integrate into SystemBuilder pipeline
• Handle force field parameterization

Phase 6: Testing & Docs

• Unit tests for each component
• Integration test with real system
• Tutorial documentation
• Example config files

Chemistry Reference: NHS Ester Conjugation

Polymer-COOH + NHS → Polymer-CO-NHS (active ester)
                           ↓
                     + Lys-NH2
                           ↓
               Polymer-CO-NH-Lys + NHS (leaving group)

Key atoms:

• Lysine NZ (ε-amino nitrogen) forms bond to polymer carbonyl C
• NHS succinimide is leaving group on polymer side
• One H removed from Lys NZ

Starting Point Options

When picking this up, consider these approaches:

1. Config schema first: Define data structures, create test configs, validate ergonomics before implementation
2. Chemistry prototype: Jupyter notebook exploring NHS ester chemistry with RDKit/OpenFF, test bond formation manually
3. Architecture doc: Detailed pseudocode and class diagrams before any code
4. Pablo deep-dive: More thorough exploration of Pablo's capabilities with our specific use case
5. Literature review: Survey how other MD tools handle covalent modifications (CHARMM-GUI, AmberTools, etc.)

Related Work

• OpenFF Pablo - Protein preparation with custom residue support
• Pablo maleimide_conect_based.ipynb example shows cysteine-conjugated fluorophore (similar concept)
• Pablo's ResidueDefinition.crosslink attribute designed exactly for this type of non-sequential bonding

Future Extensions

• Maleimide chemistry (cysteine conjugation)
• Click chemistry (azide-alkyne)
• Multiple attachment chemistries per system
• Branched polymer attachment
• Explicit residue ID specification (in addition to probabilistic)