API Overview

PolyzyMD is organized into the following modules:

Package Structure

polyzymd/
├── config/           # Configuration and YAML loading
│   ├── schema.py     # Pydantic models for all config sections
│   ├── comparison.py # ComparisonConfig, PlotSettings, condition models
│   └── loader.py     # YAML loading utilities
├── builders/         # System building components
│   ├── enzyme.py     # Enzyme/protein preparation
│   ├── substrate.py  # Substrate/ligand handling
│   ├── polymer.py    # Polymer chain generation
│   ├── solvent.py    # Solvation and ion addition
│   └── system_builder.py  # Main system assembly
├── simulation/       # MD simulation execution
│   ├── runner.py     # Simulation runner
│   ├── continuation.py    # Checkpoint continuation
│   ├── progress.py   # Segment progress tracking
│   └── signals.py    # SLURM signal handling
├── workflow/         # HPC workflow management
│   ├── slurm.py      # SLURM script generation
│   └── daisy_chain.py     # Job submission
├── core/             # Core utilities
│   ├── parameters.py # Simulation parameters
│   └── restraints.py # Restraint definitions
├── analyses/         # ★ Plugin system — unified analysis lifecycle
│   ├── base.py       # Public facade, contexts, result models
│   ├── discovery.py  # pkgutil-based auto-discovery
│   ├── orchestrator.py  # Framework engine
│   ├── stats.py      # Shared statistical utilities
│   ├── _framework/   # Private/internal lifecycle and artifact internals
│   ├── mda/          # Public MDAnalysis job and artifact layer
│   ├── shared/       # Reusable utilities (TrajectoryLoader, alignment, etc.)
│   ├── rmsd/         # RMSD plugin package
│   ├── rg/           # Rg plugin package
│   ├── rmsf/         # RMSF plugin package
│   ├── contacts/     # Contacts plugin package
│   ├── distances/    # Distance analysis plugin package
│   ├── secondary_structure/  # Secondary structure plugin package
│   └── ...           # Single-file or package plugins for each analysis type
└── cli/              # Command-line interface
    ├── compare.py    # `polyzymd compare` subcommands
    └── main.py       # Click CLI

The analyses/_framework/ package is private/internal implementation detail. Contributor plugins should import public lifecycle symbols from polyzymd.analyses.base and MDAnalysis job/artifact utilities from polyzymd.analyses.mda.

Key Classes

Configuration

• SimulationConfig - Main configuration container

• EnzymeConfig - Enzyme settings

• PolymerConfig - Polymer settings

• OutputConfig - Output directory settings

Building

• SystemBuilder - Main system builder

• EnzymeBuilder - Enzyme preparation

• PolymerBuilder - Polymer generation

Simulation

• SimulationRunner - Run simulations

• ContinuationManager - Continue from checkpoint

• SimulationProgress - Track segment completion across jobs

Workflow

• DaisyChainSubmitter - Self-resubmitting SLURM job submission

• SlurmConfig - SLURM configuration

Restraints

• RestraintDefinition - Restraint specification

• AtomSelection - Atom selection

• RestraintFactory - Create restraints from config

Analysis

• Analysis - Plugin base class for all analyses

• MDAAnalysisJob - Unit of trajectory-native MDAnalysis work

• FrameSelection - Frame selection and equilibration-window descriptor

• ReplicateArtifact - Validated output for one replicate

• ConditionArtifact - Aggregated output for one condition

• ComparisonArtifact - Canonical comparison output for cross-condition results

• ArtifactStore - Canonical artifact persistence and loading helper

• MetricValue - Scalar metric descriptor for default comparisons

• ParallelContactAnalyzer - Polymer-protein contacts

Comparison

• Analysis - Plugin base class for all analyses

• ComparisonResult - Universal comparison result model

• MetricValue - Scalar metric descriptor

• ReplicateContext - Context for per-replicate computation

• ComparisonContext - Context for cross-condition comparison

Quick Reference

Load Configuration

from polyzymd.config.schema import SimulationConfig

config = SimulationConfig.from_yaml("config.yaml")
print(config.enzyme.name)

Build System

from polyzymd.builders.system_builder import SystemBuilder

builder = SystemBuilder(config)
interchange = builder.build(replicate=1)

Run Simulation

from polyzymd.simulation.runner import SimulationRunner

runner = SimulationRunner(interchange, working_dir, config)
runner.run_equilibration()
runner.run_production(segment_index=0)

Submit to SLURM

from polyzymd.workflow.daisy_chain import submit_daisy_chain

results = submit_daisy_chain(
    config_path="config.yaml",
    slurm_preset="aa100",
    replicates="1-5",
)