CLI Reference

Complete reference for all PolyzyMD command-line interface commands.

Global Options

All commands support these global options:

polyzymd --version        # Show version
polyzymd --help           # Show help
polyzymd -v <command>     # Verbose output (debug logging)
polyzymd --openff-logs <command>  # Enable verbose OpenFF logs

Logging Behavior

By default, PolyzyMD suppresses verbose log messages from OpenFF Interchange and Toolkit libraries. These libraries generate per-atom INFO messages during system building (e.g., “Preset charges applied to atom index 8667” or “Key collision with different parameters”). For large systems with tens of thousands of atoms, this can produce millions of log lines.

Default behavior: OpenFF INFO logs are suppressed; only WARNING and ERROR messages are shown.

To enable OpenFF logs for debugging:

polyzymd --openff-logs build -c config.yaml
polyzymd --openff-logs run -c config.yaml

This is useful when:

Debugging force field parameter assignment issues
Investigating charge assignment problems
Troubleshooting system building failures

polyzymd init

Initialize a new PolyzyMD project directory with template files.

polyzymd init --name <project_name>
polyzymd init -n <project_name>

Options

Option	Short	Required	Description
`--name`	`-n`	Yes	Name of the project directory to create

What It Creates

<project_name>/
├── config.yaml              <- Template configuration (edit this)
├── structures/              <- Add your PDB/SDF files here
│   ├── place_protein_here.placeholder.txt
│   └── place_ligand_here.placeholder.txt
├── job_scripts/             <- Generated SLURM scripts go here
└── slurm_logs/              <- SLURM output logs go here

Example

# Create a new project
polyzymd init --name lipase_dmso_study
cd lipase_dmso_study

# Add your structure files
cp ~/structures/LipA.pdb structures/enzyme.pdb
cp ~/docking/substrate.sdf structures/substrate.sdf

# Remove placeholder files
rm structures/*.placeholder.txt

# Edit the configuration
nano config.yaml

# Validate
polyzymd validate -c config.yaml

Notes

The command will fail if the directory already exists
The template config.yaml has all sections commented out with example values
Uncomment and modify only the sections you need

polyzymd validate

Validate a configuration file without building or running.

polyzymd validate --config <path>
polyzymd validate -c <path>

Options

Option	Short	Required	Description
`--config`	`-c`	Yes	Path to YAML configuration file

What It Checks

YAML syntax validity
Required fields are present
Referenced files (PDB, SDF) exist
Monomer probabilities sum to 1.0
Valid enum values (water model, ensemble, etc.)
Co-solvent specification (volume_fraction XOR concentration)

Example

polyzymd validate -c config.yaml

Output (success):

Validating configuration: config.yaml
Configuration is valid!

Summary:
  Name: LipA_polymer_simulation
  Enzyme: LipA
  Substrate: ResorufinButyrate
  Polymers: SBMA-EGPMA
    Count: 2
    Length: 5
    Monomer A: 98.0%
    Monomer B: 2.0%
  Temperature: 300.0 K
  Pressure: 1.0 atm

Simulation phases:
  Equilibration: 1.0 ns (NVT)
  Production: 100.0 ns (NPT)
  Segments: 10

polyzymd build

Build the simulation system (parameterize, solvate) without running.

polyzymd build --config <path> [options]
polyzymd build -c <path> -r <replicate>
polyzymd build -c <path> --gromacs    # Export for GROMACS

Options

Option	Short	Required	Default	Description
`--config`	`-c`	Yes	-	Path to YAML configuration file
`--replicate`	`-r`	No	1	Replicate number (affects polymer random seed)
`--scratch-dir`	-	No	from config	Override scratch directory
`--projects-dir`	-	No	from config	Override projects directory
`--output-dir`	`-o`	No	from config	Alias for –scratch-dir
`--dry-run`	-	No	false	Validate only, don’t build
`--gromacs`	-	No	false	Export to GROMACS format instead of OpenMM

Example

# Build replicate 1 for OpenMM
polyzymd build -c config.yaml -r 1

# Build with custom output directory
polyzymd build -c config.yaml -r 1 --scratch-dir ./test_output

# Dry run to check configuration
polyzymd build -c config.yaml --dry-run

# Export to GROMACS format
polyzymd build -c config.yaml -r 1 --gromacs

Output Files (OpenMM)

The build command creates:

solvated_system.pdb - Complete system with water and ions
system.xml - OpenMM serialized system
topology.json - Topology information
build.log - Build process log

Output Files (GROMACS)

With --gromacs, the build command creates in {projects_dir}/replicate_{N}/gromacs/:

{system}.gro - GROMACS coordinate file
{system}.top - GROMACS topology file
em.mdp - Energy minimization parameters
eq_XX_name.mdp - Equilibration stage parameters
prod.mdp - Production parameters
posre_*.itp - Position restraint files (if configured)
run_{system}_gromacs.sh - Shell script to run the workflow

polyzymd run

Build and run a complete simulation.

By default, runs using OpenMM. Use --gromacs to run using GROMACS instead.

# OpenMM (default)
polyzymd run --config <path> [options]
polyzymd run -c <path> -r <replicate>

# GROMACS
polyzymd run -c <path> --gromacs
polyzymd run -c <path> --gromacs --gmx-path /usr/local/gromacs/bin/gmx
polyzymd run -c <path> --gromacs --dry-run

Options

Option	Short	Required	Default	Description
`--config`	`-c`	Yes	-	Path to YAML configuration file
`--replicate`	`-r`	No	1	Replicate number
`--scratch-dir`	-	No	from config	Override scratch directory
`--projects-dir`	-	No	from config	Override projects directory
`--segment-time`	-	No	auto	Override production time per segment (ns) [OpenMM only]
`--segment-frames`	-	No	auto	Override frames per segment [OpenMM only]
`--skip-build`	-	No	false	Skip building (use existing system) [OpenMM only]
`--gromacs`	-	No	false	Run using GROMACS instead of OpenMM
`--gmx-path`	-	No	“gmx”	Path to GROMACS executable [GROMACS only]
`--dry-run`	-	No	false	Export files but don’t run simulation [GROMACS only]

Example (OpenMM)

# Run locally (useful for testing)
polyzymd run -c config.yaml -r 1

# Run with shorter segment for testing
polyzymd run -c config.yaml -r 1 --segment-time 0.1 --segment-frames 10

# Skip building (use pre-built system)
polyzymd run -c config.yaml -r 1 --skip-build

Example (GROMACS)

# Run full GROMACS workflow locally
polyzymd run -c config.yaml -r 1 --gromacs

# Use custom GROMACS installation
polyzymd run -c config.yaml --gromacs --gmx-path /usr/local/gromacs/bin/gmx

# Export files only (for manual execution or HPC)
polyzymd run -c config.yaml --gromacs --dry-run

OpenMM Workflow

Load and validate configuration
Build system (enzyme + substrate + polymers + solvent)
Apply restraints (if configured)
Run energy minimization
Run equilibration (NVT/NPT stages)
Run first production segment (NPT)

GROMACS Workflow

Load and validate configuration
Build system (same as OpenMM)
Export to GROMACS format (.gro, .top, .mdp files)
Run energy minimization (grompp + mdrun)
Run equilibration stages (grompp + mdrun for each stage)
Run production MD (grompp + mdrun)
Post-process trajectory (trjconv for PBC handling)

All GROMACS output is streamed in real-time for familiar user experience. On any failure, execution stops immediately and all intermediate files are preserved for debugging.

GROMACS Notes

Requires GROMACS to be installed and accessible via PATH
Use --gmx-path to specify a custom GROMACS executable location
MDP parameters are generated from your config.yaml to match OpenMM settings
OpenFF force field defaults are used (rcoulomb=0.9, rvdw=0.9, PME) for 1:1 parity with OpenMM
Position restraints are automatically generated for equilibration stages
Post-processing creates prod_nojump.xtc and prod_centered.xtc trajectories

GROMACS Output Files

Files are created in {projects_dir}/replicate_{N}/gromacs/:

gromacs/
├── {system}.gro              # Initial coordinates
├── {system}.top              # Topology
├── em.mdp                    # Energy minimization parameters
├── eq_01_nvt.mdp             # Equilibration stage 1 (NVT)
├── eq_02_npt.mdp             # Equilibration stage 2 (NPT)
├── prod.mdp                  # Production parameters
├── posre_*.itp               # Position restraint files
├── run_{system}_gromacs.sh   # Generated run script
├── em.tpr, em.gro, em.edr    # Energy minimization outputs
├── eq_01.*, eq_02.*          # Equilibration outputs
├── prod.tpr, prod.xtc, ...   # Production outputs
├── prod_nojump.xtc           # Trajectory without PBC jumps
└── prod_centered.xtc         # Centered trajectory for visualization

polyzymd submit

Submit daisy-chain jobs to SLURM for HPC execution.

polyzymd submit --config <path> --replicates <range> [options]
polyzymd submit -c <path> -r 1-5 --preset aa100

Options

Option	Short	Required	Default	Description
`--config`	`-c`	Yes	-	Path to YAML configuration file
`--replicates`	`-r`	No	“1”	Replicate range (e.g., “1-5”, “1,3,5”)
`--preset`	-	No	aa100	SLURM partition preset
`--email`	-	No	“”	Email for job notifications
`--scratch-dir`	-	No	from config	Override scratch directory
`--projects-dir`	-	No	from config	Override projects directory
`--output-dir`	-	No	auto	Directory for job scripts
`--time-limit`	-	No	from preset	Override SLURM time limit (HH:MM:SS)
`--memory`	-	No	3G	Override SLURM memory allocation
`--openff-logs`	-	No	false	Enable verbose OpenFF logs in job scripts
`--dry-run`	-	No	false	Generate scripts without submitting

SLURM Presets

Preset	Partition	Time Limit	Description
`aa100`	aa100	24:00:00	NVIDIA A100 GPUs
`al40`	al40	24:00:00	NVIDIA L40 GPUs
`blanca-shirts`	blanca-shirts	7-00:00:00	Shirts lab partition
`testing`	atesting	01:00:00	Quick tests

Example

# Dry run first to check scripts
polyzymd submit -c config.yaml -r 1-5 --preset aa100 --dry-run

# Submit for real with email notifications
polyzymd submit -c config.yaml -r 1-5 --preset aa100 --email you@university.edu

# Quick test with short time limit
polyzymd submit -c config.yaml -r 1 --preset testing --time-limit 0:05:00

# Custom directories for HPC
polyzymd submit -c config.yaml -r 1-3 --preset aa100 \
    --scratch-dir /scratch/alpine/$USER/sims \
    --projects-dir /projects/$USER/polyzymd

Daisy-Chain Jobs

The submit command creates a chain of dependent SLURM jobs:

Job 1 (initial)  →  Job 2 (continue)  →  Job 3 (continue)  →  ...
   build + eq          segment 1           segment 2
   + segment 0

Each job only starts after the previous one completes successfully.

polyzymd continue

Continue a simulation from a previous segment checkpoint.

polyzymd continue --working-dir <path> --segment <n> --segment-time <ns>
polyzymd continue -w <path> -s <n> -t <ns>

Options

Option	Short	Required	Default	Description
`--working-dir`	`-w`	Yes	-	Working directory with previous segment
`--segment`	`-s`	Yes	-	Segment index to run (1-based)
`--segment-time`	`-t`	Yes	-	Duration of this segment (ns)
`--num-samples`	`-n`	No	250	Number of frames to save

Example

# Continue to segment 2 (after segment 1 completed)
polyzymd continue -w /scratch/user/sim/LipA_300K_run1 -s 2 -t 10.0 -n 250

Notes

This command is typically called by SLURM continuation scripts, not manually
It loads the checkpoint from the previous segment automatically
The segment index is 1-based (segment 1 continues from segment 0)

polyzymd info

Display PolyzyMD installation and dependency information.

polyzymd info

Example Output

PolyzyMD - Molecular Dynamics for Enzyme-Polymer Systems
Version: 0.1.0

Dependencies:
  OpenMM: 8.1.1
  OpenFF Toolkit: 0.16.0
  OpenFF Interchange: 0.3.25
  Pydantic: 2.7.1

Example configs: polyzymd/configs/examples/

Use Cases

Verify installation is complete
Check dependency versions for troubleshooting
Confirm GPU-enabled OpenMM is installed

Environment Variables

PolyzyMD expands environment variables in configuration paths:

Variable	Example	Description
`$USER`	jola3134	Current username
`$HOME`	/home/jola3134	Home directory
`~`	/home/jola3134	Home directory shortcut
`${VAR}`	-	Any environment variable

Example

output:
  projects_directory: "/projects/$USER/polyzymd"
  scratch_directory: "/scratch/alpine/$USER/simulations"

Exit Codes

Code	Meaning
0	Success
1	Error (validation failure, build failure, etc.)

CLI Reference

Global Options

Logging Behavior

polyzymd init

Options

What It Creates

Example

Notes

polyzymd validate

Options

What It Checks

Example

polyzymd build

Options

Example

Output Files (OpenMM)

Output Files (GROMACS)

polyzymd run

Options

Example (OpenMM)

Example (GROMACS)

OpenMM Workflow

GROMACS Workflow

GROMACS Notes

GROMACS Output Files

polyzymd submit

Options

SLURM Presets

Example

Daisy-Chain Jobs

polyzymd continue

Options

Example

Notes

polyzymd info

Example Output

Use Cases

Environment Variables

Example

Exit Codes

See Also