Configuration Module

Configuration schema for PolyzyMD simulations.

This module defines Pydantic models for all configuration sections, providing validation, type safety, and YAML/JSON serialization support.

class polyzymd.config.schema.ChargeMethod(value)

Bases: str, Enum

Supported charge assignment methods for small molecules.

NAGL = 'nagl'

ESPALOMA = 'espaloma'

AM1BCC = 'am1bcc'

class polyzymd.config.schema.WaterModel(value)

Bases: str, Enum

Supported water models.

TIP3P = 'tip3p'

SPCE = 'spce'

TIP4P = 'tip4p'

TIP4PEW = 'tip4pew'

OPC = 'opc'

class polyzymd.config.schema.BoxShape(value)

Bases: str, Enum

Supported simulation box shapes.

CUBE = 'cube'

RHOMBIC_DODECAHEDRON = 'rhombic_dodecahedron'

TRUNCATED_OCTAHEDRON = 'truncated_octahedron'

class polyzymd.config.schema.Ensemble(value)

Bases: str, Enum

Thermodynamic ensemble types.

NVT = 'NVT'

NPT = 'NPT'

NVE = 'NVE'

class polyzymd.config.schema.ThermostatType(value)

Bases: str, Enum

Supported thermostat types.

LANGEVIN_MIDDLE = 'LangevinMiddle'

LANGEVIN = 'Langevin'

ANDERSEN = 'Andersen'

NOSE_HOOVER = 'NoseHoover'

class polyzymd.config.schema.BarostatType(value)

Bases: str, Enum

Supported barostat types.

MONTE_CARLO = 'MC'

MONTE_CARLO_ANISOTROPIC = 'MCA'

class polyzymd.config.schema.RestraintType(value)

Bases: str, Enum

Types of restraints that can be applied.

FLAT_BOTTOM = 'flat_bottom'

HARMONIC = 'harmonic'

UPPER_WALL = 'upper_wall'

LOWER_WALL = 'lower_wall'

class polyzymd.config.schema.EnzymeConfig(*, name, pdb_path, description=None)

Bases: BaseModel

Configuration for the enzyme/protein component.

Variables:

• name (str) – Identifier for the enzyme (e.g., “LipA”)

• pdb_path (Path) – Path to the PDB file containing the enzyme structure

• description (Optional[str]) – Optional description of the enzyme

name: str

pdb_path: Path

description: str | None

classmethod validate_pdb_path(v)

Validate that PDB path has correct extension.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.SubstrateConfig(*, name, sdf_path, conformer_index=0, charge_method=ChargeMethod.NAGL, residue_name='LIG')

Bases: BaseModel

Configuration for the docked substrate/ligand.

Variables:

• name (str) – Identifier for the substrate (e.g., “Resorufin-Butyrate”)

• sdf_path (Path) – Path to SDF file with docked conformers

• conformer_index (int) – Which conformer to use (0-indexed)

• charge_method (ChargeMethod) – Method for assigning partial charges

• residue_name (str) – 3-letter residue name for topology (default: “LIG”)

name: str

sdf_path: Path

conformer_index: int

charge_method: ChargeMethod

residue_name: str

classmethod validate_sdf_path(v)

Validate that SDF path has correct extension.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.PolymerPackingConfig(*, padding=2.0, tolerance=2.0, movebadrandom=False, box_vectors=None)

Bases: BaseModel

Settings for packing polymers around the solute.

Controls the box size and PACKMOL behavior when packing polymers around the protein-ligand complex.

Variables:

• padding (float) – Box padding around the solute in nanometers. Larger values give polymers more room and can speed up PACKMOL convergence.

• tolerance (float) – Minimum molecular spacing for PACKMOL in Angstrom.

• movebadrandom (bool) – When True, pass the movebadrandom keyword to PACKMOL. This places badly-packed molecules at random positions in the box rather than near well-packed neighbours, which improves convergence for dense or heterogeneous systems (many unique chain types). Has no effect when only a single chain type is present. Default is False (PACKMOL default behaviour is preserved).

• box_vectors (list[float] | None) – Optional explicit box dimensions [Lx, Ly, Lz] in nanometers. When set, overrides the auto-computed bounding box plus padding. The protein is centered at the midpoint of the box. Default is None (auto-compute from solute bounding box + padding).

Example

>>> PolymerPackingConfig(padding=2.5, movebadrandom=True)
>>> PolymerPackingConfig(box_vectors=[8.0, 10.0, 12.0])

padding: float

tolerance: float

movebadrandom: bool

box_vectors: list[float] | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.MonomerSpec(*, label, probability, name=None, smiles=None, residue_name=None)

Bases: BaseModel

Specification for a single monomer type in a co-polymer.

For dynamic polymer generation, provide the raw (unactivated) monomer SMILES. The system will run initiation reactions to create the active fragments.

Variables:

• label (str) – Single character label for this monomer (e.g., “A”, “B”)

• probability (float) – Probability of selecting this monomer (0-1)

• name (Optional[str]) – Optional full name (e.g., “SBMA”, “EGPMA”)

• smiles (Optional[str]) – Raw monomer SMILES string (required for dynamic generation)

• residue_name (Optional[str]) – 3-character PDB residue name (auto-generated if not provided)

label: str

probability: float

name: str | None

smiles: str | None

residue_name: str | None

auto_generate_residue_name()

Auto-generate residue name from monomer name if not provided.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.PolymerGenerationMode(value)

Bases: str, Enum

Mode for polymer generation.

CACHED = 'cached'

DYNAMIC = 'dynamic'

class polyzymd.config.schema.ReactionConfig(*, initiation, polymerization, termination)

Bases: BaseModel

Paths to reaction templates for ATRP polymer generation.

These .rxn files define the chemical transformations used to create polymer fragments from raw monomer SMILES. For ATRP, this includes: - Initiation: Activates the vinyl group (e.g., chlorination) - Polymerization: Creates chain-extending fragments - Termination: Restores the alkene for chain ends

You can use “default” as a special value to use the bundled ATRP methacrylate reaction templates that ship with PolyzyMD.

Example

reactions:

initiation: “default” polymerization: “default” termination: “default”

Variables:

• initiation (Path) – Path to the initiation reaction template (.rxn) or “default”

• polymerization (Path) – Path to the polymerization reaction template (.rxn) or “default”

• termination (Path) – Path to the termination reaction template (.rxn) or “default”

initiation: Path

polymerization: Path

termination: Path

classmethod resolve_default_paths(v, info)

Resolve ‘default’ to bundled ATRP reaction paths.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.PolymerConfig(*, enabled=True, generation_mode=PolymerGenerationMode.CACHED, type_prefix, monomers, length, count, sdf_directory=None, reactions=None, charger=ChargeMethod.NAGL, max_retries=10, cache_directory=PosixPath('.polymer_cache'), packing=<factory>, random_seed=None)

Bases: BaseModel

Configuration for polymer components.

Supports two generation modes: - “cached”: Load pre-built polymer SDF files from sdf_directory (legacy) - “dynamic”: Generate polymers on-the-fly using Polymerist from SMILES

For dynamic mode, you must provide: - SMILES for each monomer in monomers[].smiles - Reaction templates in the reactions field

Variables:

• enabled (bool) – Whether to include polymers in the system

• generation_mode (PolymerGenerationMode) – “cached” for pre-built SDFs, “dynamic” for on-the-fly generation

• type_prefix (str) – Prefix for polymer type in filenames (e.g., “SBMA-EGPMA”)

• monomers (List[MonomerSpec]) – List of monomer specifications with probabilities (and SMILES for dynamic)

• length (int) – Number of monomer units per polymer chain

• count (int) – Number of polymer chains to add

• sdf_directory (Optional[Path]) – Path to pre-built polymer SDF files (for cached mode)

• reactions (Optional[ReactionConfig]) – Reaction templates for ATRP (required for dynamic mode)

• charger (ChargeMethod) – Charge assignment method for generated polymers

• max_retries (int) – Maximum retries for polymer generation (ring-piercing failures)

• cache_directory (Path) – Directory for caching generated polymers and fragments

• packing (PolymerPackingConfig) – Settings for packing polymers around the solute

• random_seed (Optional[int]) – Random seed for polymer sequence generation (for reproducibility)

enabled: bool

generation_mode: PolymerGenerationMode

type_prefix: str

monomers: List[MonomerSpec]

length: int

count: int

sdf_directory: Path | None

reactions: ReactionConfig | None

charger: ChargeMethod

max_retries: int

cache_directory: Path

packing: PolymerPackingConfig

random_seed: int | None

validate_probabilities_sum_to_one()

Ensure monomer probabilities sum to 1.0.

validate_generation_mode_requirements()

Validate that required fields are present for the selected generation mode.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.CoSolventSpec(*, name, smiles=None, volume_fraction=None, concentration=None, density=None, residue_name=None)

Bases: BaseModel

Specification for a co-solvent component.

You must specify EITHER volume_fraction OR concentration, not both.

For co-solvents in the built-in library (dmso, dmf, urea, ethanol, etc.), you can omit the smiles and density fields - they will be looked up automatically.

Variables:

• name (str) – Identifier for the co-solvent (e.g., “dmso”)

• smiles (Optional[str]) – SMILES string (optional if co-solvent is in library)

• volume_fraction (Optional[float]) – Volume fraction (0-1), e.g., 0.30 for 30% v/v

• concentration (Optional[float]) – Molar concentration (mol/L)

• density (Optional[float]) – Density in g/mL (required for volume_fraction with custom molecules)

• residue_name (Optional[str]) – 3-letter residue name (default: first 3 chars of name)

Example (library co-solvent with volume fraction):

>>> CoSolventSpec(name="dmso", volume_fraction=0.30)

Example (library co-solvent with concentration):

>>> CoSolventSpec(name="urea", concentration=2.0)

Example (custom co-solvent):

>>> CoSolventSpec(
...     name="my_solvent",
...     smiles="CCOC(=O)C",
...     density=0.902,
...     volume_fraction=0.15
... )

name: str

smiles: str | None

volume_fraction: float | None

concentration: float | None

density: float | None

residue_name: str | None

validate_and_populate()

Validate specification and populate missing fields from library.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.PrimarySolventConfig(*, type='water', model=WaterModel.TIP3P)

Bases: BaseModel

Configuration for the primary solvent (usually water).

Variables:

• type (str) – Solvent type identifier

• model (WaterModel) – Water model to use (if type is “water”)

type: str

model: WaterModel

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.IonConfig(*, neutralize=True, nacl_concentration=0.1, kcl_concentration=0.0, mgcl2_concentration=0.0)

Bases: BaseModel

Configuration for ions in the solvent.

Variables:

• neutralize (bool) – Whether to add ions for charge neutralization

• nacl_concentration (float) – Additional NaCl concentration in mol/L

• kcl_concentration (float) – Additional KCl concentration in mol/L

• mgcl2_concentration (float) – Additional MgCl2 concentration in mol/L

neutralize: bool

nacl_concentration: float

kcl_concentration: float

mgcl2_concentration: float

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.BoxConfig(*, padding=1.2, shape=BoxShape.RHOMBIC_DODECAHEDRON, target_density=1.0, tolerance=2.0)

Bases: BaseModel

Configuration for the simulation box.

Variables:

• padding (float) – Distance from solute to box edge in nm

• shape (BoxShape) – Box geometry

• target_density (float) – Target density in g/mL

• tolerance (float) – Minimum molecular spacing for PACKMOL in Angstrom

padding: float

shape: BoxShape

target_density: float

tolerance: float

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.SolventConfig(*, primary=<factory>, co_solvents=<factory>, ions=<factory>, box=<factory>)

Bases: BaseModel

Complete solvent configuration.

Variables:

• primary (PrimarySolventConfig) – Primary solvent settings

• co_solvents (List[CoSolventSpec]) – List of co-solvent specifications

• ions (IonConfig) – Ion configuration

• box (BoxConfig) – Box geometry settings

primary: PrimarySolventConfig

co_solvents: List[CoSolventSpec]

ions: IonConfig

box: BoxConfig

validate_volume_fractions()

Ensure co-solvent volume fractions don’t exceed 1.0.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.AtomSelectionConfig(*, selection, description=None)

Bases: BaseModel

Configuration for selecting atoms for restraints.

Uses MDAnalysis-compatible selection syntax for flexibility.

Variables:

• selection (str) – MDAnalysis selection string (e.g., “resid 77 and name OG”)

• description (Optional[str]) – Optional human-readable description

selection: str

description: str | None

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.RestraintConfig(*, type, name, atom1, atom2, distance, force_constant=10000.0, enabled=True)

Bases: BaseModel

Configuration for a single restraint.

Variables:

• type (RestraintType) – Type of restraint (flat_bottom, harmonic, etc.)

• name (str) – Identifier for this restraint

• atom1 (AtomSelectionConfig) – First atom selection

• atom2 (AtomSelectionConfig) – Second atom selection

• distance (float) – Target/threshold distance in Angstroms

• force_constant (float) – Force constant in kJ/mol/nm^2

• enabled (bool) – Whether this restraint is active

type: RestraintType

name: str

atom1: AtomSelectionConfig

atom2: AtomSelectionConfig

distance: float

force_constant: float

enabled: bool

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.ThermodynamicsConfig(*, temperature, pressure=1.0)

Bases: BaseModel

Thermodynamic conditions for the simulation.

Variables:

• temperature (float) – System temperature in Kelvin

• pressure (float) – System pressure in atmospheres (for NPT)

• salt_concentration – Ionic strength in mol/L (deprecated, use solvent.ions)

temperature: float

pressure: float

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.SimulationPhaseConfig(*, ensemble, duration, samples, time_step=2.0, thermostat=ThermostatType.LANGEVIN_MIDDLE, thermostat_timescale=1.0, barostat=None, barostat_frequency=25, checkpoint_interval=60.0)

Bases: BaseModel

Configuration for a single simulation phase (equilibration or production).

Variables:

• ensemble (Ensemble) – Thermodynamic ensemble (NVT, NPT)

• duration (float) – Simulation duration in nanoseconds

• samples (int) – Number of trajectory frames to save

• time_step (float) – Integration time step in femtoseconds

• thermostat (ThermostatType) – Thermostat type

• thermostat_timescale (float) – Thermostat coupling timescale in ps

• barostat (Optional[BarostatType]) – Barostat type (for NPT)

• barostat_frequency (int) – Barostat update frequency (steps)

• checkpoint_interval (float) – Wall-time interval (seconds) between restart checkpoints for preemption resilience

ensemble: Ensemble

duration: float

samples: int

time_step: float

thermostat: ThermostatType

thermostat_timescale: float

barostat: BarostatType | None

barostat_frequency: int

checkpoint_interval: float

validate_ensemble_barostat()

Ensure NPT ensemble has a barostat configured.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.PositionRestraintConfig(*, group, force_constant=4184.0)

Bases: BaseModel

Configuration for positional restraints on an atom group.

Position restraints apply a harmonic potential to keep atoms near their initial coordinates. This is commonly used during equilibration to prevent large structural changes while the system relaxes.

Variables:

• group (str) – Predefined atom group name

• force_constant (float) – Force constant in kJ/mol/nm^2 (4184.0 = 1.0 kcal/mol/A^2)

group: str

force_constant: float

classmethod validate_group_name(v)

Validate that the group name is a recognized predefined group.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.EquilibrationStageConfig(*, name, duration, samples=100, ensemble=Ensemble.NVT, temperature=None, temperature_start=None, temperature_end=None, temperature_increment=1.0, temperature_interval=1200.0, position_restraints=<factory>, time_step=None, thermostat=None, thermostat_timescale=None, barostat=None, barostat_frequency=None)

Bases: BaseModel

Configuration for a single equilibration stage.

Supports two temperature modes:

1. Constant temperature: Set temperature field

2. Temperature ramping (simulated annealing): Set temperature_start and temperature_end fields

Position restraints can be applied to hold specific atom groups in place during the stage.

Variables:

• name (str) – Stage identifier (used in output paths)

• duration (float) – Stage duration in nanoseconds

• samples (int) – Number of trajectory frames to save

• ensemble (Ensemble) – Thermodynamic ensemble (NVT or NPT)

• temperature (Optional[float]) – Constant temperature in K (mutually exclusive with ramping)

• temperature_start (Optional[float]) – Starting temperature for ramping in K

• temperature_end (Optional[float]) – Ending temperature for ramping in K

• temperature_increment (float) – Temperature increment per update in K

• temperature_interval (float) – Time between temperature updates in fs

• position_restraints (List[PositionRestraintConfig]) – List of position restraints for this stage

• time_step (Optional[float]) – Optional time step override in fs

• thermostat (Optional[ThermostatType]) – Optional thermostat type override

• thermostat_timescale (Optional[float]) – Optional thermostat timescale override in ps

• barostat (Optional[BarostatType]) – Optional barostat type (for NPT ensemble)

• barostat_frequency (Optional[int]) – Optional barostat update frequency

name: str

duration: float

samples: int

ensemble: Ensemble

temperature: float | None

temperature_start: float | None

temperature_end: float | None

temperature_increment: float

temperature_interval: float

position_restraints: List[PositionRestraintConfig]

time_step: float | None

thermostat: ThermostatType | None

thermostat_timescale: float | None

barostat: BarostatType | None

barostat_frequency: int | None

validate_temperature_mode()

Ensure valid temperature specification.

validate_npt_barostat()

Ensure NPT ensemble has a barostat configured.

property is_temperature_ramping: bool

Check if this stage uses temperature ramping.

get_start_temperature()

Get the starting temperature of this stage.

get_final_temperature()

Get the final temperature of this stage.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.SimulationPhasesConfig(*, equilibration_stages=None, production)

Bases: BaseModel

Configuration for all simulation phases.

Variables:

• equilibration_stages (Optional[List[EquilibrationStageConfig]]) – Multi-stage equilibration protocol

• production (SimulationPhaseConfig) – Production phase settings

model_config = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

equilibration_stages: List[EquilibrationStageConfig] | None

production: SimulationPhaseConfig

classmethod warn_deprecated_segments(data)

Warn if the deprecated ‘segments’ field is present and remove it.

validate_equilibration_mode()

Ensure staged equilibration is configured.

property total_equilibration_duration: float

Total equilibration duration in nanoseconds.

Returns the sum of all stage durations.

property total_equilibration_samples: int

Total equilibration trajectory samples.

Returns the sum of all stage samples.

polyzymd.config.schema.expand_path(path)

Expand environment variables and user home in a path.

Supports: - $VAR and ${VAR} syntax for environment variables - ~ for user home directory

Parameters:

path (Path) – Path that may contain environment variables

Returns:

Path with variables expanded

Return type:

Path

class polyzymd.config.schema.OutputConfig(*, projects_directory=PosixPath('.'), scratch_directory=None, naming_template='{enzyme}_{substrate}_{polymer_type}_{duration}ns_{temperature}K_run{replicate}', job_scripts_subdir='job_scripts', slurm_logs_subdir='slurm_logs', save_checkpoint=True, save_state_data=True, trajectory_format='dcd', base_directory=None)

Bases: BaseModel

Configuration for simulation output.

Supports separate directories for: - scripts/logs (projects_directory): Where job scripts and SLURM logs are written - simulation data (scratch_directory): Where trajectories, checkpoints go

This separation allows running simulations on HPC systems where code lives in long-term storage (projects) but data is written to high-performance scratch storage.

Variables:

• projects_directory (Path) – Directory for scripts, configs, logs (long-term storage)

• scratch_directory (Optional[Path]) – Directory for simulation output (high-performance storage)

• naming_template (str) – Template for naming working directories

• job_scripts_subdir (str) – Subdirectory name for job scripts within projects

• slurm_logs_subdir (str) – Subdirectory name for SLURM logs within projects

• save_checkpoint (bool) – Whether to save checkpoint files

• save_state_data (bool) – Whether to save thermodynamic state data

• trajectory_format (str) – Output trajectory format

Example YAML:

output:

projects_directory: /projects/user/polyzymd scratch_directory: /scratch/alpine/user/simulations naming_template: “{enzyme}_{substrate}_{temperature}K_run{replicate}”

projects_directory: Path

scratch_directory: Path | None

naming_template: str

job_scripts_subdir: str

slurm_logs_subdir: str

save_checkpoint: bool

save_state_data: bool

trajectory_format: str

base_directory: Path | None

classmethod expand_env_vars_in_paths(v)

Expand environment variables and ~ in path fields.

Supports $USER, ${HOME}, ~/path, etc.

handle_legacy_base_directory()

Handle legacy base_directory field for backwards compatibility.

property effective_scratch_directory: Path

Get the effective scratch directory (falls back to projects if not set).

format_directory_name(enzyme, substrate, polymer_type, temperature, replicate, duration=0.0, **kwargs)

Format the directory name using the template.

Parameters:

• enzyme (str) – Enzyme name

• substrate (str) – Substrate name

• polymer_type (str) – Polymer type (or “none”)

• temperature (float) – Temperature in K

• replicate (int) – Replicate number

• duration (float) – Production duration in ns

• **kwargs (Any) – Additional template variables

Returns:

Formatted directory name

Return type:

str

get_job_scripts_directory()

Get the directory for job scripts.

Returns:

Path to job scripts directory (within projects)

Return type:

Path

get_slurm_logs_directory()

Get the directory for SLURM log files.

Returns:

Path to SLURM logs directory (within projects)

Return type:

Path

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.ForceFieldConfig(*, protein='ff14sb_off_impropers_0.0.4.offxml', small_molecule='openff-2.0.0.offxml')

Bases: BaseModel

Configuration for force field selection.

Variables:

• protein (str) – Force field for proteins

• small_molecule (str) – Force field for small molecules

• water – Water model force field (derived from solvent config)

protein: str

small_molecule: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polyzymd.config.schema.SimulationConfig(*, name, description=None, enzyme, substrate=None, polymers=None, solvent=<factory>, restraints=<factory>, thermodynamics, simulation_phases, output=<factory>, force_field=<factory>)

Bases: BaseModel

Complete simulation configuration.

This is the top-level configuration model that contains all settings for a PolyzyMD simulation.

Variables:

• name (str) – Simulation name/identifier

• description (Optional[str]) – Optional description

• enzyme (EnzymeConfig) – Enzyme configuration

• substrate (Optional[SubstrateConfig]) – Substrate/ligand configuration

• polymers (Optional[PolymerConfig]) – Polymer configuration (optional)

• solvent (SolventConfig) – Solvent and box configuration

• restraints (List[RestraintConfig]) – List of restraint configurations

• thermodynamics (ThermodynamicsConfig) – Temperature/pressure settings

• simulation_phases (SimulationPhasesConfig) – Equilibration and production settings

• output (OutputConfig) – Output file settings

• force_field (ForceFieldConfig) – Force field selection

Example

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

name: str

description: str | None

enzyme: EnzymeConfig

substrate: SubstrateConfig | None

polymers: PolymerConfig | None

solvent: SolventConfig

restraints: List[RestraintConfig]

thermodynamics: ThermodynamicsConfig

simulation_phases: SimulationPhasesConfig

output: OutputConfig

force_field: ForceFieldConfig

classmethod from_yaml(path)

Load configuration from a YAML file.

Parameters:

path (str | Path) – Path to the YAML configuration file

Returns:

SimulationConfig instance

Raises:

• FileNotFoundError – If file doesn’t exist

• ValidationError – If configuration is invalid

Return type:

SimulationConfig

to_yaml(path)

Save configuration to a YAML file.

Parameters:

path (str | Path) – Path to save the configuration file

get_working_directory(replicate=1)

Get the working directory path for a given replicate (in scratch).

This returns the path where simulation output (trajectories, checkpoints) will be written, which is in the scratch directory.

Parameters:

replicate (int) – Replicate number

Returns:

Path to the working directory (in scratch)

Return type:

Path

get_projects_directory()

Get the projects directory path.

This is where scripts, configs, and logs are stored.

Returns:

Path to the projects directory

Return type:

Path

discover_replicate_dirs()

Auto-detect all replicate directories on disk.

Builds a glob pattern from the naming template with replicate="*" and scans the effective scratch directory.

Returns:

Sorted list of (replicate_number, directory_path) tuples.

Return type:

list[tuple[int, Path]]

to_signac_statepoint(replicate=1)

Convert configuration to a Signac-compatible state point dictionary.

Parameters:

replicate (int) – Replicate number

Returns:

Dictionary suitable for use as a Signac state point

Return type:

Dict[str, Any]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Loader Utilities

YAML configuration loader and saver for PolyzyMD.

This module provides functions to load and save SimulationConfig objects from/to YAML files, with support for Path objects and environment variable expansion.

class polyzymd.config.loader.ConfigLoader(base_path)

Bases: object

Custom YAML loader with support for includes and references.

__init__(base_path)

load(stream)

Load YAML with custom processing.

polyzymd.config.loader.load_config(path)

Load a SimulationConfig from a YAML file.

Parameters:

path (str | Path) – Path to the YAML configuration file

Returns:

Validated SimulationConfig instance

Raises:

• FileNotFoundError – If the config file doesn’t exist

• yaml.YAMLError – If the YAML is malformed

• pydantic.ValidationError – If the configuration is invalid

Return type:

SimulationConfig

Example

>>> config = load_config("my_simulation.yaml")
>>> print(config.enzyme.name)
"LipA"

polyzymd.config.loader.save_config(config, path, relative_paths=True)

Save a SimulationConfig to a YAML file.

Parameters:

• config (SimulationConfig) – Configuration to save

• path (str | Path) – Destination path for the YAML file

• relative_paths (bool) – Whether to convert paths to relative (default: True)

Example

>>> config = SimulationConfig(...)
>>> save_config(config, "output_config.yaml")

polyzymd.config.loader.load_config_dict(data, base_path=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/polyzymd/checkouts/latest/docs/source'))

Create a SimulationConfig from a dictionary.

This is useful for programmatic configuration creation.

Parameters:

• data (Dict[str, Any]) – Configuration dictionary

• base_path (Path) – Base path for resolving relative paths

Returns:

Validated SimulationConfig instance

Return type:

SimulationConfig

Example

>>> data = {
...     "name": "test_sim",
...     "enzyme": {"name": "LipA", "pdb_path": "enzyme.pdb"},
...     ...
... }
>>> config = load_config_dict(data)