Preprocess & I/O#

Engine-aware input discovery and trajectory normalization for PHENOMS.

This module converts replicate folders from GROMACS/OpenMM/AMBER layouts into normalized multi-frame protein-only PDBs consumable by SimulationSet.

class phenoms.preprocess.ReplicateInput(replicate_dir: 'Path', engine: 'str', trajectory_path: 'Path', topology_path: 'Path | None')[source]#

Bases: object

Parameters:

  • replicate_dir (Path)

  • engine (str)

  • trajectory_path (Path)

  • topology_path (Path | None)

replicate_dir: Path#
engine: str#
trajectory_path: Path#
topology_path: Path | None#
phenoms.preprocess.detect_replicate_input(replicate_dir)[source]#

Detect simulation engine and enforce required files for one replicate folder.

Required files:

  • gromacs: trajectory (.xtc/.trr) + topology (.tpr preferred, else .gro/.pdb). Reading .tpr requires the optional MDAnalysis dependency (pip install "phenoms[gromacs]"); without it, use a .gro/.pdb topology instead.

  • openmm: trajectory (.dcd/.xtc) + topology (.pdb/.prmtop)

  • amber: trajectory (.nc/.mdcrd) + topology (.prmtop/.parm7)

  • pdb: one multi-model .pdb trajectory (already normalized input)

Parameters:

replicate_dir (str | Path)

Return type:

ReplicateInput

phenoms.preprocess.discover_replicate_dirs(input_dir)[source]#

Directory policy: - if input_dir itself looks like one replicate, use it - otherwise treat each direct child directory as a replicate

Parameters:

input_dir (str | Path)

Return type:

list[Path]

phenoms.preprocess.normalize_replicate_to_pdb(replicate, out_pdb_path, *, frame_dt_ps=1000.0, start_ps=None, end_ps=None, apply_imaging=True, center=True, fit=True)[source]#

Normalize one replicate: image/unwrap (best-effort) -> center -> fit -> protein-only -> save PDB.

Parameters:
Return type:

Path

phenoms.preprocess.prepare_set_from_dir(input_dir, prepared_dir, *, frame_dt_ps=1000.0, start_ps=None, end_ps=None, apply_imaging=True, center=True, fit=True)[source]#

Prepare one set directory into normalized PDB replicates. Returns sorted list of prepared PDB paths.

Parameters:
Return type:

list[str]

I/O and trajectory loading for PHENOMS.

Supports multi-frame PDBs (simple path) and native MD formats (trajectory + topology).

phenoms.io.tpr_to_mdtraj_topology(tpr_path, traj_path)[source]#

Convert a GROMACS .tpr into a throwaway PDB that MDTraj can use as a topology.

Uses MDAnalysis’s pure-Python .tpr parser (no GROMACS binary required) to read atoms/bonds/resids. The trajectory is loaded alongside it purely so MDAnalysis has a coordinate set to write out (whether a bare .tpr carries usable coordinates on its own varies by MDAnalysis version); the actual frame data used for analysis always comes from traj_path via MDTraj afterward. Caller is responsible for deleting the returned path.

Return type:

Path

phenoms.io.load_trajectory(path, top=None, max_frames=None)[source]#

Load a trajectory from a PDB or from a native trajectory + topology pair.

Parameters:

  • path (str or path-like) – Trajectory file (.pdb, .xtc, .trr, .dcd, .nc, …).

  • top (str or path-like or None) – Topology for non-PDB trajectories (.pdb, .prmtop, .gro, .tpr, …). .tpr is converted on the fly via MDAnalysis (optional dependency). Ignored when path is already a multi-frame PDB with topology embedded.

  • max_frames (int or None) – If set, only the first max_frames frames are read from disk (via mdtraj.iterload) instead of loading the entire trajectory first. Pass the same value you intend to pass as sub_frames downstream to cut peak memory when a trajectory has far more frames than you need.

Return type:

mdtraj.Trajectory

phenoms.io.load_and_select_residues(path, resid_range=None, top=None, max_frames=None)[source]#

Load trajectory and optionally select a residue range.

If resid_range is None, select all protein atoms (whole protein).

Parameters:

  • path (str or path-like) – Trajectory / PDB path.

  • resid_range (tuple (int, int) or None) – (start, end) residue numbers (1-based). None = whole protein.

  • top (str or path-like or None) – Topology for native trajectory formats.

  • max_frames (int or None) – See load_trajectory().

Returns:

Loaded (and optionally sliced) trajectory.

Return type:

mdtraj.Trajectory

phenoms.io.normalize_topology_list(n_replicates, *, topology=None, topologies=None)[source]#

Resolve a single shared topology or per-replicate topologies.

Returns None when no topology is needed (PDB-only inputs).

Parameters:
Return type:

list | None