reforge package

Subpackages

Submodules

reforge.cli module

File: cli.py

Description:

This module provides a collection of command-line interface utilities for executing shell commands, submitting SLURM sbatch jobs, and running GROMACS operations from within a Python script. It includes generic functions for running commands and managing directories, as well as specialized wrappers for GROMACS commands (e.g., editconf, solvate, grompp, mdrun, and others) for molecular dynamics analysis.

Usage Example:
>>> from cli import run, sbatch, gmx, change_directory
>>> # Run a simple shell command
>>> run('ls', '-l')
>>>
>>> # Change directory temporarily
>>> with change_directory('/tmp'):
...     run('pwd')
>>>
>>> # Submit a job via SLURM
>>> sbatch('script.sh', 'arg1', 'arg2', t='01:00:00', mem='4G', N='1', c='4')
>>>
>>> # Execute a GROMACS command
>>> gmx('editconf', f='system.pdb', o='system_out.pdb')
Requirements:

  • Python 3.x

  • Standard libraries: os, subprocess, shutil, contextlib, functools

  • SLURM (for sbatch)

  • GROMACS (for GROMACS wrappers)

Author: DY Date: YYYY-MM-DD

reforge.cli.run(*args, **kwargs)[source]

Execute a shell command from within a Python script.

Parameters:

  • *args (str) – Positional arguments that compose the command to be executed.

  • **kwargs (dict) –

    Additional keyword arguments for command options. Special keys:

    • clinput (str, optional): Input string to be passed to the command’s standard input.

    • cltext (bool, optional): Whether the input should be treated as text (default True).

Return type:

None

reforge.cli.sbatch(script, *args, **kwargs)[source]

Submit a shell script as a SLURM sbatch job.

Parameters:

  • script (str) – The path to the shell script to be executed.

  • *args (str) – Additional positional arguments that are passed to the script.

  • **kwargs (dict) –

    Additional keyword options for the sbatch command. Special keys include:

    • clinput (str, optional): Input string for the command’s standard input.

    • cltext (bool, optional): Indicates if input should be treated as text (default True).

Example

>>> sbatch('script.sh', 'arg1', 'arg2', t='01:00:00', mem='4G', N='1', c='4')
Return type:

None

reforge.cli.dojob(submit, *args, **kwargs)[source]

Submit or run a job based on the ‘submit’ flag.

This function provides a simple interface to either submit a job to SLURM (using the ‘sbatch’ command) or to run it locally via bash. When submit is True, the function calls the sbatch function with the given arguments and keyword options, which handles setting SLURM parameters and submitting the job. When submit is False, the job is executed immediately using bash.

Parameters:

  • submit (bool) – If True, submit the job to SLURM using sbatch; if False, run the job locally via bash.

  • *args (tuple of str) – Positional arguments representing the script and any additional command-line arguments that should be passed to the job.

  • **kwargs (dict) – Keyword arguments for job configuration. These are passed to the sbatch function when submitting the job. They can include SLURM options (such as ‘t’ for time, ‘mem’ for memory, etc.) as well as any special keys recognized by sbatch (e.g., ‘clinput’ for standard input).

Examples

To submit a job to SLURM:

>>> dojob(True, 'script.sh', 'arg1', 'arg2', t='01:00:00', mem='4G', N='1', c='4')

To run the job locally via bash:

>>> dojob(False, 'script.sh', 'arg1', 'arg2')
Return type:

None

reforge.cli.gmx(command, gmx_callable='gmx_mpi', **kwargs)[source]

Execute a GROMACS command.

Parameters:

  • command (str) – The GROMACS command to execute (e.g., ‘editconf’, ‘solvate’).

  • gmx_callable (str, optional) – The GROMACS executable to use (default is ‘gmx_mpi’).

  • **kwargs (dict) –

    Additional options for the command. Special keys:

    • clinput (str, optional): Input to be passed to the command’s standard input.

    • cltext (bool, optional): Whether to treat the input as text (default True).

Return type:

None

reforge.cli.change_directory(new_dir)[source]

Temporarily change the working directory.

Parameters:

new_dir (str) – The directory path to change into.

Yields:

None – After executing the enclosed block, reverts to the original directory.

reforge.cli.from_wdir(func)[source]

Decorator to temporarily change the working directory before executing a function.

The first argument of the decorated function should be the target working directory.

Parameters:

func (callable) – The function to be decorated.

Returns:

The wrapped function that executes in the specified directory.

Return type:

callable

reforge.cli.gmx_editconf(**kwargs)[source]

Execute the GROMACS ‘editconf’ command to modify system configuration.

Parameters:

  • wdir (str) – The working directory where the command is executed.

  • **kwargs (dict) –

    Additional options for ‘editconf’. Defaults are:

    • f: ‘solute.pdb’ (input file)

    • o: ‘solute.pdb’ (output file)

    • bt: ‘triclinic’ (box type)

Return type:

None

reforge.cli.gmx_solvate(**kwargs)[source]

Execute the GROMACS ‘solvate’ command to add solvent to the system.

Parameters:

  • wdir (str) – The working directory where the command is executed.

  • **kwargs (dict) –

    Additional options for ‘solvate’. Defaults are:

    • cp: ‘solute.pdb’ (input configuration file)

    • cs: ‘water.gro’ (solvent structure file)

    • p: ‘system.top’ (topology file)

    • o: ‘system.pdb’ (output configuration file)

    • radius: ‘0.23’ (minimal solute-solvent distance)

Return type:

None

reforge.cli.gmx_make_ndx(clinput=None, **kwargs)[source]

Execute the GROMACS ‘make_ndx’ command to create an index file.

Parameters:

  • clinput (str, optional) – Input string for defining index groups.

  • **kwargs (dict) –

    Additional options for ‘make_ndx’. Defaults are:

    • f: ‘system.pdb’ (input configuration file)

    • o: ‘index.ndx’ (output index file)

Return type:

None

reforge.cli.gmx_grompp(**kwargs)[source]

Execute the GROMACS ‘grompp’ command to preprocess input files and generate a .tpr file.

Parameters:

**kwargs (dict) –

Additional options for ‘grompp’. Defaults are:

  • maxwarn: ‘1’

  • f: ‘../mdp/em.mdp’ (input parameter file)

  • c: ‘../system.pdb’ (input configuration file)

  • r: ‘../system.pdb’ (input structure for position restraints)

  • p: ‘../system.top’ (input topology file)

  • o: ‘em.tpr’ (output run file)

Return type:

None

reforge.cli.gmx_mdrun(**kwargs)[source]

Execute the GROMACS ‘mdrun’ command to perform molecular dynamics simulations or energy minimization.

Parameters:

**kwargs (dict) –

Additional options for ‘mdrun’. Defaults are:

  • ntomp: ‘8’

  • pin: ‘on’

  • pinstride: ‘1’

Return type:

None

reforge.cli.gmx_trjconv(clinput='1\n1\n', **kwargs)[source]

Execute the GROMACS ‘trjconv’ command to convert trajectory files.

Parameters:

  • clinput (str, optional) – Input string for trajectory frame selection (default ‘1n1n’).

  • **kwargs (dict) – Additional options for ‘trjconv’.

Return type:

None

reforge.cli.gmx_rmsf(clinput=None, **kwargs)[source]

Execute the GROMACS ‘rmsf’ command to compute root mean square fluctuations (RMSF).

Parameters:

  • wdir (str) – The working directory where the command is executed.

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) –

    Additional options for ‘rmsf’. Defaults are:

    • s: ‘md.tpr’ (input run file)

    • f: ‘mdc.xtc’ (trajectory file)

    • o: ‘rms_analysis/rmsf.xvg’ (output file)

    • b: ‘0’ (start time)

    • xvg: ‘none’ (output format)

    • res: ‘yes’ (calculate per-residue RMSF)

Return type:

None

reforge.cli.gmx_rms(clinput=None, **kwargs)[source]

Execute the GROMACS ‘rms’ command to compute root mean square deviation (RMSD).

Parameters:

  • wdir (str) – The working directory where the command is executed.

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) –

    Additional options for ‘rms’. Defaults are:

    • s: ‘md.tpr’ (input run file)

    • f: ‘mdc.xtc’ (trajectory file)

    • o: ‘rms_analysis/rmsd.xvg’ (output file)

    • b: ‘0’ (start time)

    • xvg: ‘none’ (output format)

    • fit: ‘rot+trans’ (fitting method)

Return type:

None

reforge.cli.gmx_rdf(clinput=None, **kwargs)[source]

Execute the GROMACS ‘rdf’ command to compute radial distribution functions (RDF).

Parameters:

  • wdir (str) – The working directory where the command is executed.

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) –

    Additional options for ‘rdf’. Defaults are:

    • s: ‘md.tpr’ (input run file)

    • f: ‘mdc.xtc’ (trajectory file)

    • o: ‘rms_analysis/rdf.xvg’ (output file)

    • b: ‘0’ (start time)

    • xvg: ‘none’ (output format)

Return type:

None

reforge.cli.gmx_cluster(clinput=None, **kwargs)[source]

Execute the GROMACS ‘cluster’ command to perform clustering analysis.

Parameters:

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) – Additional options for ‘cluster’.

Return type:

None

reforge.cli.gmx_extract_cluster(clinput=None, **kwargs)[source]

Execute the GROMACS ‘extract-cluster’ command to extract clustered structures.

Parameters:

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) – Additional options for ‘extract-cluster’.

Return type:

None

reforge.cli.gmx_covar(clinput=None, **kwargs)[source]

Execute the GROMACS ‘covar’ command to compute the covariance matrix and normal modes.

Parameters:

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) – Additional options for ‘covar’.

Return type:

None

reforge.cli.gmx_anaeig(clinput=None, **kwargs)[source]

Execute the GROMACS ‘anaeig’ command to analyze eigenvalues and eigenvectors.

Parameters:

  • clinput (str, optional) – Input string for defining groups.

  • **kwargs (dict) –

    Additional options for ‘anaeig’. Defaults include:

    • v: ‘eigenvec.trr’ (eigenvector file)

Return type:

None

reforge.cli.gmx_make_edi(clinput=None, **kwargs)[source]

Execute the GROMACS ‘make_edi’ command to generate essential dynamics (ED) information.

Parameters:

  • clinput (str, optional) – Input string for atom selection.

  • **kwargs (dict) –

    Additional options for ‘make_edi’. Defaults are:

    • f: ‘eigenvec.trr’ (input eigenvector file)

Return type:

None

reforge.cli.args_to_str(*args)[source]

Convert positional arguments to a space-separated string.

Parameters:

*args (str) – Positional arguments to be concatenated.

Returns:

A space-separated string representation of the arguments.

Return type:

str

reforge.cli.kwargs_to_str(hyphen='-', **kwargs)[source]

Convert keyword arguments to a formatted string with a given hyphen prefix.

Parameters:

  • hyphen (str, optional) – The prefix to use for each keyword (default is ‘-‘).

  • **kwargs (dict) – Keyword arguments to be formatted.

Returns:

A formatted string of the keyword arguments.

Return type:

str

reforge.io module

File: io.py

Description:

This module provides I/O utilities for the reForge workflow, including functions for reading and saving various data formats (e.g., CSV, NPY, XVG) as well as parsing PDB files into domain-specific objects. Additionally, it offers helper functions for filtering file names and recursively retrieving file paths from directories.

Usage Example:
>>> from io import read_positions, pdb2system, npy2csv
>>> import numpy as np
>>> # Read positions from an MDAnalysis Universe object 'u'
>>> positions = read_positions(u, ag, time_range=(0, 500), sample_rate=1)
>>> # Save a NumPy array to CSV format
>>> data = np.random.rand(100, 10)
>>> npy2csv(data, 'output.csv')
>>> # Parse a PDB file into a System object
>>> system = pdb2system('structure.pdb')
Requirements:

  • Python 3.x

  • NumPy

  • Pandas

  • pathlib

  • reForge utilities (timeit, memprofit, logger)

  • reForge pdbtools (AtomList, System, PDBParser)

Author: Your Name Date: YYYY-MM-DD

reforge.io.read_positions(u, ag, b=0, e=10000000, sample_rate=1, dtype=<class 'numpy.float32'>)[source]

Extract and return positions from an MDAnalysis trajectory.

This function reads the positions for a specified atom group from the trajectory stored in an MDAnalysis Universe. It extracts frames starting from index b up to index e, sampling every sample_rate frames, and returns the coordinates in a flattened, contiguous 2D array.

Parameters:

  • u (MDAnalysis.Universe) – The MDAnalysis Universe containing the trajectory.

  • ag (MDAnalysis.AtomGroup) – The atom group from which to extract positions.

  • b (int, optional) – The starting frame index (default is 0).

  • e (int, optional) – The ending frame index (default is 10000000).

  • sample_rate (int, optional) – The sampling rate for frames (default is 1, meaning every frame is used).

  • dtype (data-type, optional) – The data type for the returned array (default is np.float32).

Returns:

A contiguous 2D array with shape (n_coords, n_frames) containing flattened position coordinates.

Return type:

np.ndarray

reforge.io.read_velocities(u, ag, b=0, e=10000000, sample_rate=1, dtype=<class 'numpy.float32'>)[source]

Saimilar to the previous. Read and return velocities from an MDAnalysis trajectory.

reforge.io.parse_covar_dat(file, dtype=<class 'numpy.float32'>)[source]

Parse a GROMACS covar.dat file into a covariance matrix.

Parameters:

  • file (str) – Path to the covar.dat file.

  • dtype (data-type, optional) – The data type for the covariance matrix (default is np.float32).

Returns:

A reshaped 2D covariance matrix of shape (3*resnum, 3*resnum), where resnum is inferred from the file.

Return type:

np.ndarray

reforge.io.fname_filter(f, sw='', cont='', ew='')[source]

Check if a file name matches the specified start, contained, and end patterns.

Parameters:

  • f (str) – The file name to check.

  • sw (str, optional) – Required starting substring (default is an empty string).

  • cont (str, optional) – Required substring to be contained in the name (default is an empty string).

  • ew (str, optional) – Required ending substring (default is an empty string).

Returns:

True if the file name satisfies all specified conditions; otherwise, False.

Return type:

bool

reforge.io.filter_files(fpaths, sw='', cont='', ew='')[source]

Filter a list of file paths based on name patterns.

Parameters:

  • fpaths (list[Path]) – A list of pathlib.Path objects representing file paths.

  • sw (str, optional) – Required starting substring (default is an empty string).

  • cont (str, optional) – Required substring to be contained (default is an empty string).

  • ew (str, optional) – Required ending substring (default is an empty string).

Returns:

A list of Path objects that match the specified filters.

Return type:

list[Path]

reforge.io.pull_files(directory, pattern)[source]

Recursively search for files in a directory matching a given pattern.

Parameters:

  • directory (str or Path) – The root directory to search.

  • pattern (str) – The glob pattern to match files (e.g., *.txt).

Returns:

A list of absolute file paths (as strings) that match the pattern.

Return type:

list[str]

Raises:

FileNotFoundError – If the specified directory does not exist or is not a directory.

reforge.io.pull_all_files(directory)[source]

Recursively retrieve all files in the specified directory and its subdirectories.

Parameters:

directory (str or Path) – The directory to search.

Returns:

A list of absolute file paths for all files found.

Return type:

list[str]

reforge.io.xvg2npy(xvg_path, npy_path, usecols=(0, 1))[source]

Convert a GROMACS XVG file to a NumPy binary file (.npy).

Parameters:

  • xvg_path (str) – Path to the input XVG file.

  • npy_path (str) – Path where the output .npy file will be saved.

  • usecols (list of int, optional) – Column indices to read from the XVG file (default is [0, 1]).

Return type:

None

reforge.io.pdb2system(pdb_path) → System[source]

Parse a PDB file and return a System object.

Parameters:

pdb_path (str) – Path to the PDB file.

Returns:

A System object representing the parsed PDB structure.

Return type:

System

reforge.io.pdb2atomlist(pdb_path) → AtomList[source]

Parse a PDB file and return an AtomList object.

Parameters:

pdb_path (str) – Path to the PDB file.

Returns:

An AtomList object containing the atoms from the PDB file.

Return type:

AtomList

reforge.io.read_data(fpath)[source]

Read data from a file (.csv, .npy, .dat, or .xvg) and return it as a NumPy array.

Parameters:

fpath (str) – Path to the data file.

Returns:

The data loaded from the file.

Return type:

np.ndarray

Raises:

ValueError – If the file cannot be read properly or the data does not meet expected criteria.

reforge.io.read_xvg(fpath, usecols=(0, 1))[source]

Read a GROMACS XVG file and return its contents as a Pandas DataFrame.

Parameters:

  • fpath (str) – Path to the XVG file.

  • usecols (list of int, optional) – Column indices to read from the file (default is [0, 1]).

Returns:

A DataFrame containing the selected columns from the XVG file.

Return type:

pd.DataFrame

Raises:

ValueError – If the file cannot be read.

reforge.io.npy2csv(data, fpath)[source]

Save a NumPy array to a file in either .csv or .npy format.

Parameters:

  • data (np.ndarray) – The data to be saved.

  • fpath (str) – Path to the output file. The file extension determines the format (.csv or .npy).

Return type:

None

reforge.io.save_1d_data(data, ids=None, fpath='dfi.xvg', sep=' ')[source]

Save one-dimensional data in GROMACS XVG format.

Parameters:

  • data (list or np.ndarray) – The y-column data to be saved.

  • ids (list or np.ndarray, optional) – The x-column data (e.g., indices). If not provided, defaults to a range starting from 1.

  • fpath (str, optional) – Path to the output file (default is ‘dfi.xvg’).

  • sep (str, optional) – Field separator in the output file (default is a single space).

Return type:

None

reforge.io.save_2d_data(data, fpath='dfi.xvg', sep=' ')[source]

Save two-dimensional data in GROMACS XVG format.

Parameters:

  • data (list or np.ndarray) – The 2D data to be saved.

  • ids (list, optional) – Optional identifiers (unused in this function; provided for interface consistency).

  • fpath (str, optional) – Path to the output file (default is ‘dfi.xvg’).

  • sep (str, optional) – Field separator in the output file (default is a single space).

Return type:

None

reforge.itpio module

IO for GROMACS topology .itp files.

Description:

This module provides functions for reading, parsing, formatting, and writing GROMACS ITP files. It includes utilities to extract and format different sections (such as bonds, angles, atoms, etc.) and higher-level functions tailored for Martini RNA and ion topologies.

Requirements:

  • Python 3.x

  • Standard library modules: shutil, typing

  • (Optional) Additional modules for extended functionality.

Author: DY Date: 2025-02-27

reforge.itpio.read_itp(filename)[source]

Read a Gromacs ITP file and organize its contents by section.

Parameters:

filename (str) – The path to the ITP file.

Returns:

A dictionary where keys are section names and values are lists of entries, each entry being a list of [connectivity, parameters, comment].

Return type:

dict

reforge.itpio.line2bond(line, tag)[source]

Parse a line from an ITP file and return connectivity, parameters, and comment.

Parameters:

  • line (str) – A line from the ITP file.

  • tag (str) – The section tag (e.g. ‘bonds’, ‘angles’, etc.).

Returns:

A tuple (connectivity, parameters, comment) where connectivity is a tuple of ints, parameters is a tuple of numbers (first as int, rest as floats), and comment is a string.

Return type:

tuple

reforge.itpio.bond2line(connectivity=None, parameters='', comment='')[source]

Format a bond entry into a string for a Gromacs ITP file.

Parameters:

  • connectivity (tuple, optional) – Connectivity indices.

  • parameters (tuple, optional) – Bond parameters.

  • comment (str, optional) – Optional comment.

Returns:

A formatted string representing the bond entry.

Return type:

str

reforge.itpio.format_header(molname='molecule', forcefield='', arguments='') → List[str][source]

Format the header of the topology file.

Parameters:

  • molname (str, optional) – Molecule name. Default is “molecule”.

  • forcefield (str, optional) – Force field identifier.

  • arguments (str, optional) – Command-line arguments used.

Returns:

A list of header lines.

Return type:

List[str]

reforge.itpio.format_sequence_section(sequence, secstruct) → List[str][source]

Format the sequence section.

Parameters:

  • sequence (iterable) – Sequence characters.

  • secstruct (iterable) – Secondary structure characters.

Returns:

Formatted lines for the sequence section.

Return type:

List[str]

reforge.itpio.format_moleculetype_section(molname='molecule', nrexcl=1) → List[str][source]

Format the moleculetype section.

Parameters:

  • molname (str, optional) – Molecule name. Default is “molecule”.

  • nrexcl (int, optional) – Number of exclusions. Default is 1.

Returns:

Formatted lines for the moleculetype section.

Return type:

List[str]

reforge.itpio.format_atoms_section(atoms: List[Tuple]) → List[str][source]

Format the atoms section for a Gromacs ITP file.

Parameters:

atoms (List[Tuple]) – List of atom records.

Returns:

A list of formatted lines.

Return type:

List[str]

reforge.itpio.format_bonded_section(header: str, bonds: List[List]) → List[str][source]

Format a bonded section (e.g., bonds, angles) for a Gromacs ITP file.

Parameters:

  • header (str) – Section header.

  • bonds (List[List]) – List of bond entries.

Returns:

A list of formatted lines.

Return type:

List[str]

reforge.itpio.format_posres_section(atoms: List[Tuple], posres_fc=500, selection: List[str] = None) → List[str][source]

Format the position restraints section.

Parameters:

  • atoms (List[Tuple]) – List of atom records.

  • posres_fc (float, optional) – Force constant for restraints. Default is 500.

  • selection (List[str], optional) – Atom names to select. Defaults to [“BB1”, “BB2”, “BB3”, “SC1”] if not provided.

Returns:

A list of formatted lines.

Return type:

List[str]

reforge.itpio.write_itp(filename, lines)[source]

Write a list of lines to an ITP file.

Parameters:

  • filename (str) – Output file path.

  • lines (List[str]) – Lines to write.

reforge.itpio.make_in_terms(input_file, output_file, dict_of_names)[source]

Generate a Martini ITP file using input terms and a dictionary of names.

Parameters:

  • input_file (str) – Path to the input ITP file.

  • output_file (str) – Path to the output ITP file.

  • dict_of_names (dict) – Dictionary mapping keys to desired names.

reforge.itpio.make_cross_terms(input_file, output_file, old_name, new_name)[source]

Append cross-term entries to an ITP file by replacing an old name with a new one.

Parameters:

  • input_file (str) – Path to the input ITP file.

  • output_file (str) – Path to the output ITP file.

  • old_name (str) – The name to be replaced.

  • new_name (str) – The replacement name.

reforge.itpio.make_marnatini_itp()[source]

Generate and copy a Martini RNA ITP file.

This high-level function processes a base Martini ITP file using defined name mappings and copies the resulting file to several target directories.

reforge.itpio.make_ions_itp()[source]

Generate an ITP file for ions.

This function modifies a base Martini ITP file, adjusts parameters, and writes the final Martini ions ITP file.

reforge.itpio.count_itp_atoms(file_path)[source]

Count the number of atom entries in the [ atoms ] section of an ITP file.

Parameters:

file_path (str) – Path to the ITP file.

Returns:

The atom count, or 0 if an error occurs.

Return type:

int

reforge.mdm module

Math for MD

Description:

This module provides a unified interface for molecular dynamics and structural analysis routines within the reForge package. It wraps a variety of operations including FFT-based cross-correlation, covariance matrix computation, perturbation matrix calculations (for DFI/DCI metrics), and elastic network model (ENM) Hessian evaluations. Both CPU and GPU implementations are supported, with fallbacks to CPU methods if CUDA is not available.

Usage Example:
>>> import numpy as np
>>> from mdm import fft_ccf, calc_and_save_covmats, inverse_matrix
>>>
>>> # Compute FFT-based cross-correlation function in serial mode
>>> ccf = fft_ccf(signal1, signal2, mode='serial')
>>>
>>> # Calculate and save covariance matrices from trajectory positions
>>> calc_and_save_covmats(positions, outdir='./covmats', n=5)
>>>
>>> # Compute the inverse of a matrix using the unified inversion wrapper
>>> inv_mat = inverse_matrix(matrix, device='cpu_sparse')
Requirements:

  • Python 3.x

  • MDAnalysis

  • NumPy

  • CuPy (if GPU routines are used)

  • Pandas

  • reForge utilities (logger, etc.)

  • reForge rfgmath modules (rcmath, rpymath)

Author: DY Date: YYYY-MM-DD

reforge.mdm.fft_ccf(*args, mode='serial', **kwargs)[source]

Unified wrapper for FFT-based correlation functions.

This function dispatches to one of the internal FFT correlation routines based on the specified mode:

  • ‘serial’ for sfft_ccf,

  • ‘parallel’ for pfft_ccf, or

  • ‘gpu’ for gfft_ccf.

Parameters:

  • *args – Positional arguments for the chosen correlation function.

  • mode (str, optional) – Mode to use (‘serial’, ‘parallel’, or ‘gpu’). Default is ‘serial’.

  • **kwargs – Additional keyword arguments for the internal routines.

Returns:

The computed correlation function.

Return type:

np.ndarray

Raises:

ValueError – If an unsupported mode is specified.

reforge.mdm.ccf(*args, **kwargs)[source]

Similar to the previous. Unified wrapper for calculating cross-correlations.

reforge.mdm.covariance_matrix(positions, dtype=<class 'numpy.float64'>)[source]

Compute the covariance matrix from trajectory positions.

Parameters:

  • positions (np.ndarray) – Array of position coordinates.

  • dtype (data-type, optional) – Desired data type (default is np.float64).

Returns:

The computed covariance matrix.

Return type:

np.ndarray

reforge.mdm.calc_and_save_covmats(positions, outdir, n=1, outtag='covmat', dtype=<class 'numpy.float32'>)[source]

Calculate and save covariance matrices by splitting a trajectory into segments.

Parameters:

  • positions (np.ndarray) – Array of positions with shape (n_coords, n_frames).

  • outdir (str) – Directory where the covariance matrices will be saved.

  • n (int, optional) – Number of segments to split the trajectory into (default is 1).

  • outtag (str, optional) – Base tag for output file names (default is ‘covmat’).

  • dtype (data-type, optional) – Desired data type for covariance computation (default is np.float32).

Return type:

None

reforge.mdm.calc_and_save_rmsf(positions, outdir, n=1, outtag='rmsf', dtype=<class 'numpy.float64'>)[source]

Calculate and save RMSF by splitting a trajectory into segments.

Parameters:

  • positions (np.ndarray) – Array of positions with shape (n_coords, n_frames).

  • outdir (str) – Directory where the RMSF data will be saved.

  • n (int, optional) – Number of segments to split the trajectory into (default is 1).

  • outtag (str, optional) – Base tag for output file names (default is ‘rmsf’).

  • dtype (data-type, optional) – Desired data type for covariance computation (default is np.float32).

Return type:

None

reforge.mdm.perturbation_matrix(covmat, dtype=<class 'numpy.float64'>)[source]

Compute the perturbation matrix from a covariance matrix.

Parameters:

  • covmat (np.ndarray) – The covariance matrix.

  • dtype (data-type, optional) – Desired data type (default is np.float64).

Returns:

The computed perturbation matrix.

Return type:

np.ndarray

reforge.mdm.perturbation_matrix_iso(covmat, dtype=<class 'numpy.float64'>)[source]

Compute the perturbation matrix from a covariance matrix

reforge.mdm.td_perturbation_matrix(covmat, dtype=<class 'numpy.float64'>)[source]

Compute the block-wise (td) perturbation matrix from a covariance matrix.

Parameters:

  • covmat (np.ndarray) – The covariance matrix.

  • dtype (data-type, optional) – Desired data type (default is np.float64).

Returns:

The computed block-wise perturbation matrix.

Return type:

np.ndarray

reforge.mdm.dfi(pert_mat)[source]

Calculate the Dynamic Flexibility Index (DFI) from a perturbation matrix.

Parameters:

pert_mat (np.ndarray) – The perturbation matrix.

Returns:

The DFI values.

Return type:

np.ndarray

reforge.mdm.dci(pert_mat, asym=False)[source]

Calculate the Dynamic Coupling Index (DCI) from a perturbation matrix.

Parameters:

  • pert_mat (np.ndarray) – The perturbation matrix.

  • asym (bool, optional) – If True, return an asymmetric version (default is False).

Returns:

The DCI matrix.

Return type:

np.ndarray

reforge.mdm.group_molecule_dci(pert_mat, groups=None, asym=False, transpose=False)[source]

Calculate the DCI between groups of atoms and the remainder of the molecule.

Parameters:

  • pert_mat (np.ndarray) – The perturbation matrix.

  • groups (list of lists, optional) – A list of groups, each containing indices of atoms. Defaults to a list containing an empty list.

  • asym (bool, optional) – If True, use the asymmetric DCI (default is False).

Returns:

A list of DCI values for each group.

Return type:

list of np.ndarray

reforge.mdm.group_group_dci(pert_mat, groups=None, asym=False)[source]

Calculate the inter-group DCI matrix.

Parameters:

  • pert_mat (np.ndarray) – The perturbation matrix.

  • groups (list of lists, optional) – A list of groups, each containing indices of atoms. Defaults to a list containing an empty list.

  • asym (bool, optional) – If True, compute the asymmetric DCI (default is False).

Returns:

A 2D list containing the DCI values between each pair of groups.

Return type:

list of lists

reforge.mdm.hessian(vecs, cutoff, spring_constant=1000.0, dd=0)[source]

Compute the Hessian matrix using an elastic network model.

Parameters:

  • vecs (np.ndarray) – Coordinate matrix of shape (n, 3) where each row corresponds to a residue.

  • cutoff (float) – Distance cutoff threshold.

  • spring_constant (float) – Base spring constant.

  • dd (int) – Exponent modifier for the inverse distance.

Returns:

The computed Hessian matrix.

Return type:

np.ndarray

reforge.mdm.inverse_matrix(matrix, device='cpu_sparse', k_singular=6, n_modes=100, dtype=None, **kwargs)[source]

Unified wrapper for computing the inverse of a matrix via eigen-decomposition.

Depending on the ‘device’ parameter, the function selects an appropriate routine.

Parameters:

  • matrix (np.ndarray) – The input matrix.

  • device (str, optional) – Inversion method (‘cpu_sparse’, ‘cpu_dense’, ‘gpu_sparse’, or ‘gpu_dense’). Default is ‘cpu_sparse’.

  • k_singular (int, optional) – Number of smallest eigenvalues to set to zero (default is 6).

  • n_modes (int, optional) – Number of eigenmodes to compute/consider.

  • dtype (data-type, optional) – Desired data type for computations (default: matrix.dtype).

  • **kwargs – Additional keyword arguments for the eigensolver.

Returns:

The computed inverse matrix.

Return type:

np.ndarray or cp.ndarray

reforge.mdm.percentile(x)[source]

Compute the percentile ranking for each element in an array.

Parameters:

x (np.ndarray) – Input array.

Returns:

An array containing the percentile (from 0 to 1) of each element in x.

Return type:

np.ndarray

reforge.pdbtools module

Classes and functions for parsing and manipulating PDB atoms

Description:

This module provides utilities for parsing, manipulating, and writing PDB files. It defines classes for representing individual atoms (Atom), groups of atoms (AtomList), as well as hierarchical representations of residues, chains, models, and entire systems. In addition, helper functions are provided to read and write PDB files and GROMACS index (NDX) files, and to perform common operations such as sorting and cleaning PDB files.

Usage:

from pdbtools import pdb2system, pdb2atomlist, sort_pdb, clean_pdb system = pdb2system(“input.pdb”) atoms = pdb2atomlist(“input.pdb”)

Requirements:

  • Python 3.x

  • pathlib and typing (standard library)

  • pdbfixer and OpenMM (for cleaning PDB files, optional)

Author: DY Date: 2025-02-27

class reforge.pdbtools.Atom(record, atid, name, alt_loc, resname, chid, resid, icode, x, y, z, occupancy, bfactor, segid, element, charge)[source]

Bases: object

Represents an ATOM or HETATM record from a PDB file.

This class intentionally contains many attributes to capture all fields from a PDB record.

classmethod from_pdb_line(line)[source]

Parse a PDB line and return an Atom instance.

to_pdb_line()[source]

Format the Atom as a fixed-width PDB line.

class reforge.pdbtools.AtomList(iterable=(), /)[source]

Bases: list

A list of Atom objects with convenient attribute access.

key_funcs = {'alt_loc': <function AtomList.<lambda>>, 'atid': <function AtomList.<lambda>>, 'bfactor': <function AtomList.<lambda>>, 'charge': <function AtomList.<lambda>>, 'chid': <function AtomList.<lambda>>, 'element': <function AtomList.<lambda>>, 'icode': <function AtomList.<lambda>>, 'name': <function AtomList.<lambda>>, 'occupancy': <function AtomList.<lambda>>, 'record': <function AtomList.<lambda>>, 'resid': <function AtomList.<lambda>>, 'resname': <function AtomList.<lambda>>, 'segid': <function AtomList.<lambda>>, 'x': <function AtomList.<lambda>>, 'y': <function AtomList.<lambda>>, 'z': <function AtomList.<lambda>>}
property records
property atids
property names
property alt_locs
property resnames
property chids
property resids
property icodes
property xs
property ys
property zs
property occupancies
property bfactors
property segids
property elements
property charges
property vecs
property residues

Group atoms by residue and return an AtomListCollection.

property chains

Group atoms by chain identifier and return an AtomListCollection.

property segments

Group atoms by segid identifier and return an AtomListCollection.

renum()[source]

Renumber atom IDs starting from 0.

sort(key=None, reverse=False)[source]

Sort the AtomList in place.

mask(mask_vals, mode='name')[source]

Return a new AtomList with atoms matching the given mask.

mask_out(mask_vals, mode='name')[source]

Return a new AtomList with atoms not matching the given mask.

renumber()[source]

Renumber atoms starting from 1.

remove_atoms(atoms_to_remove)[source]

Remove specified atoms from the AtomList.

read_pdb(in_pdb)[source]

Read a PDB file and populate the AtomList.

write_pdb(out_pdb, append=False)[source]

Write the AtomList to a PDB file.

write_ndx(filename, header='[ group ]', append=False, wrap=15)[source]

Write the atom IDs to a GROMACS .ndx file.

class reforge.pdbtools.AtomListCollection(iterable=(), /)[source]

Bases: list

A collection of AtomList objects.

property records: List[List]
property atids: List[List]
property names: List[List]
property alt_locs: List[List]
property resnames: List[List]
property chids: List[List]
property resids: List[List]
property icodes: List[List]
property xs: List[List]
property ys: List[List]
property zs: List[List]
property occupancies: List[List]
property bfactors: List[List]
property segids: List[List]
property elements: List[List]
property charges: List[List]
property vecs: List[List]
class reforge.pdbtools.Residue(resname, resid, icode)[source]

Bases: object

Represents a residue containing Atom objects.

add_atom(atom)[source]
property atoms
class reforge.pdbtools.Chain(chid)[source]

Bases: object

Represents a chain containing multiple residues.

add_atom(atom)[source]
property atoms
class reforge.pdbtools.Model(modid)[source]

Bases: object

Represents a model containing multiple chains.

add_atom(atom)[source]
property atoms
select_chains(chids)[source]
class reforge.pdbtools.System[source]

Bases: object

Represents an entire system, potentially with multiple models.

add_atom(atom, modid=1)[source]
add_atoms(atoms, modid=1)[source]
property atoms
residues()[source]
chains()[source]
write_pdb(filename)[source]
class reforge.pdbtools.PDBParser(pdb_file)[source]

Bases: object

Parses a PDB file and builds a System object.

parse()[source]
reforge.pdbtools.pdb2system(pdb_path) → System[source]

Parse a PDB file into a System object.

reforge.pdbtools.pdb2atomlist(pdb_path) → AtomList[source]

Read a PDB file and return an AtomList of its atoms.

reforge.pdbtools.sort_chains_atoms(atoms)[source]

Sort an AtomList and renumber atom IDs.

reforge.pdbtools.rename_chains_for_gromacs(atoms)[source]

Rename chains in an AtomList in a predefined order: uppercase, then lowercase, then digits.

reforge.pdbtools.sort_pdb(in_pdb, out_pdb)[source]

Sort a PDB file and save the result.

reforge.pdbtools.clean_pdb(in_pdb, out_pdb, add_missing_atoms=False, add_hydrogens=False, pH=7.0)[source]

Clean a PDB file using PDBFixer via OpenMM.

reforge.pdbtools.rename_chain_in_pdb(in_pdb, new_chain_id)[source]

Rename all chain identifiers in a PDB file.

reforge.pdbtools.rename_chain_and_histidines_in_pdb(in_pdb, new_chain_id)[source]

Rename chain identifiers and update histidine names in a PDB file.

reforge.pdbtools.write_ndx(atoms, fpath='system.ndx', backbone_atoms=('CA', 'P', "C1'"))[source]

Write a GROMACS index file based on an AtomList.

reforge.pdbtools.update_bfactors(in_pdb, out_pdb, bfactors)[source]

(Incomplete) Update the B-factors in a PDB file. Implementation is missing; please provide definitions for read_b_factors and update_pdb_b_factors.

reforge.pdbtools.sort_uld(alist)[source]

Sort a list of characters: uppercase, then lowercase, then digits.

reforge.pdbtools.label_segments(in_pdb, out_pdb)[source]

Label segments based on something

reforge.plotting module

reforge.plotting.init_figure(grid=(2, 3), axsize=(4, 4), **kwargs)[source]

Instantiate a figure.

We can modify axes separately

reforge.plotting.make_hist(ax, datas, params=None)[source]

ax - matplotlib ax object datas - list of datas to histogram params - list of kwargs dictionary for the ax

reforge.plotting.make_plot(ax, xs, ys, params=None)[source]

ax - matplotlib ax object xs - list of x coords ys - list of y coords params - list of kwargs dictionary for the ax

reforge.plotting.make_errorbar(ax, xs, ys, errs, params=None, **kwargs)[source]

ax - matplotlib ax object xs - list of x coords ys - list of y coords errs - list of errors params - list of kwargs dictionary for the ax

reforge.plotting.make_heatmap(ax, data, **params)[source]
reforge.plotting.plot_figure(fig, axes, figname=None, figpath='png/test.png', **kwargs)[source]

Finish plotting.

reforge.plotting.pull_data(metric)[source]
reforge.plotting.set_ax_parameters(ax, xlabel=None, ylabel=None, axtitle=None)[source]

ax - matplotlib ax object

reforge.plotting.set_hm_parameters(ax, mdsys, xlabel=None, ylabel=None, axtitle=None)[source]

ax - matplotlib ax object

reforge.plotting.grid_labels(mdsys)[source]
reforge.plotting.plot_dfi(mdsys)[source]
reforge.plotting.plot_pdfi(mdsys)[source]
reforge.plotting.plot_rmsf(mdsys)[source]
reforge.plotting.plot_rmsd(mdsys)[source]
reforge.plotting.plot_dci(mdsys)[source]
reforge.plotting.plot_asym(mdsys)[source]
reforge.plotting.plot_pert(mdsys)[source]
reforge.plotting.plot_segment_dci(mdsys, segid)[source]
reforge.plotting.plot_segment_asym(mdsys, segid)[source]
reforge.plotting.response_1(mat, norm=1)[source]
reforge.plotting.response_2(mat, norm=1)[source]
reforge.plotting.response_2_2d(mat, norm=1)[source]
reforge.plotting.response_force(mat_t)[source]
reforge.plotting.response(mat, norm=1)[source]
reforge.plotting.make_1d_data(infile, nframes=1000)[source]
reforge.plotting.make_2d_data(infile, nframes=1000)[source]
reforge.plotting.make_heatmap_td(data, outfile='png/heatmap.png')[source]
reforge.plotting.make_plot_td(datas, labels, outfile='png/test.png')[source]
reforge.plotting.make_plot_t_td(datas, labels, outfile='png/test.png', dt=0.2)[source]
reforge.plotting.make_plot_t_2d(datas, labels, outfile='png/test.png', dt=0.2, nframes=750)[source]
reforge.plotting.animate_1d(fig, ax, lines, datas, outfile='data/ani1d.mp4', dt=0.2)[source]
reforge.plotting.animate_2d(fig, img, data, outfile='data/ani2d.mp4', dt=0.2)[source]
reforge.plotting.make_animation(infile, mode='1d', tag='pv', outfile=None)[source]
reforge.plotting.mkfigure(datas, labels)[source]
reforge.plotting.make_1d_plots(sysdir, sysnames)[source]

reforge.utils module

Utility wrappers and functions

Description:

This module provides utility functions and decorators for the reForge workflow. It includes decorators for timing and memory profiling functions, a context manager for changing the working directory, and helper functions for cleaning directories and detecting CUDA availability.

Usage Example:
>>> from utils import timeit, memprofit, cd, clean_dir, cuda_info
>>>
>>> @timeit
... def my_function():
...     # Function implementation here
...     pass
>>>
>>> with cd("/tmp"):
...     # Perform operations in /tmp
...     pass
>>>
>>> cuda_info()
Requirements:

  • Python 3.x

  • cupy

  • Standard libraries: logging, os, time, tracemalloc, contextlib, functools, pathlib

Author: DY Date: YYYY-MM-DD

reforge.utils.timeit(func)[source]

Decorator to measure and log the execution time of a function.

reforge.utils.memprofit(func)[source]

Decorator to profile and log the memory usage of a function.

reforge.utils.cd(newdir)[source]

Context manager to temporarily change the current working directory.

Parameters:

newdir (str or Path): The target directory to change into.

Yields:

None. After the context, reverts to the original directory.

reforge.utils.clean_dir(directory='.', pattern='#*')[source]

Remove files matching a specific pattern from a directory.

Parameters:

directory (str or Path, optional): Directory to search (default: current directory). pattern (str, optional): Glob pattern for files to remove (default: “#*”).

reforge.utils.cuda_info()[source]

Check CUDA availability and log CUDA device information if available.

Returns:

bool: True if CUDA is available, False otherwise.

reforge.utils.cuda_detected()[source]

Check if CUDA is detected without logging detailed device information.

Returns:

bool: True if CUDA is available, False otherwise.

Module contents