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.

name

Identifier for the enzyme (e.g., “LipA”)

Type:

str

pdb_path

Path to the PDB file containing the enzyme structure

Type:

Path

description

Optional description of the enzyme

Type:

str | None

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.

name

Identifier for the substrate (e.g., “Resorufin-Butyrate”)

Type:

str

sdf_path

Path to SDF file with docked conformers

Type:

Path

conformer_index

Which conformer to use (0-indexed)

Type:

int

charge_method

Method for assigning partial charges

Type:

ChargeMethod

residue_name

3-letter residue name for topology (default: “LIG”)

Type:

str

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.

padding

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

Type:

float

tolerance

Minimum molecular spacing for PACKMOL in Angstrom.

Type:

float

movebadrandom

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).

Type:

bool

box_vectors

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).

Type:

list[float] | None

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.

label

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

Type:

str

probability

Probability of selecting this monomer (0-1)

Type:

float

name

Optional full name (e.g., “SBMA”, “EGPMA”)

Type:

str | None

smiles

Raw monomer SMILES string (required for dynamic generation)

Type:

str | None

residue_name

3-character PDB residue name (auto-generated if not provided)

Type:

str | None

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”

initiation

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

Type:

Path

polymerization

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

Type:

Path

termination

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

Type:

Path

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

enabled

Whether to include polymers in the system

Type:

bool

generation_mode

“cached” for pre-built SDFs, “dynamic” for on-the-fly generation

Type:

PolymerGenerationMode

type_prefix

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

Type:

str

monomers

List of monomer specifications with probabilities (and SMILES for dynamic)

Type:

list[MonomerSpec]

length

Number of monomer units per polymer chain

Type:

int

count

Number of polymer chains to add

Type:

int

sdf_directory

Path to pre-built polymer SDF files (for cached mode)

Type:

Path | None

reactions

Reaction templates for ATRP (required for dynamic mode)

Type:

ReactionConfig | None

charger

Charge assignment method for generated polymers

Type:

ChargeMethod

max_retries

Maximum retries for polymer generation (ring-piercing failures)

Type:

int

cache_directory

Directory for caching generated polymers and fragments

Type:

Path

packing

Settings for packing polymers around the solute

Type:

PolymerPackingConfig

random_seed

Random seed for polymer sequence generation (for reproducibility)

Type:

int | None

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.

name

Identifier for the co-solvent (e.g., “dmso”)

Type:

str

smiles

SMILES string (optional if co-solvent is in library)

Type:

str | None

volume_fraction

Volume fraction (0-1), e.g., 0.30 for 30% v/v

Type:

float | None

concentration

Molar concentration (mol/L)

Type:

float | None

density

Density in g/mL (required for volume_fraction with custom molecules)

Type:

float | None

residue_name

3-letter residue name (default: first 3 chars of name)

Type:

str | None

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).

type

Solvent type identifier

Type:

str

model

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

Type:

WaterModel

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.

neutralize

Whether to add ions for charge neutralization

Type:

bool

nacl_concentration

Additional NaCl concentration in mol/L

Type:

float

kcl_concentration

Additional KCl concentration in mol/L

Type:

float

mgcl2_concentration

Additional MgCl2 concentration in mol/L

Type:

float

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.

padding

Distance from solute to box edge in nm

Type:

float

shape

Box geometry

Type:

BoxShape

target_density

Target density in g/mL

Type:

float

tolerance

Minimum molecular spacing for PACKMOL in Angstrom

Type:

float

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.

primary

Primary solvent settings

Type:

PrimarySolventConfig

co_solvents

List of co-solvent specifications

Type:

list[CoSolventSpec]

ions

Ion configuration

Type:

IonConfig

box

Box geometry settings

Type:

BoxConfig

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.

selection

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

Type:

str

description

Optional human-readable description

Type:

str | None

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.

type

Type of restraint (flat_bottom, harmonic, etc.)

Type:

RestraintType

name

Identifier for this restraint

Type:

str

atom1

First atom selection

Type:

AtomSelectionConfig

atom2

Second atom selection

Type:

AtomSelectionConfig

distance

Target/threshold distance in Angstroms

Type:

float

force_constant

Force constant in kJ/mol/nm^2

Type:

float

enabled

Whether this restraint is active

Type:

bool

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.

temperature

System temperature in Kelvin

Type:

float

pressure

System pressure in atmospheres (for NPT)

Type:

float

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).

ensemble

Thermodynamic ensemble (NVT, NPT)

Type:

Ensemble

duration

Simulation duration in nanoseconds

Type:

float

samples

Number of trajectory frames to save

Type:

int

time_step

Integration time step in femtoseconds

Type:

float

thermostat

Thermostat type

Type:

ThermostatType

thermostat_timescale

Thermostat coupling timescale in ps

Type:

float

barostat

Barostat type (for NPT)

Type:

BarostatType | None

barostat_frequency

Barostat update frequency (steps)

Type:

int

checkpoint_interval

Wall-time interval (seconds) between restart checkpoints for preemption resilience

Type:

float

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.

group

Predefined atom group name

Type:

str

force_constant

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

Type:

float

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.

name

Stage identifier (used in output paths)

Type:

str

duration

Stage duration in nanoseconds

Type:

float

samples

Number of trajectory frames to save

Type:

int

ensemble

Thermodynamic ensemble (NVT or NPT)

Type:

Ensemble

temperature

Constant temperature in K (mutually exclusive with ramping)

Type:

float | None

temperature_start

Starting temperature for ramping in K

Type:

float | None

temperature_end

Ending temperature for ramping in K

Type:

float | None

temperature_increment

Temperature increment per update in K

Type:

float

temperature_interval

Time between temperature updates in fs

Type:

float

position_restraints

List of position restraints for this stage

Type:

list[PositionRestraintConfig]

time_step

Optional time step override in fs

Type:

float | None

thermostat

Optional thermostat type override

Type:

ThermostatType | None

thermostat_timescale

Optional thermostat timescale override in ps

Type:

float | None

barostat

Optional barostat type (for NPT ensemble)

Type:

BarostatType | None

barostat_frequency

Optional barostat update frequency

Type:

int | None

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.

equilibration_stages

Multi-stage equilibration protocol

Type:

list[EquilibrationStageConfig] | None

production

Production phase settings

Type:

SimulationPhaseConfig

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.

projects_directory

Directory for scripts, configs, logs (long-term storage)

Type:

Path

scratch_directory

Directory for simulation output (high-performance storage)

Type:

Path | None

naming_template

Template for naming working directories

Type:

str

job_scripts_subdir

Subdirectory name for job scripts within projects

Type:

str

slurm_logs_subdir

Subdirectory name for SLURM logs within projects

Type:

str

save_checkpoint

Whether to save checkpoint files

Type:

bool

save_state_data

Whether to save thermodynamic state data

Type:

bool

trajectory_format

Output trajectory format

Type:

str

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.

protein

Force field for proteins

Type:

str

small_molecule

Force field for small molecules

Type:

str

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.OpenMMEngineConfig(*, platform='CUDA', device_index=None, precision='mixed')

Bases: BaseModel

OpenMM-specific engine settings.

These settings control OpenMM platform selection and device configuration. Only relevant when engine is "openmm".

platform

OpenMM platform to use for computation.

Type:

str

device_index

GPU device index (platform-specific).

Type:

str | None

precision

Floating-point precision mode.

Type:

str

platform: str

device_index: str | None

precision: str

model_config = {}

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

class polyzymd.config.schema.GromacsEngineConfig(*, gmx_binary=None, mdrun_flags='', grompp_flags='-maxwarn 1', mdrun_flags_equilibration=None, mdrun_flags_production=None, command_prefix=None, mpi_launcher_flags='', module_load=None, env_exports=<factory>, setup_commands=<factory>, ntmpi=1, slurm_ntasks=None, ntomp=8, gpu=False, gpus=1, memory='16G')

Bases: BaseModel

GROMACS-specific engine settings.

These settings control how GROMACS binaries are located and invoked, and how SLURM resources are allocated for GROMACS jobs.

GROMACS users configure parallelism via ntmpi (MPI ranks) and ntomp (OpenMP threads per rank). These map directly to the gmx mdrun -ntmpi and -ntomp flags. The corresponding SLURM resources (ntasks, cpus_per_task, memory) are set to match.

Set gpu: true when running a CUDA-enabled GROMACS build on a GPU node. When False (default), the SLURM script omits GPU directives entirely.

gmx_binary

Path or name of the GROMACS binary. Resolved via config > $GMX_BIN > PATH discovery if None.

Type:

str | None

mdrun_flags

Additional flags passed to gmx mdrun (all stages).

Type:

str

grompp_flags

Additional flags passed to gmx grompp.

Type:

str

module_load

Module load command for HPC (e.g. "module load gromacs/2024")

Type:

str | None

ntmpi

Number of MPI ranks for gmx mdrun -ntmpi. Also sets SLURM --ntasks.

Type:

int

ntomp

Number of OpenMP threads per rank for gmx mdrun -ntomp. Also sets SLURM --cpus-per-task.

Type:

int

gpu

Request a GPU via SLURM. When False, the --gres=gpu directive is omitted entirely.

Type:

bool

gpus

Number of GPUs to request when gpu is True. Ignored when gpu is False.

Type:

int

memory

SLURM --mem allocation for GROMACS jobs.

Type:

str

gmx_binary: str | None

mdrun_flags: str

grompp_flags: str

mdrun_flags_equilibration: str | None

mdrun_flags_production: str | None

command_prefix: str | None

mpi_launcher_flags: str

module_load: str | None

env_exports: dict[str, str]

setup_commands: list[str]

ntmpi: int

slurm_ntasks: int | None

ntomp: int

gpu: bool

gpus: int

memory: 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>, engine='openmm', openmm=<factory>, gromacs=<factory>)

Bases: BaseModel

Complete simulation configuration.

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

name

Simulation name/identifier

Type:

str

description

Optional description

Type:

str | None

enzyme

Enzyme configuration

Type:

EnzymeConfig

substrate

Substrate/ligand configuration

Type:

SubstrateConfig | None

polymers

Polymer configuration (optional)

Type:

PolymerConfig | None

solvent

Solvent and box configuration

Type:

SolventConfig

restraints

List of restraint configurations

Type:

list[RestraintConfig]

thermodynamics

Temperature/pressure settings

Type:

ThermodynamicsConfig

simulation_phases

Equilibration and production settings

Type:

SimulationPhasesConfig

output

Output file settings

Type:

OutputConfig

force_field

Force field selection

Type:

ForceFieldConfig

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

engine: Literal['openmm', 'gromacs']

openmm: OpenMMEngineConfig

gromacs: GromacsEngineConfig

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 or Path) – Path to the YAML configuration file.

Returns:

Validated configuration instance.

Return type:

SimulationConfig

Raises:

• FileNotFoundError – If the config file doesn’t exist.

• yaml.YAMLError – If the YAML is malformed.

• pydantic.ValidationError – If the configuration is invalid.

Examples

>>> 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 or Path) – Destination path for the YAML file.

• relative_paths (bool, optional) – Whether to convert paths to relative, by default True.

Examples

>>> 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/v1.3.0-rc.3/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)