pyCADD.Dynamic package

Submodules

pyCADD.Dynamic.analysis module

Molecular dynamics trajectory analysis utilities.

This module provides functions for analyzing molecular dynamics trajectories including RMSD/RMSF calculations, hydrogen bond analysis, distance and angle tracking, energy analysis, and frame extraction capabilities.

pyCADD.Dynamic.cli module

pyCADD.Dynamic.cli.md_prepare(protein_file: str, molecule_file: str, charge: int = 0, multiplicity: int = 1, solvent: str = 'water', parallel: int = 4, time: float = 100.0, dft: str = 'B3LYP', basis_set: str = '6-31g*', charge_method: str = 'resp', keep_water: bool = False, box_size: float = 10.0, overwrite: bool = False)

pyCADD.Dynamic.cli.md_simulate(top_file: str, inpcrd_file: str, with_gpu: int = 0)

pyCADD.Dynamic.cli.md_workflow(protein_file: str, molecule_file: str, charge: int = 0, multiplicity: int = 1, solvent: str = 'water', parallel: int = 1, time: float = 1.0, dft: str = 'B3LYP', basis_set: str = '6-31G*', charge_method: str = 'RESP', keep_water: bool = False, box_size: float = 10.0, overwrite: bool = False, with_gpu: int = 0, analysis: bool = True)

pyCADD.Dynamic.common module

High-level molecular dynamics simulation workflow management.

This module provides the Processor class which serves as the main interface for managing complete molecular dynamics simulation workflows including system preparation, simulation execution, and trajectory analysis.

class pyCADD.Dynamic.common.Processor(work_dir: str = None, apo: bool = False)

Bases: object

High-level molecular dynamics simulation workflow manager.

The Processor class provides a complete interface for managing molecular dynamics simulations from system preparation through analysis.

work_dir

Main working directory for the simulation project.

Type:

str

apo

Whether this is an apo (protein-only) system.

Type:

bool

pro_file

Prepared protein structure file.

Type:

File

mol2_file

Ligand MOL2 file (None for apo systems).

Type:

File

frcmod_file

Force field parameter file for ligand.

Type:

File

comsolvate_topfile

Solvated system topology file.

Type:

File

comsolvate_crdfile

Solvated system coordinate file.

Type:

File

comsolvate_pdbfile

Solvated system PDB file.

Type:

File

com_topfile

Complex topology file.

Type:

File

pro_topfile

Protein topology file.

Type:

File

lig_topfile

Ligand topology file.

Type:

File

md_process_list

List of MD simulation processes to execute.

Type:

list

__init__(work_dir: str = None, apo: bool = False)

Initializes the MD simulation processor.

Sets up the directory structure and initializes attributes for managing a molecular dynamics simulation workflow.

Parameters:

• work_dir (str, optional) – Main working directory for simulation files. Defaults to current working directory.

• apo (bool, optional) – Whether this is an apo (protein-only) system. Defaults to False (protein-ligand system).

protein_prepare(protein_file_path: str | File, keep_water: bool = False, overwrite: bool = False) → None

Prepare protein structure for molecular dynamics simulation.

Processes the input protein structure using pdb4amber to clean up the structure, add missing atoms, and prepare it for use with Amber force fields.

Parameters:

• protein_file_path (str | File) – Path to the input protein structure file (PDB format).

• keep_water (bool) – Whether to retain crystal water molecules in the structure. Defaults to False.

• overwrite (bool) – Whether to overwrite existing prepared files. Defaults to False.

Note

The prepared protein file is automatically saved in the protein subdirectory and stored in self.pro_file for subsequent use.

molecule_prepare(molecule_file_path: str | File, charge: int = 0, multiplicity: int = 1, dft: str = 'B3LYP', basis_set: str = '6-31g*', cpu_num: int = 4, mem_use: str = '8GB', charge_method: Literal['resp', 'bcc', 'resp2'] = 'resp', solvent: str = 'water', delta: float = 0.5, overwrite: bool = False) → None

Prepare ligand molecule for molecular dynamics simulation.

Performs complete ligand parameterization including geometry optimization, charge calculation, and force field parameter generation using antechamber and related Amber tools.

Parameters:

• molecule_file_path (str | File) – Path to the input ligand structure file.

• charge (int) – Net charge of the ligand molecule. Defaults to 0.

• multiplicity (int) – Spin multiplicity of the ligand. Defaults to 1.

• dft (str) – DFT method for quantum chemistry calculations. Defaults to “B3LYP”.

• basis_set (str) – Basis set for quantum chemistry calculations. Defaults to “6-31g*”.

• cpu_num (int) – Number of CPU cores to use. Defaults to 4.

• mem_use (str) – Memory allocation for quantum calculations. Defaults to “8GB”.

• charge_method (str) – Method for partial charge calculation (“resp”, “bcc”, “resp2”). Defaults to “resp”.

• solvent (str) – Solvent model for charge calculation. Defaults to “water”.

• delta (float) – Grid spacing for RESP charge fitting. Defaults to 0.5.

• overwrite (bool) – Whether to overwrite existing prepared files. Defaults to False.

Note

The prepared MOL2 and FRCMOD files are automatically saved in the molecule/ subdirectory and stored in self.mol2_file and self.frcmod_file.

load_processed_profile(pro_file_path: str) → None

Load a previously prepared protein file.

Parameters:

pro_file_path (str | File) – Path to the prepared protein structure file.

load_processed_molfile(mol_file_path: str) → None

Load a previously prepared ligand MOL2 file.

Parameters:

mol_file_path (str | File) – Path to the prepared ligand MOL2 file.

load_frcmod_file(frcmod_file_path: str) → None

Load a ligand force field parameter file.

Parameters:

frcmod_file_path (str | File) – Path to the ligand FRCMOD parameter file.

leap_prepare(box_size: float = 10.0, box_type: str = 'TIP3PBOX', solvatebox: Literal['solvatebox', 'solvateOct'] = 'solvatebox') → None

Prepare solvated molecular system using tLEaP.

Builds the complete simulation system by combining protein and ligand (if applicable), adding solvent and counter-ions using Amber’s tLEaP program.

Parameters:

• box_size (float) – Distance from solute to box edge in Angstroms. Defaults to 10.0.

• box_type (str) – Type of water box (“TIP3PBOX”, “TIP4PBOX”, etc.). Defaults to “TIP3PBOX”.

• solvatebox (str) – Solvation command type (“solvatebox” or “solvateOct”). Defaults to “solvatebox”.

Raises:

RuntimeError – If required protein or ligand files haven’t been prepared.

Note

Automatically generates topology (.top), coordinate (.crd), and PDB files for the solvated system in the leap/ subdirectory.

set_prepared_file(file_path: str, file_type: str) → None

Set a pre-prepared file for use in the simulation workflow.

Allows manual specification of prepared files, useful for resuming workflows or using externally prepared files.

Parameters:

• file_path (str | File) – Path to the prepared file.

• file_type (str) – Type of file to set. Valid options: - “pro”: Prepared protein file - “mol2”: Prepared ligand MOL2 file - “frcmod”: Ligand force field parameter file - “com_pdb”: Solvated complex PDB file - “com_top”: Solvated complex topology file - “com_crd”: Solvated complex coordinate file

Raises:

RuntimeError – If an invalid file_type is specified.

get_water_resnum() → list

Get list of water residue numbers from the solvated system.

Returns:

List of residue numbers corresponding to water molecules.

Return type:

list

Raises:

ValueError – If the solvated complex PDB file hasn’t been prepared or loaded.

Note

Useful for setting up restraints or analysis that excludes water molecules.

create_minimize_input(maxcyc: int = 10000, ncyc: int = 5000, cut: float = 8.0, restraint: bool = False, restraint_mask: str = None, restraint_wt: float = 2.0, file_name: str = None, **kwargs) → File

Create energy minimization input file.

Generates Amber input files for energy minimization using steepest descent followed by conjugate gradient algorithms, with optional positional restraints.

Parameters:

• maxcyc (int) – Maximum number of minimization cycles. Defaults to 10000.

• ncyc (int) – Number of steepest descent cycles before switching to conjugate gradient. Defaults to 5000.

• cut (float) – Nonbonded interaction cutoff distance in Angstroms. Defaults to 8.0.

• restraint (bool) – Whether to apply positional restraints. Defaults to False.

• restraint_mask (str) – Amber mask syntax for restrained atoms. Required if restraint=True.

• restraint_wt (float) – Restraint force constant in kcal/mol/Ų. Defaults to 2.0.

• file_name (str) – Output filename for the input file. Defaults to “minimize.in”.

• **kwargs – Additional minimization parameters.

Returns:

The created minimization input file.

Return type:

File

Raises:

RuntimeError – If restraint=True but no restraint_mask is provided.

create_heat_input(target_temp: float = 300.0, heat_step: int = 9000, total_step: int = 10000, step_length: float = 0.002, restraint_mask: str = None, restraint_wt: float = 2.0, file_name: str = None) → File

Create system heating input file.

Generates Amber input file for gradual temperature increase from 0 K to target temperature using a controlled heating protocol with optional restraints.

Parameters:

• target_temp (float) – Target temperature in Kelvin. Defaults to 300.0.

• heat_step (int) – Number of steps for temperature ramping phase. Defaults to 9000.

• total_step (int) – Total simulation steps for heating protocol. Defaults to 10000.

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• restraint_mask (str) – Optional Amber mask for restrained atoms.

• restraint_wt (float) – Restraint force constant in kcal/mol/Ų. Defaults to 2.0.

• file_name (str) – Output filename for input file. Defaults to “heat.in”.

Returns:

The created heating input file.

Return type:

File

Note

Uses a two-phase protocol: linear temperature ramp followed by temperature maintenance at the target value.

create_nvt_input(init_temp: float = 300.0, total_step: int = 500000, step_length: float = 0.002, irest: int = 1, ntx: int = 5, file_name: str = None, **kwargs) → File

Create NVT (constant volume, temperature) simulation input file.

Generates Amber input file for NVT ensemble molecular dynamics simulation with Langevin thermostat for temperature control.

Parameters:

• init_temp (float) – Simulation temperature in Kelvin. Defaults to 300.0.

• total_step (int) – Total number of MD steps. Defaults to 500000 (1 ns at 2 fs steps).

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• irest (int) – Restart flag (0=new simulation, 1=restart). Defaults to 1.

• ntx (int) – Coordinate/velocity reading option. Defaults to 5.

• file_name (str) – Output filename for input file. Defaults to “nvt.in”.

• **kwargs – Additional NVT simulation parameters.

Returns:

The created NVT input file.

Return type:

File

Note

Typically used for equilibration after heating or as a production simulation for constant volume systems.

create_npt_input(init_temp: float = 300.0, total_step: int = 50000000, step_length: float = 0.002, irest: int = 1, ntx: int = 5, taup: float = 2.0, file_name: str = None, **kwargs) → File

Create NPT (constant pressure, temperature) simulation input file.

Generates Amber input file for NPT ensemble molecular dynamics simulation with both temperature and pressure control for production simulations.

Parameters:

• init_temp (float) – Simulation temperature in Kelvin. Defaults to 300.0.

• total_step (int) – Total number of MD steps. Defaults to 50000000 (100 ns at 2 fs steps).

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• irest (int) – Restart flag (0=new simulation, 1=restart). Defaults to 1.

• ntx (int) – Coordinate/velocity reading option. Defaults to 5.

• taup (float) – Pressure relaxation time in picoseconds. Defaults to 2.0.

• file_name (str) – Output filename for input file. Defaults to “npt.in”.

• **kwargs – Additional NPT simulation parameters.

Returns:

The created NPT input file.

Return type:

File

Note

Typically used for production simulations at physiological conditions (1 atm pressure, 300 K temperature).

add_process(input_file: str | File, process_name: str = None, _type: str = None, process: MDProcess = None, **kwargs) → None

Add a molecular dynamics process to the simulation workflow.

Adds an MD simulation process (minimization, heating, equilibration, or production) to the execution queue with appropriate process type and parameters.

Parameters:

• input_file (str | File) – Path to the Amber input file for this process.

• process_name (str) – Descriptive name for this process step.

• _type (str) – Type of MD process (“minimize”, “nvt”, “npt”). Defaults to generic MDProcess.

• process (MDProcess) – Custom MDProcess subclass to use instead of auto-detected type.

• **kwargs – Additional parameters passed to the process constructor.

Note

Process type determines the appropriate MDProcess subclass: - “minimize”: MinimizeProcess - “nvt”: NVTProcess - “npt”: NPTProcess - default: generic MDProcess

add_minimize_process(maxcyc: int = 10000, ncyc: int = 5000, process_name: str = 'minimize', restraint: bool = False, restraint_mask: str = None, use_gpu: bool = False, cpu_num: int = None, **kwargs) → None

Add energy minimization process to workflow.

Creates a minimization input file and adds the corresponding process to the simulation workflow queue.

Parameters:

• maxcyc (int) – Maximum number of minimization cycles. Defaults to 10000.

• ncyc (int) – Number of steepest descent cycles. Defaults to 5000.

• process_name (str) – Name for this minimization step. Defaults to “minimize”.

• restraint (bool) – Whether to apply positional restraints. Defaults to False.

• restraint_mask (str) – Amber mask for restrained atoms if restraint=True.

• use_gpu (bool) – Whether to use GPU acceleration if available. Defaults to False.

• cpu_num (int) – Number of CPU cores to use if not using GPU. Defaults to half of available CPUs.

• **kwargs – Additional minimization parameters.

Note

Automatically creates input file and adds MinimizeProcess to workflow.

add_nvt_process(total_step: int = 500000, step_length: float = 0.002, process_name: str = 'nvt', is_production: bool = False, **kwargs) → None

Add NVT simulation process to workflow.

Creates an NVT input file and adds the corresponding process to the simulation workflow queue.

Parameters:

• total_step (int) – Total number of MD steps. Defaults to 500000 (1 ns).

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• process_name (str) – Name for this NVT step. Defaults to “nvt”.

• is_production (bool) – Whether this is a production simulation. Defaults to False.

• **kwargs – Additional NVT simulation parameters.

Note

Automatically creates input file and adds NVTProcess to workflow.

add_heat_process(target_temp: float = 300.0, heat_step: int = 9000, total_step: int = 10000, step_length: float = 0.002, process_name: str = 'heat', **kwargs) → None

Add system heating process to workflow.

Creates a heating input file and adds the corresponding process to the simulation workflow queue.

Parameters:

• target_temp (float) – Target temperature in Kelvin. Defaults to 300.0.

• heat_step (int) – Number of steps for temperature ramping. Defaults to 9000.

• total_step (int) – Total simulation steps. Defaults to 10000.

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• process_name (str) – Name for this heating step. Defaults to “heat”.

• **kwargs – Additional heating parameters.

Note

Automatically creates input file and adds MDProcess to workflow.

add_npt_process(total_step: int = 50000000, step_length: float = 0.002, process_name: str = 'npt', is_production: bool = False, **kwargs) → None

Add NPT simulation process to workflow.

Creates an NPT input file and adds the corresponding process to the simulation workflow queue.

Parameters:

• total_step (int) – Total number of MD steps. Defaults to 50000000 (100 ns).

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• process_name (str) – Name for this NPT step. Defaults to “npt”.

• is_production (bool) – Whether this is a production simulation. Defaults to False.

• **kwargs – Additional NPT simulation parameters.

Note

Automatically creates input file and adds NPTProcess to workflow.

class pyCADD.Dynamic.common.Simulator(processor: Processor)

Bases: object

GPU-accelerated molecular dynamics simulation executor.

Manages the execution of MD simulation workflows on GPU hardware using AMBER’s pmemd.cuda engine. Handles GPU device selection and process execution coordination.

processor

Associated Processor instance containing the workflow.

comsolvate_topfile

System topology file for simulation.

comsolvate_crdfile

System coordinate file for simulation.

md_process_list

List of MD processes to execute.

cuda_device

GPU device ID to use for calculations.

__init__(processor: Processor) → None

Initialize Simulator with a configured Processor.

Parameters:

processor (Processor) – Processor instance with prepared system files and process workflow.

Note

Automatically inherits system files and process list from the provided processor instance.

show_cuda_device() → None

Display available GPU devices using nvidia-smi.

Prints GPU information including memory usage, temperature, and process information for device selection.

set_cuda_device(cuda_device: int) → None

Set the GPU device for CUDA calculations.

Parameters:

cuda_device (int) – GPU device ID to use (0, 1, 2, etc.).

Note

Sets the CUDA_VISIBLE_DEVICES environment variable to restrict CUDA operations to the specified device.

run_simulation(cuda_device: int = None) → None

Execute the complete MD simulation workflow on GPU.

Runs all MD processes in the workflow using AMBER’s pmemd.cuda engine with automatic file management and error checking.

Parameters:

cuda_device (int | None) – Optional GPU device ID to use. If provided, overrides the current device setting.

Raises:

RuntimeError – If no MD processes have been added to workflow or if pmemd.cuda is not available.

Note

Results are automatically saved in the md_result/ subdirectory with appropriate naming conventions for each process step.

class pyCADD.Dynamic.common.Analyzer(traj_file: str | File, comsolvated_topfile: str | File, com_topfile: str | File = None, receptor_topfile: str | File = None, ligand_topfile: str | File = None, mdout_file: str | File = None, save_dir: str = None)

Bases: object

Molecular dynamics trajectory analysis interface.

Provides comprehensive analysis capabilities for MD simulation trajectories including RMSD, RMSF, hydrogen bond analysis, and energy extraction using pytraj and custom analysis functions.

traj_file_path

Path to the MD trajectory file.

traj_file

File object for trajectory.

traj

Loaded trajectory object for analysis.

top_file_path

Path to the topology file.

top_file

File object for topology.

__init__(traj_file: str | File, comsolvated_topfile: str | File, com_topfile: str | File = None, receptor_topfile: str | File = None, ligand_topfile: str | File = None, mdout_file: str | File = None, save_dir: str = None) → None

Initialize trajectory analyzer with file paths.

Parameters:

• traj_file (str | File) – Path to MD trajectory file (.nc, .mdcrd, etc.).

• comsolvated_topfile (str | File) – Path to solvated system topology file.

• com_topfile (str | File) – Path to complex (protein-ligand) topology file.

• receptor_topfile (str | File) – Path to receptor-only topology file.

• ligand_topfile (str | File) – Path to ligand-only topology file.

• mdout_file (str | File) – Path to MD output file for energy extraction.

• save_dir (str) – Directory for saving analysis results.

Note

Multiple topology files support different analysis types (complex, apo, ligand-only). Trajectory and topology files are loaded on-demand when analysis methods are called.

load_traj(traj_file: str | File, top_file: str | File) → None

Load trajectory and topology files for analysis.

Parameters:

• traj_file (str | File) – Path to the MD trajectory file.

• top_file (str | File) – Path to the corresponding topology file.

Note

Uses pytraj to load trajectory for efficient analysis operations. Prints trajectory information including frame count and atom count.

load_mdout(mdout_file: str | File) → None

Load MD output file for energy analysis.

Parameters:

mdout_file (str | File) – Path to the Amber MD output file containing energy information from the simulation.

load_topfile(comsolvated_topfile: str | File = None, com_topfile: str | File = None, receptor_topfile: str | File = None, ligand_topfile: str | File = None) → None

Load topology files for different system components.

Parameters:

• comsolvated_topfile (str | File) – Path to solvated complex topology.

• com_topfile (str | File) – Path to complex (protein-ligand) topology.

• receptor_topfile (str | File) – Path to receptor-only topology.

• ligand_topfile (str | File) – Path to ligand-only topology.

Note

Multiple topology files enable component-specific analysis (e.g., protein-only RMSD, ligand-only RMSF). Sets apo flag based on ligand topology availability.

calc_rmsd(mask: str = '@CA', ref: int = 0, **kwargs) → None

Calculate Root Mean Square Deviation (RMSD) over trajectory.

Computes RMSD values for selected atoms relative to a reference frame, providing insight into structural stability and conformational changes.

Parameters:

• mask (str) – Amber mask syntax for atom selection. Defaults to “@CA” (alpha carbons).

• ref (int) – Reference frame number for RMSD calculation. Defaults to 0 (first frame).

• **kwargs – Additional parameters passed to analysis function.

Note

Results are saved in rmsd/ subdirectory as CSV files and plots. Common masks: “@CA” (backbone), “:1-100” (residues), “!:WAT” (no water).

calc_rmsf(mask: str = '@CA', options: str = 'byres', **kwargs) → None

Calculate Root Mean Square Fluctuation (RMSF) per residue/atom.

Computes RMSF values to identify flexible regions and binding site dynamics in the protein structure.

Parameters:

• mask (str) – Amber mask syntax for atom selection. Defaults to “@CA”.

• options (str) – Analysis options (“byres” for per-residue, “byatom” for per-atom). Defaults to “byres”.

• **kwargs – Additional parameters passed to analysis function.

Note

Results are saved in rmsf/ subdirectory. “byres” option averages fluctuations over all atoms in each residue for cleaner plots.

calc_hbond(mask: str = ':*', distance: float = 3.0, angle: float = 135.0, options: str = None, **kwargs) → None

Calculate hydrogen bond analysis throughout trajectory.

Identifies and tracks hydrogen bonds based on geometric criteria, providing insights into protein-ligand and internal protein interactions.

Parameters:

• mask (str) – Amber mask syntax for donor/acceptor selection. Defaults to “:*” (all).

• distance (float) – Maximum donor-acceptor distance in Angstroms. Defaults to 3.0.

• angle (float) – Minimum donor-H-acceptor angle in degrees. Defaults to 135.0.

• options (str) – Additional options for hydrogen bond analysis.

• **kwargs – Additional parameters passed to analysis function.

Note

Results include hydrogen bond occupancy, distances, and angles saved in hbond/ subdirectory with detailed statistics.

trace_distance(mask: str, **kwargs) → None

Trace distance between two atom groups over trajectory.

Monitors the distance between specified atoms/groups to analyze binding interactions, conformational changes, or domain movements.

Parameters:

• mask (str) – Amber mask syntax specifying two atom groups (e.g., “:1@CA :100@CA”).

• **kwargs – Additional parameters passed to analysis function.

Note

Results saved in distance/ subdirectory with time series plots and statistical analysis of distance fluctuations.

trace_angle(mask: str, **kwargs) → None

Trace angle between three atom groups over trajectory.

Monitors angular measurements to analyze conformational changes, binding geometry, or secondary structure dynamics.

Parameters:

• mask (str) – Amber mask syntax specifying three atom groups for angle calculation (e.g., “:1@CA :2@CA :3@CA”).

• **kwargs – Additional parameters passed to analysis function.

Note

Results saved in angle/ subdirectory with time series plots showing angle evolution and distribution analysis.

extract_frame(frame: int, **kwargs) → None

Extract a single frame structure from trajectory.

Saves the specified frame as a separate structure file for detailed analysis or visualization.

Parameters:

• frame (int) – Frame number to extract (0-indexed).

• **kwargs – Additional parameters passed to extraction function.

Note

Frame structures saved in frame_structures/ subdirectory in PDB format for further analysis or visualization.

extract_frames(start: int, end: int, **kwargs) → None

Extract a range of frame structures from trajectory.

Saves multiple frames as separate structure files for ensemble analysis or representative structure selection.

Parameters:

• start (int) – Starting frame number (0-indexed, inclusive).

• end (int) – Ending frame number (0-indexed, inclusive).

• **kwargs – Additional parameters passed to extraction function.

Note

All frames in the specified range are saved in frame_structures/ subdirectory with sequential numbering.

extract_lowest_energy_st() → None

Extract structure frame with lowest total energy.

Analyzes the MD output file to identify the frame with minimum total energy and extracts it as a representative low-energy structure.

Raises:

ValueError – If MD output file hasn’t been loaded.

Note

Results include energy information and extracted structure saved in lowest_energy_structure/ subdirectory. Useful for identifying stable conformations or starting structures for further analysis.

create_energy_inputfile(start_frame: int, end_frame: int, job_type: Literal['free', 'entropy', 'decomp'], method: Literal['pb/gbsa', 'gbsa'] = None, step_size: int = 10) → None

Create input file for MM/PBSA or MM/GBSA energy calculations.

Generates input files for free energy analysis, entropy calculations, or energy decomposition using AMBER’s MMPBSA.py tool.

Parameters:

• start_frame (int) – First frame for energy analysis (1-indexed).

• end_frame (int) – Last frame for energy analysis (inclusive).

• job_type (str) – Type of energy calculation: - “free”: Free energy calculation (ΔG) - “entropy”: Entropy contribution calculation - “decomp”: Per-residue energy decomposition

• method (str) – Energy calculation method for “free” job type: - “pb/gbsa”: Both PB and GB calculations - “gbsa”: GB calculation only

• step_size (int) – Frame sampling interval. Defaults to 10.

Returns:

Created input file for MMPBSA.py calculations.

Return type:

File

Raises:

ValueError – If method is not specified for “free” job type or if invalid job_type/method is provided.

Note

Input files saved in energy_inputfile/ subdirectory with appropriate parameter sets for different calculation types.

run_energy_calc(energy_decompose: str = None, cpu_num: int = None, input_file: File = None) → None

Execute MM/PBSA or MM/GBSA energy calculations.

Runs AMBER’s MMPBSA.py tool to calculate binding free energies, entropy contributions, or per-residue energy decomposition.

Parameters:

• energy_decompose (str) – Optional decomposition specification.

• cpu_num (int) – Number of CPU cores to use. Defaults to system CPU_NUM.

• input_file (File) – Custom input file to use. Defaults to self.inputfile.

Raises:

ValueError – If required input file or topology files are missing.

Note

Requires all topology files (complex, receptor, ligand) and trajectory data to be loaded. Results saved in energy_results/ subdirectory with detailed energy breakdown and statistics.

pyCADD.Dynamic.constant module

pyCADD.Dynamic.core module

Core molecular dynamics simulation preparation and execution functions.

This module provides the main functionality for preparing molecular systems and running molecular dynamics simulations using Amber tools. It includes protein preparation, ligand parameterization, system building, and simulation execution.

pyCADD.Dynamic.core.protein_prepare(protein_file: File | str, save_dir: str = None, keep_water: bool = False, overwrite: bool = False) → File

Prepares protein structure for molecular dynamics simulation.

Processes a protein PDB file using pdb4amber to clean up the structure, add missing atoms, and prepare it for Amber force field parameterization. The preparation includes removing/adding atoms and fixing structural issues.

Parameters:

• protein_file (File | str) – Input protein PDB file to be processed.

• save_dir (str, optional) – Directory to save processed files. Defaults to current working directory.

• keep_water (bool, optional) – Whether to retain water molecules in final structure. Defaults to False.

• overwrite (bool, optional) – Whether to overwrite existing prepared files. Defaults to False.

Returns:

Processed protein file ready for MD simulation setup.

Return type:

File

Note

The preparation process involves multiple steps:

1. Remove water and add missing atoms (dry step). If keep_water=True, water molecules from original file are preserved.

2. Remove all hydrogens (noH step)

3. Final cleanup and preparation

Raises:

• FileNotFoundError – If the input protein file doesn’t exist.

• RuntimeError – If pdb4amber processing fails.

pyCADD.Dynamic.core.molecule_prepare(ligand_file: File, charge_method: Literal['resp', 'bcc', 'resp2'] = 'resp', charge: int = None, multiplicity: int = None, dft: str = 'B3LYP', basis_set: str = '6-31g*', cpu_num: int = 4, mem_use: str = '8GB', solvent: str = 'water', delta: float = 0.5, save_dir: str = None, overwrite: bool = False) → tuple[File, File]

Prepares small molecule/ligand for molecular dynamics simulation.

Generates Amber-compatible parameter and coordinate files for a small molecule by calculating partial charges using quantum mechanical methods (RESP, AM1-BCC, or RESP2) and creating force field parameters using GAFF.

Parameters:

• ligand_file (File) – Input ligand structure file (SDF, MOL2, PDB, etc.).

• charge_method (str, optional) – Method for charge calculation. Defaults to “resp”.

• charge (int, optional) – Net charge of the molecule. If None, will be determined automatically.

• multiplicity (int, optional) – Spin multiplicity. If None, will be determined automatically.

• dft (str, optional) – DFT functional for quantum calculations. Defaults to “B3LYP”.

• basis_set (str, optional) – Basis set for quantum calculations. Defaults to “6-31g*”.

• cpu_num (int, optional) – Number of CPUs for quantum calculations. Defaults to 4.

• mem_use (str, optional) – Memory allocation for quantum calculations. Defaults to “8GB”.

• solvent (str, optional) – Solvent for implicit solvation in quantum calculations. Defaults to “water”.

• delta (float, optional) – Interpolation parameter for RESP2 method. Defaults to 0.5.

• save_dir (str, optional) – Directory to save generated files. Defaults to current working directory.

• overwrite (bool, optional) – Whether to overwrite existing parameter files. Defaults to False.

Returns:

Tuple containing (parameter_file, coordinate_file) where:

• parameter_file: Amber parameter file (.prmtop)

• coordinate_file: Amber coordinate file (.inpcrd)

Return type:

tuple[File, File]

Raises:

• ValueError – If unsupported charge method is specified.

• RuntimeError – If antechamber or other Amber tools fail.

• FileNotFoundError – If input ligand file doesn’t exist.

Note

The function automatically handles:

• Charge and multiplicity determination if not provided

• GAFF parameter assignment using antechamber

• Missing parameter generation using parmchk2

• System building using tleap

pyCADD.Dynamic.core.leap_prepare(protein_file: File, ligand_file: File = None, frcmod_file: File = None, box_size: float = 10.0, box_type: str = 'TIP3PBOX', solvatebox: str = 'solvatebox', save_dir: str = None) → tuple[File, File, File, File, File, File | None]

Prepares solvated molecular system using tLEaP.

Builds a complete molecular dynamics system by combining protein, ligand (optional), solvent, and counter ions using Amber’s tLEaP program. Generates topology and coordinate files ready for MD simulation.

Parameters:

• protein_file (File) – Prepared protein structure file.

• ligand_file (File, optional) – Ligand MOL2 file with parameters. Defaults to None.

• frcmod_file (File, optional) – Additional force field parameter file. Defaults to None.

• box_size (float, optional) – Distance from solute to box boundary in Angstroms. Defaults to 10.0.

• box_type (str, optional) – Water model for solvation. Defaults to “TIP3PBOX”.

• solvatebox (str, optional) – Solvation command type. Defaults to “solvatebox”.

• save_dir (str, optional) – Directory to save output files. Defaults to current working directory.

Returns:

Tuple containing (topology_file, coordinate_file, pdb_file, com_topfile, pro_topfile, lig_topfile) where:

• topology_file: Amber parameter/topology file (.prmtop)

• coordinate_file: Amber coordinate file (.inpcrd)

• pdb_file: PDB file of the solvated system

• com_topfile: Combined system topology file (.prmtop)

• pro_topfile: Protein-only topology file (.prmtop)

• lig_topfile: Ligand-only topology file (.prmtop) or None if no ligand

Return type:

tuple

Raises:

• RuntimeError – If tLEaP execution fails.

• FileNotFoundError – If input files don’t exist.

Note

The function automatically:

• Generates appropriate file prefixes based on input files

• Creates tLEaP input script and executes it

• Converts coordinates to PDB format for visualization

• Handles both protein-only and protein-ligand systems

class pyCADD.Dynamic.core.BaseProcess(input_file: File, process_name: str, **kwargs)

Bases: object

Base class for molecular dynamics simulation processes.

Provides common functionality for parsing MD input files and managing simulation process parameters. This is an abstract base class that defines the interface for all MD simulation processes.

input_file

MD input file containing simulation parameters.

Type:

File

process_name

Name identifier for this simulation process.

Type:

str

cfg

Parsed configuration from the input file.

Type:

list

__init__(input_file: File, process_name: str, **kwargs) → None

Initializes the base MD process.

Parameters:

• input_file (File) – Amber MD input file with simulation parameters.

• process_name (str) – Unique name for this simulation process.

• **kwargs – Additional attributes to set on the process instance.

Note

The input file is automatically parsed to extract configuration sections and parameters. Additional keyword arguments are set as instance attributes for process customization.

run(**kwargs) → None

Executes the simulation process.

Parameters:

**kwargs – Process-specific arguments required for execution.

Raises:

NotImplementedError – This method must be implemented by subclasses.

Note

Subclasses must override this method to implement the specific execution logic for their simulation type.

class pyCADD.Dynamic.core.MDProcess(input_file: File, process_name: str, use_gpu: bool = True, cpu_num: int = None, **kwargs)

Bases: BaseProcess

Molecular dynamics simulation process implementation.

Handles execution of Amber MD simulations including minimization, heating, equilibration, and production runs. Automatically parses input parameters and manages file paths for simulation output.

control_cfg

Parsed &cntrl section from input file.

Type:

dict

is_minimize

Whether this is a minimization process.

Type:

bool

is_restrained

Whether restraints are applied.

Type:

bool

is_production

Whether this is a production run.

Type:

bool

total_step

Total number of simulation steps.

Type:

int

step_size

Time step size in picoseconds.

Type:

float

cmd

Command string for simulation execution.

Type:

str

topology_file

Topology file for the system.

Type:

File

inpcrd_file

Input coordinate file.

Type:

File

mdout_file_path

Path to simulation output file.

Type:

str

mdcrd_file_path

Path to trajectory coordinate file.

Type:

str

mdrst_file_path

Path to restart coordinate file.

Type:

str

__init__(input_file: File, process_name: str, use_gpu: bool = True, cpu_num: int = None, **kwargs) → None

Initializes the MD process with input parameters.

Parameters:

• input_file (File) – Amber MD input file with simulation parameters.

• process_name (str) – Unique name for this simulation process.

• use_gpu (bool, optional) – Whether to use GPU acceleration. Defaults to True.

• cpu_num (int, optional) – Number of CPU cores to use if not using GPU. Defaults to half of available CPUs.

• **kwargs – Additional attributes for process customization.

Note

Automatically determines simulation type (minimization vs dynamics) based on the ‘imin’ parameter in the input file. Step size and total steps are extracted from appropriate input parameters.

run(topology_file: File, inpcrd_file: File, reference_file: File | str = None, save_dir: str = None, nohup: bool = False) → MDProcess

Executes the molecular dynamics simulation.

Runs the MD simulation using either PMEMD (for dynamics) or SANDER (for minimization) with the specified topology and coordinate files. Handles output file management and progress tracking.

Parameters:

• topology_file (File) – Amber topology file (.prmtop) for the system.

• inpcrd_file (File) – Input coordinate file (.inpcrd or .rst).

• reference_file (File | str, optional) – Reference structure for restrained simulations. Defaults to None.

• save_dir (str, optional) – Directory to save simulation outputs. Defaults to current working directory.

• nohup (bool, optional) – Whether to run in background with progress tracking. Defaults to False.

Returns:

Self-reference with updated file paths and execution status.

Return type:

MDProcess

Note

The method automatically:

• Selects appropriate MD engine (PMEMD/SANDER) based on simulation type

• Generates output file paths based on process name

• Logs simulation parameters (steps, time step, total time)

• Provides real-time progress tracking for background runs

• Handles reference files for restrained simulations

Raises:

• RuntimeError – If the simulation execution fails.

• FileNotFoundError – If required input files don’t exist.

class pyCADD.Dynamic.core.MinimizeProcess(input_file: File, process_name: str, use_gpu: bool = False, cpu_num: int = None, **kwargs)

Bases: MDProcess

Energy minimization simulation process.

Specialized MD process for performing energy minimization using SANDER. Inherits all functionality from MDProcess but is specifically configured for minimization calculations.

Note

Minimization processes use SANDER engine and don’t generate trajectory files. The process automatically detects minimization mode from the input file’s ‘imin=1’ parameter.

__init__(input_file: File, process_name: str, use_gpu: bool = False, cpu_num: int = None, **kwargs) → None

Initializes the minimization process.

Parameters:

• input_file (File) – Amber minimization input file with imin=1.

• process_name (str) – Unique name for this minimization process.

• use_gpu (bool, optional) – Whether to use GPU acceleration. Defaults to False.

• cpu_num (int, optional) – Number of CPUs to use if not using GPU. Defaults to half of available CPUs.

• **kwargs – Additional attributes for process customization.

class pyCADD.Dynamic.core.NPTProcess(input_file: File, process_name: str, is_production: bool = False, **kwargs)

Bases: MDProcess

Isothermal-isobaric (NPT) molecular dynamics process.

Performs MD simulation in the NPT ensemble where temperature and pressure are held constant. Commonly used for equilibration and production phases to maintain realistic density and pressure conditions.

is_production

Whether this is a production run requiring background execution with progress tracking.

Type:

bool

__init__(input_file: File, process_name: str, is_production: bool = False, **kwargs) → None

Initializes the NPT simulation process.

Parameters:

• input_file (File) – Amber MD input file configured for NPT simulation.

• process_name (str) – Unique name for this NPT process.

• is_production (bool, optional) – Whether this is a production run. Production runs use background execution. Defaults to False.

• **kwargs – Additional attributes for process customization.

Note

NPT simulations require appropriate barostat and thermostat settings in the input file (ntp>0, ntt>0). Production runs automatically use nohup execution for long simulations.

class pyCADD.Dynamic.core.NVTProcess(input_file: File, process_name: str, is_production: bool = False, **kwargs)

Bases: MDProcess

Canonical (NVT) molecular dynamics process.

Performs MD simulation in the NVT ensemble where temperature and volume are held constant. Typically used for heating phases and some equilibration steps before switching to NPT conditions.

is_production

Whether this is a production run requiring background execution with progress tracking.

Type:

bool

__init__(input_file: File, process_name: str, is_production: bool = False, **kwargs) → None

Initializes the NVT simulation process.

Parameters:

• input_file (File) – Amber MD input file configured for NVT simulation.

• process_name (str) – Unique name for this NVT process.

• is_production (bool, optional) – Whether this is a production run. Production runs use background execution. Defaults to False.

• **kwargs – Additional attributes for process customization.

Note

NVT simulations require thermostat settings in the input file (ntt>0) but no barostat (ntp=0). Commonly used for gradual heating from 0 K to target temperature.

pyCADD.Dynamic.core.run_simulation(comsolvate_topfile: File, comsolvate_crdfile: File, process_list: list[MDProcess], save_dir: str = None) → MDProcess

Executes a series of molecular dynamics simulation processes.

Runs a complete MD simulation workflow by sequentially executing a list of simulation processes (minimization, heating, equilibration, production). Each process uses the output coordinates from the previous step as input.

Parameters:

• comsolvate_topfile (File) – Amber topology file for the solvated system.

• comsolvate_crdfile (File) – Initial coordinate file for the solvated system.

• process_list (list[MDProcess]) – List of MD processes to execute in order. Each process contains its own input parameters and settings.

• save_dir (str, optional) – Base directory to save all simulation outputs. Defaults to current working directory.

Note

The function automatically:

• Creates separate subdirectories for each simulation process

• Chains coordinates between processes (output → input)

• Handles restrained simulations with appropriate reference structures

• Uses nohup for production runs to allow background execution

• Provides progress tracking for long simulations

Returns:

The final completed simulation process in the workflow.

Return type:

MDProcess

Raises:

• RuntimeError – If any simulation process fails.

• FileNotFoundError – If input topology or coordinate files don’t exist.

pyCADD.Dynamic.core.create_energy_inputfile(job_type: str, startframe: int, endframe: int, step_size: int, decomp: bool = False, save_dir: str = None) → File

Creates MM-PBSA/MM-GBSA input file for binding energy calculations.

Generates an input file for Amber’s MM-PBSA or MM-GBSA calculations to analyze protein-ligand binding energies from MD trajectory data.

Parameters:

• job_type (str) – Type of energy calculation. Valid options: - “pb/gb”: Both Poisson-Boltzmann and Generalized Born calculations - “gb”: Generalized Born calculation only - “nmode”: Normal mode entropy calculation

• startframe (int) – Starting frame number from trajectory (1-indexed).

• endframe (int) – Ending frame number from trajectory (1-indexed).

• step_size (int) – Frame interval for analysis (e.g., 10 = every 10th frame).

• decomp (bool, optional) – Whether to perform per-residue energy decomposition. Defaults to False.

• save_dir (str, optional) – Directory to save the input file. Defaults to current working directory.

Returns:

Generated MM-PBSA/MM-GBSA input file.

Return type:

File

Raises:

ValueError – If an invalid job_type is specified.

Note

The function automatically configures appropriate calculation sections based on the job type. Energy decomposition provides detailed per-residue contributions but significantly increases computation time.

pyCADD.Dynamic.core.run_energy_calculation(input_file: File, comsolvate_topfile: File, com_topfile: File, receptor_topfile: File, ligand_topfile: File, traj_file: File, save_dir: str = None, energy_decompose: bool = False, cpu_num: int = None) → tuple[File, File]

Executes MM-PBSA/MM-GBSA binding energy calculations.

Performs comprehensive binding energy analysis using Amber’s MMPBSA.py.MPI program with parallel processing. Calculates binding free energies and optionally performs per-residue energy decomposition.

Parameters:

• input_file (File) – MM-PBSA input file with calculation parameters.

• comsolvate_topfile (File) – Topology file for the complete solvated system.

• com_topfile (File) – Topology file for the protein-ligand complex (no solvent).

• receptor_topfile (File) – Topology file for the receptor/protein only.

• ligand_topfile (File) – Topology file for the ligand only.

• traj_file (File) – MD trajectory file (.nc or .dcd format).

• save_dir (str, optional) – Directory to save calculation results. Defaults to current working directory.

• energy_decompose (bool, optional) – Whether per-residue decomposition was requested. Defaults to False.

• cpu_num (int, optional) – Number of CPU cores for parallel calculation. Defaults to system CPU_NUM constant.

Returns:

Tuple containing (energy_results, decomp_results):

• energy_results: CSV file with binding energy results

• decomp_results: CSV file with per-residue decomposition (if requested)

Return type:

tuple[File, File]

Raises:

• RuntimeError – If MPI is not available or calculation fails.

• FileNotFoundError – If required input files don’t exist.

Note

The calculation requires:

• MPI installation for parallel processing

• Proper trajectory format compatibility with topology files

• Sufficient memory for large trajectory analysis

• All topology files must be consistent with the trajectory

pyCADD.Dynamic.template module

Template classes for molecular dynamics input file generation.

This module provides template classes for generating various types of molecular dynamics input files including Amber MD input files, tLEaP scripts, and MM-GBSA analysis inputs. All templates use string formatting to replace placeholders with actual simulation parameters.

class pyCADD.Dynamic.template.BaseConstructor(state_dict: dict)

Bases: ABC

Abstract base class for all input file template constructors.

Provides common functionality for managing template parameters and generating formatted input files for molecular dynamics simulations and related tools.

_state_dict

Dictionary containing template parameters.

Type:

dict

_state_keys

List of parameter keys for state management.

Type:

list

__init__(state_dict: dict) → None

Initializes the base constructor with template parameters.

Parameters:

state_dict (dict) – Dictionary containing template parameters and values.

Note

All keys in state_dict are automatically set as instance attributes for convenient access in template formatting.

get_state_dict() → dict

Returns the current state of the constructor as a dictionary.

Returns:

Dictionary containing current values of all template parameters.

Return type:

dict

Note

Only returns parameters that were originally in the state_dict, not any additional attributes that may have been added later.

abstractmethod to_string() → str

Generates formatted template string with current parameters.

Returns:

Complete formatted template string ready for file output.

Return type:

str

Note

This method must be implemented by all subclasses to define how the template should be formatted with the current parameters.

to_str() → str

Alias for to_string() method.

Returns:

Same as to_string() - formatted template string.

Return type:

str

to_dict() → dict

Returns the current state as a dictionary.

Returns:

Dictionary containing current template parameter values.

Return type:

dict

Note

This is an alias for get_state_dict() method for convenience.

save(file_path: str) → str

Saves the formatted template to a file.

Parameters:

file_path (str) – Path where the template file should be saved.

Returns:

Path to the saved file.

Return type:

str

Note

The template is automatically formatted using to_string() before saving. Any existing file at the target path will be overwritten.

add_attr(**kwargs) → None

Adds or updates template attributes.

Parameters:

**kwargs – Attribute name-value pairs to add or update.

Note

Only attributes that were originally in the state dictionary can be updated. New attributes not in _state_keys are ignored.

get_attr(attr_name: str) → str

Get the value of the attribute.

set_attr(**kwargs) → None

Set the value of the attribute.

del_attr(attr_name: str) → None

Delete the attribute from the current state.

class pyCADD.Dynamic.template.LeapConstructor(state_dict: dict)

Bases: BaseConstructor

Template constructor for Amber tLEaP input files.

Generates tLEaP scripts for building molecular systems including proteins, ligands, solvent boxes, and counter ions. Supports both protein-only (apo) and protein-ligand systems.

Required state_dict keys:

force_field (list): List of force field names (e.g., [“protein.ff14SB”, “gaff2”]) protein_file_path (str): Path to prepared protein PDB file file_prefix (str): Prefix for output topology and coordinate files box_type (str): Type of solvent box (e.g., “TIP3PBOX”) box_size (float): Distance from solute to box edge in Angstroms add_ions_type (str): Type of neutralizing ions (e.g., “Na+”, “Cl-“)

Optional state_dict keys (for protein-ligand systems):

ligand_file_path (str): Path to ligand MOL2 file frcmod_file_path (str): Path to additional force field parameters

__init__(state_dict: dict) → None

Initializes the tLEaP template constructor.

Parameters:

state_dict (dict) – Dictionary containing template parameters. See class docstring for required and optional keys.

Note

Automatically sets pro_lig attribute for complex naming in templates. The template selection (apo vs protein-ligand) is determined by the presence of ligand_file_path in the state dictionary.

property base_template: str

Returns the appropriate base template for the system type.

Returns:

Base tLEaP template string for either apo (protein-only) or

protein-ligand systems based on the presence of ligand_file_path.

Return type:

str

to_string() → str

Generates the complete tLEaP input file content.

Returns:

Complete tLEaP script with force field loading commands

followed by the formatted base template.

Return type:

str

Note

The output combines force field loading commands with the system-specific template (apo or protein-ligand) formatted with the current state parameters.

class pyCADD.Dynamic.template.SimulationConstructor(state_dict: dict, type: Literal['cntrl', 'wt'], end_cfg: bool = True, title: str = None)

Bases: BaseConstructor

__init__(state_dict: dict, type: Literal['cntrl', 'wt'], end_cfg: bool = True, title: str = None) → None

Initialize a SimulationConstructor for MD simulation input files.

Creates a constructor for generating MD simulation input files used for energy minimization, heating, equilibration, and production simulations. Supports both control (&cntrl) and weight (&wt) namelist formats.

Parameters:

• state_dict (dict) – Dictionary containing simulation parameters and their values.

• type (str) – Type of simulation namelist (‘cntrl’ for standard MD parameters, ‘wt’ for weight parameters).

• end_cfg (bool) – Whether to add “END” string at the end of input file. Defaults to True.

• title (str) – Optional title string for the simulation stage. Defaults to None.

Note

The constructor supports two main Amber MD input formats:

• &cntrl: Standard MD control parameters (imin, nstlim, dt, etc.)

• &wt: Weight parameters for restraints and temperature ramping

to_string() → str

Generate formatted MD simulation input file content.

Creates a properly formatted Amber MD input file with namelist syntax, including optional title, parameter assignments, and termination strings.

Returns:

Formatted MD input file content with:

• Optional title line

• Namelist declaration (&cntrl or &wt)

• Parameter assignments (key=value format)

• Namelist termination (/)

• Optional END statement

Return type:

str

Note

Output format follows Amber MD input conventions: ` [title] &namelist_type param1=value1, param2=value2, ... / [END] `

class pyCADD.Dynamic.template.AnalysisConstructor(state_dict: dict, type: Literal['general', 'gb', 'pb', 'decomp', 'nmode'], title: str = None)

Bases: BaseConstructor

Constructor for MD trajectory analysis input files.

Generates input files for various types of MD trajectory analysis including general analysis, GB/PB calculations, decomposition analysis, and normal mode analysis using Amber analysis tools.

_type

Type of analysis to perform.

title

Optional title for the analysis.

__init__(state_dict: dict, type: Literal['general', 'gb', 'pb', 'decomp', 'nmode'], title: str = None) → None

Initialize an AnalysisConstructor for MD trajectory analysis.

Creates a constructor for generating analysis input files used with Amber trajectory analysis tools like cpptraj, MMPBSA, and nmode.

Parameters:

• state_dict (dict) – Dictionary containing analysis parameters and their values.

• type (str) – Type of analysis to perform: - ‘general’: General trajectory analysis (RMSD, RMSF, etc.) - ‘gb’: Generalized Born solvation analysis - ‘pb’: Poisson-Boltzmann solvation analysis - ‘decomp’: Energy decomposition analysis - ‘nmode’: Normal mode analysis

• title (str) – Optional title string for the analysis job. Defaults to None.

Note

Different analysis types require specific parameter sets and are processed by different Amber analysis programs.

to_string() → str

Generate formatted analysis input file content.

Creates a properly formatted Amber analysis input file with comment headers, namelist syntax, and parameter assignments for trajectory analysis tools.

Returns:

Formatted analysis input file content with:

• Optional comment title line (# title)

• Namelist declaration (&analysis_type)

• Parameter assignments with leading space

• Namelist termination (/)

Return type:

str

Note

Output format follows Amber analysis tool conventions: ``` # [title] &analysis_type

param1=value1, param2=value2,

… / ```

class pyCADD.Dynamic.template.MultiConstructorManager(constructor_list: list = None)

Bases: object

Manager for handling multiple template constructors.

Provides a unified interface for managing multiple BaseConstructor instances, allowing batch operations, state aggregation, and combined output generation for complex MD workflows requiring multiple input files.

constructor_list

List of BaseConstructor instances managed by this manager.

__init__(constructor_list: list = None) → None

Initialize a MultiConstructorManager.

Parameters:

constructor_list (list) – Optional list of BaseConstructor instances to manage. Defaults to empty list if None.

is_empty() → bool

Check if the manager contains any constructors.

Returns:

True if constructor list is empty, False otherwise.

Return type:

bool

add_constructor(constructor: BaseConstructor) → None

Add a constructor to the management list.

Parameters:

constructor (BaseConstructor) – BaseConstructor instance to add to the manager.

del_constructor(constructor: BaseConstructor) → None

Remove a constructor from the management list.

Parameters:

constructor (BaseConstructor) – BaseConstructor instance to remove from the manager.

Raises:

ValueError – If constructor is not found in the list.

to_string() → str

Generate combined string output from all managed constructors.

Concatenates the string output from all constructors in the management list, maintaining the order they were added.

Returns:

Combined string output from all managed constructors.

Empty string if no constructors present.

Return type:

str

save(file_path: str) → str

Save combined constructor output to file.

Writes the concatenated string output from all managed constructors to the specified file path.

Parameters:

file_path (str) – Path where the combined output should be saved.

Returns:

Path to the saved file.

Return type:

str

Note

Uses the write_file utility function for file operations.

class pyCADD.Dynamic.template.LeapInput(protein_file_path: str | File, ligand_file_path: str | File = None, frcmod_file_path: str | File = None, file_prefix: str = None, box_size: float = 10.0, box_type: str = 'TIP3PBOX', solvatebox: str = 'solvatebox', add_ions_type: str = 'Na+', **kwargs)

Bases: LeapConstructor

tLEaP input file constructor for system preparation.

Specialized constructor for generating tLEaP scripts that prepare MD systems including protein structures, ligands, solvation, and ion neutralization. Extends LeapConstructor with convenient parameter management for common MD system setup tasks.

__init__(protein_file_path: str | File, ligand_file_path: str | File = None, frcmod_file_path: str | File = None, file_prefix: str = None, box_size: float = 10.0, box_type: str = 'TIP3PBOX', solvatebox: str = 'solvatebox', add_ions_type: str = 'Na+', **kwargs) → None

Initialize a LeapInput constructor for tLEaP system preparation.

Creates a tLEaP input constructor with default force fields and customizable system parameters for protein-ligand MD simulations.

Parameters:

• protein_file_path (str | File) – Path to protein structure file (PDB format).

• ligand_file_path (str | File) – Optional path to ligand structure file. Defaults to None for apo simulations.

• frcmod_file_path (str | File) – Optional path to custom force field modification file. Defaults to None.

• file_prefix (str) – Prefix for generated output files. Defaults to “Untitled” if None.

• box_size (float) – Size of solvation box in Angstroms. Defaults to 10.0.

• box_type (str) – Type of water box (TIP3PBOX, TIP4PBOX, etc.). Defaults to “TIP3PBOX”.

• solvatebox (str) – Solvation command type. Defaults to “solvatebox”.

• add_ions_type (str) – Type of ions for neutralization. Defaults to “Na+”.

• **kwargs – Additional parameters to override default values.

Note

Default force field combination includes: - protein.ff14SB: Amber protein force field - gaff2: General Amber force field for small molecules - water.tip3p: TIP3P water model

class pyCADD.Dynamic.template.MinimizeInput(title: str = None, **kwargs)

Bases: SimulationConstructor

Constructor for energy minimization input files.

Generates Amber input files for energy minimization simulations using steepest descent and conjugate gradient algorithms to relax molecular structures before MD simulations.

__init__(title: str = None, **kwargs) → None

Initialize a MinimizeInput constructor.

Creates an energy minimization input with default parameters optimized for typical protein-ligand systems.

Parameters:

• title (str) – Optional title for the minimization job. Defaults to “Minimization”.

• **kwargs – Additional parameters to override defaults.

Note

Default minimization parameters:

• imin=1: Energy minimization flag

• cut=8.0: Nonbonded cutoff distance (Å)

• ntpr=10: Print frequency

• ntb=1: Constant volume periodic boundaries

• ntr=0: No positional restraints

• ntc=1: No SHAKE constraints

• maxcyc=10000: Maximum minimization cycles

• ncyc=5000: Steepest descent cycles before conjugate gradient

class pyCADD.Dynamic.template.RestrainedMinimizeInput(restraintmask: str, restraint_wt=2.0, title: str = None, **kwargs)

Bases: SimulationConstructor

Constructor for restrained energy minimization input files.

Generates Amber input files for energy minimization with positional restraints on specified atoms, typically used to minimize solvent and ions while keeping protein structure fixed.

__init__(restraintmask: str, restraint_wt=2.0, title: str = None, **kwargs) → None

Initialize a RestrainedMinimizeInput constructor.

Creates a restrained energy minimization input with specified atom restraints and force constants.

Parameters:

• restraintmask (str) – Amber mask syntax specifying atoms to restrain (e.g., “:1-100@CA,C,N,O” for protein backbone).

• restraint_wt (float) – Force constant for positional restraints in kcal/mol/Ų. Defaults to 2.0.

• title (str) – Optional title for the minimization job. Defaults to “Restrained Minimization”.

• **kwargs – Additional parameters to override defaults.

Note

Builds on standard minimization with:

• ntr=1: Enable positional restraints

• restraintmask: Atom selection for restraints

• restraint_wt: Restraint force constant

class pyCADD.Dynamic.template.NVTInput(end_cfg: bool = True, title: str = None, **kwargs)

Bases: SimulationConstructor

Constructor for NVT (constant volume, temperature) MD simulation input files.

Generates Amber input files for NVT ensemble molecular dynamics simulations with temperature control via Langevin dynamics, typically used for equilibration after minimization or heating phases.

__init__(end_cfg: bool = True, title: str = None, **kwargs) → None

Initialize an NVTInput constructor.

Creates an NVT simulation input with default parameters for temperature equilibration at 300 K using Langevin thermostat.

Parameters:

• end_cfg (bool) – Whether to add “END” string at end of input file. Defaults to True.

• title (str) – Optional title for the simulation. Defaults to “NVT Simulation”.

• **kwargs – Additional parameters to override defaults.

Note

Default NVT parameters:

• imin=0: MD simulation flag

• ntx=5: Read coordinates and velocities

• irest=1: Restart simulation

• temp0=300: Target temperature (K)

• ntt=3: Langevin thermostat

• gamma_ln=2.0: Collision frequency (ps⁻¹)

• ntp=0: No pressure control

• ntb=1: Constant volume periodic boundaries

• ntc=2: SHAKE constraints on H-bonds

• ntf=2: Omit forces for constrained bonds

• nstlim=500000: Simulation steps (1 ns at dt=0.002 ps)

class pyCADD.Dynamic.template.HeatInput(target_temp: float = 300.0, heat_step: int = 9000, total_step: int = 10000, step_length: float = 0.002, restraint_wt: float = None, restraintmask: str = None)

Bases: object

Constructor for system heating MD simulation with temperature ramping.

Manages gradual temperature increase from 0 K to target temperature using Amber weight (&wt) namelist for controlled heating phases. Combines NVT simulation parameters with temperature ramping schedules.

HEAT_TEMPLATE

Default weight parameters for temperature ramping.

stage_1_dict

Weight parameters for heating phase.

stage_2_dict

Weight parameters for temperature maintenance phase.

manager

MultiConstructorManager for combining simulation components.

HEAT_TEMPLATE = {'ISTEP1': 0, 'ISTEP2': 9000, 'TYPE': "'TEMP0'", 'VALUE1': 0.0, 'VALUE2': 300.0}

__init__(target_temp: float = 300.0, heat_step: int = 9000, total_step: int = 10000, step_length: float = 0.002, restraint_wt: float = None, restraintmask: str = None) → None

Initialize a HeatInput constructor for controlled heating.

Creates a heating protocol with linear temperature ramping followed by temperature maintenance using Amber weight parameters.

Parameters:

• target_temp (float) – Target temperature for heating in Kelvin. Defaults to 300.0.

• heat_step (int) – Number of steps for temperature ramping phase. Must be less than total_step. Defaults to 9000.

• total_step (int) – Total simulation steps for entire heating protocol. Defaults to 10000.

• step_length (float) – Time step length in picoseconds. Defaults to 0.002.

• restraint_wt (float) – Optional restraint force constant in kcal/mol/Ų. Defaults to None.

• restraintmask (str) – Optional Amber mask for restrained atoms. Defaults to None.

Note

Creates two-stage heating protocol:

1. Ramping: 0 K → target_temp over heat_step steps

2. Maintenance: target_temp held for remaining steps

get_state_dict() → dict

Get current state dictionary.

Returns:

Current state parameters for the heating protocol.

Return type:

dict

add_nvt(**kwargs) → None

Add NVT simulation component to heating protocol.

Creates and adds an NVT simulation constructor configured for heating with appropriate initial conditions and output frequencies.

Parameters:

**kwargs – Additional parameters to override NVT defaults.

Note

Configures NVT for heating with:

• irest=0, ntx=1: Cold start from coordinates only

• tempi=0.0: Initial temperature 0 K

• Custom output frequencies for heating monitoring

add_heat(stage_dict: dict = None) → None

Add temperature ramping weight parameters to heating protocol.

Adds weight (&wt) namelist sections for controlling temperature ramping during the heating simulation.

Parameters:

stage_dict (dict) – Optional custom weight parameters dictionary. If None, uses default two-stage heating protocol.

Note

Default protocol adds:

1. Stage 1: Linear ramp from 0 K to target temperature

2. Stage 2: Hold at target temperature

3. END directive to terminate weight section

to_string() → str

Generate complete heating input file content.

Executes default workflow if needed, then returns formatted input file content for Amber heating simulation.

Returns:

Complete Amber input file with NVT and weight sections.

Return type:

str

save(file_path: str) → None

Save heating input file to disk.

Executes default workflow if needed, then saves complete input file content to the specified path.

Parameters:

file_path (str) – Path where the heating input file should be saved.

class pyCADD.Dynamic.template.NPTInput(end_cfg: bool = True, title: str = None, **kwargs)

Bases: SimulationConstructor

Constructor for NPT (constant pressure, temperature) MD simulation input files.

Generates Amber input files for NPT ensemble molecular dynamics simulations with both temperature and pressure control, typically used for production simulations and system equilibration at physiological conditions.

__init__(end_cfg: bool = True, title: str = None, **kwargs) → None

Initialize an NPTInput constructor.

Creates an NPT simulation input with default parameters for production MD simulations at 300 K and 1 atm using Langevin thermostat and Berendsen barostat.

Parameters:

• end_cfg (bool) – Whether to add “END” string at end of input file. Defaults to True.

• title (str) – Optional title for the simulation. Defaults to “NPT Simulation”.

• **kwargs – Additional parameters to override defaults.

Note

Default NPT parameters:

• imin=0: MD simulation flag

• ntx=5: Read coordinates and velocities

• irest=1: Restart simulation

• temp0=300: Target temperature (K)

• ntt=3: Langevin thermostat

• ntp=1: Isotropic pressure scaling

• taup=2.0: Pressure relaxation time (ps)

• ntb=2: Constant pressure periodic boundaries

• nstlim=50000000: Long production simulation (100 ns)

class pyCADD.Dynamic.template.MMGBSAInput(start_frame: int, end_frame: int, step_size: int = 1)

Bases: object

Constructor for MM/GBSA (MM/PBSA) analysis input files.

Generates input files for Molecular Mechanics/Generalized Born Surface Area or Poisson-Boltzmann Surface Area free energy calculations using AMBER’s MMPBSA.py tool. Supports various analysis methods including GB, PB, decomposition, and normal mode analysis.

general_dict

General analysis parameters.

manager

MultiConstructorManager for combining analysis components.

__init__(start_frame: int, end_frame: int, step_size: int = 1) → None

Initialize an MMGBSAInput constructor.

Sets up MM/GBSA analysis with frame range specification and default general parameters for trajectory processing.

Parameters:

• start_frame (int) – First trajectory frame to analyze (1-indexed).

• end_frame (int) – Last trajectory frame to analyze (inclusive).

• step_size (int) – Frame interval for analysis sampling. Defaults to 1 (analyze every frame).

Note

Frame numbering follows AMBER convention (1-indexed). Analysis will process frames: start_frame, start_frame+step_size, …, up to end_frame.

add_general(title: str = None, **kwargs) → None

Add general analysis parameters section.

Adds the &general namelist with trajectory processing parameters, file handling options, and output control settings.

Parameters:

• title (str) – Optional title comment for the analysis.

• **kwargs – Additional general parameters to override defaults.

Note

Common parameters include verbose, keep_files, netcdf for controlling output detail and file management.

add_gb(**kwargs) → None

Add Generalized Born analysis parameters section.

Adds the &gb namelist for MM/GBSA calculations using implicit solvent models based on Generalized Born theory.

Parameters:

**kwargs – GB parameters to override defaults.

Note

Default GB model (igb=5) with physiological salt concentration (saltcon=0.15 M). Other igb values: 1, 2, 5, 7, 8 for different GB models (Hawkins, Onufriev, etc.).

add_pb(**kwargs) → None

Add Poisson-Boltzmann analysis parameters section.

Adds the &pb namelist for MM/PBSA calculations using explicit solution of the Poisson-Boltzmann equation for electrostatics.

Parameters:

**kwargs – PB parameters to override defaults.

Note

Default parameters include ionic strength (istrng=0.15) and grid fill ratio (fillration=4.0) for finite difference Poisson-Boltzmann solver.

add_decomp(**kwargs) → None

Add energy decomposition analysis parameters section.

Adds the &decomp namelist for per-residue energy decomposition analysis to identify key binding site residues and interactions.

Parameters:

**kwargs – Decomposition parameters to override defaults.

Note

Default enables residue-based decomposition (idecomp=1) with verbose output (dec_verbose=1) for detailed interaction analysis.

add_nmode(**kwargs) → None

Add normal mode analysis parameters section.

Adds the &nmode namelist for calculating conformational entropy contributions using normal mode analysis of energy-minimized structures.

Parameters:

**kwargs – Normal mode parameters to override defaults.

Note

Default parameters include convergence criteria (maxcyc=10000, drms=0.001) for minimization prior to normal mode calculation. Computationally expensive - use sparingly.

to_string() → str

Generate complete MM/GBSA input file content.

Returns:

Formatted MMPBSA.py input file with all added analysis sections.

Return type:

str

save(file_path: str) → None

Save MM/GBSA input file to disk.

Parameters:

file_path (str) – Path where the MMPBSA.py input file should be saved.

pyCADD.Dynamic.utils module

Utility functions for molecular dynamics simulation preparation and monitoring.

This module provides helper functions for charge calculation, parameter generation, simulation progress tracking, and system analysis utilities used throughout the molecular dynamics workflow.

pyCADD.Dynamic.utils.calc_am1bcc(structure_file: str | File, charge: int, multiplicity: int = 1, force_field: str = 'gaff2', save_dir: str = None) → File

Calculates AM1-BCC partial charges for a small molecule.

Uses antechamber to calculate AM1-BCC charges and assigns GAFF2 atom types to a small molecule structure. This is a faster alternative to quantum mechanical charge calculation methods.

Parameters:

• structure_file (str | File) – Input molecular structure file (SDF, MOL2, PDB, etc.).

• charge (int) – Net charge of the molecule.

• multiplicity (int, optional) – Spin multiplicity of the molecule. Defaults to 1.

• force_field (str, optional) – Force field to assign atom types. Defaults to “gaff2”.

• save_dir (str, optional) – Directory to save the output MOL2 file. Defaults to current working directory.

Returns:

MOL2 file with AM1-BCC charges and GAFF2 atom types.

Return type:

File

Raises:

• FileNotFoundError – If antechamber calculation fails or output file not generated.

• RuntimeError – If antechamber execution fails.

Note

AM1-BCC charges are semi-empirical and faster than ab initio methods but may be less accurate than RESP charges for some applications. The output file is named “{input_prefix}_bcc.mol2”.

pyCADD.Dynamic.utils.run_parmchk2(mol2_file_path: str | File, save_dir: str = None) → File

Generates missing force field parameters using parmchk2.

Runs Amber’s parmchk2 program to identify and generate missing force field parameters for a molecule based on its MOL2 file with assigned atom types. Creates a frcmod file containing additional parameters not found in the standard GAFF force field.

Parameters:

• mol2_file_path (str | File) – File or Path to MOL2 file with assigned atom types (from antechamber).

• save_dir (str, optional) – Directory to save the frcmod parameter file. Defaults to current working directory.

Returns:

Generated frcmod file containing missing force field parameters.

Return type:

File

Raises:

• RuntimeError – If parmchk2 execution fails.

• FileNotFoundError – If input MOL2 file doesn’t exist.

Note

The frcmod file contains additional parameters (bonds, angles, dihedrals) that are not available in the standard GAFF parameter set. This file is used together with GAFF in tLEaP to build complete molecular systems. Output file is named “{mol2_prefix}.frcmod”.

Module contents