reforge.rfgmath package
Submodules
reforge.rfgmath.legacy module
- reforge.rfgmath.legacy.calcperturbMat(invHrs, resnum)[source]
Legavy perturbation matrix for dfi calculation.
- reforge.rfgmath.legacy.calculate_hessian(resnum, x, y, z, cutoff=12, spring_constant=1000, dd=0, dtype=<class 'numpy.float64'>)[source]
- reforge.rfgmath.legacy.perturbation_matrix_old(covariance_matrix, resnum, dtype=<class 'numpy.float64'>)[source]
- reforge.rfgmath.legacy.perturbation_matrix_cpu(covariance_matrix, dtype=<class 'numpy.float64'>)[source]
Calculates perturbation matrix from a covariance matrix or a hessian on CPU The result is normalized such that the total sum of the matrix elements is equal to 1.
- reforge.rfgmath.legacy.td_perturbation_matrix_cpu(ccf, normalize=True, dtype=<class 'numpy.float64'>)[source]
Calculates perturbation matrix from a covariance matrix or a hessian on CPU The result is normalized such that the total sum of the matrix elements is equal to 1.
reforge.rfgmath.rcmath module
Cython Math
- Description:
This module contains internal routines for performing optimized mathematical operations. It includes functions for calculating position-position Hessian matrices and perturbation matrices derived from coordinate and covariance data. The computations are accelerated using Cython.
Note: This module is intended for internal use only within the reForge workflow.
- Usage Example:
>>> import numpy as np >>> from rcmath import _calculate_hessian, _hessian, _perturbation_matrix, _td_perturbation_matrix >>> # Generate random coordinate data for residues >>> n = 10 >>> vecs = np.random.rand(n, 3) >>> hessian2 = _hessian(vecs, cutoff=1.2, spring_constant=1000, dd=0) >>> # Compute perturbation matrix from a covariance matrix >>> cov_matrix = np.random.rand(3 * n, 3 * n) >>> pert_matrix = _perturbation_matrix(cov_matrix) >>> # Compute block-wise perturbation matrix with normalization >>> td_pert_matrix = _td_perturbation_matrix(cov_matrix, normalize=True)
- Requirements:
Python 3.x
NumPy
Cython
reForge utilities (timeit, memprofit)
Author: Your Name Date: YYYY-MM-DD
- reforge.rfgmath.rcmath.calculate_hessian(resnum, x, y, z, cutoff=1.2, spring_constant=1000.0, dd=0)
Calculate the position-position Hessian matrix based on individual coordinate arrays.
- Parameters:
resnum (int) – Number of residues (atoms).
x (ndarray of double, 1D) – Array of x coordinates.
y (ndarray of double, 1D) – Array of y coordinates.
z (ndarray of double, 1D) – Array of z coordinates.
cutoff (double, optional) – Distance cutoff threshold. Interactions beyond this distance are ignored (default is 1.2).
spring_constant (double, optional) – Base spring constant used in the calculation (default is 1000).
dd (int, optional) – Exponent modifier applied to the inverse distance factor (default is 0).
- Returns:
hessian – Hessian matrix of shape (3*resnum, 3*resnum) representing the second derivatives of the system energy with respect to positions.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.covmat(X)
Naive mimicing of:
covmat = np.cov(centered_positions, rowvar=True, dtype=np.float64)
Much slower, as expected.
- reforge.rfgmath.rcmath.hessian(vec, cutoff=1.2, spring_constant=1000.0, dd=0)
Calculate the position-position Hessian matrix from a coordinate matrix.
- Parameters:
vec (ndarray of double, 2D) – A coordinate matrix where each residue’s coordinates are provided. Note: The function computes n = vec.shape[0] // 3; thus, vec.shape[0] should be a multiple of 3. Each residue is expected to have three entries corresponding to its x, y, and z coordinates.
cutoff (double, optional) – Distance cutoff threshold. Interactions beyond this distance are ignored (default is 1.2).
spring_constant (double, optional) – Base spring constant used in the calculation (default is 1000).
dd (int, optional) – Exponent modifier applied to the inverse distance factor (default is 0).
- Returns:
hessian – Hessian matrix of shape (3*n, 3*n) representing the second derivatives of the system energy, where n is derived from the input coordinate matrix.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.pcovmat(X)
Parallel computation of covariance matrix using OpenMP (via prange). Assumes X is already centered (mean subtracted).
- reforge.rfgmath.rcmath.perturbation_matrix(covariance_matrix, normalize=True) ndarray
Compute a perturbation matrix from a covariance matrix. Same as the old one but no need to specify resnum and works with rectangular matrices
- Parameters:
covariance_matrix (ndarray of double, 2D) – A covariance matrix computed from positional data with shape (3*m, 3*n), where m and n are the numbers of residues in two systems.
- Returns:
perturbation_matrix – A normalized perturbation matrix of shape (m, n). Each element represents the aggregated perturbation computed from the directional components of the corresponding 3x3 block.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.perturbation_matrix_iso(ccf, normalize=True) ndarray
Calculate the perturbation matrix from a covariance (or Hessian) matrix using block-wise norms.
The input covariance matrix ‘ccf’ is expected to have shape (3*m, 3*n). For each block (i,j), the perturbation value is computed as the square root of the sum of the squares of the corresponding 3x3 block elements.
- Parameters:
ccf (ndarray of double, 2D) – Input covariance matrix with shape (3*m, 3*n).
normalize (bool, optional) – If True, the output perturbation matrix is normalized so that the total sum of its elements equals 1 (default is True).
- Returns:
perturbation_matrix – An (m, n) matrix of perturbation values computed from the blocks of ccf.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.perturbation_matrix_iso_par(ccf, normalize=True) ndarray
Parallel computation of perturbation matrix using OpenMP. Calculate the perturbation matrix from a covariance (or Hessian) matrix using block-wise norms.
The input covariance matrix ‘ccf’ is expected to have shape (3*m, 3*n). For each block (i,j), the perturbation value is computed as the square root of the sum of the squares of the corresponding 3x3 block elements.
- Parameters:
ccf (ndarray of double, 2D) – Input covariance matrix with shape (3*m, 3*n).
normalize (bool, optional) – If True, the output perturbation matrix is normalized so that the total sum of its elements equals 1 (default is True).
- Returns:
perturbation_matrix – An (m, n) matrix of perturbation values computed from the blocks of ccf.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.perturbation_matrix_old(covariance_matrix, resnum)
Compute a perturbation matrix from a covariance matrix using an older method.
- Parameters:
covariance_matrix (ndarray of double, 2D) – A covariance matrix of shape (3*resnum, 3*resnum) computed from position data.
resnum (int) – Number of residues (atoms).
- Returns:
perturbation_matrix – A normalized perturbation matrix of shape (resnum, resnum), where each element represents the cumulative perturbation contribution from directional projections.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.perturbation_matrix_par(covariance_matrix, normalize=True) ndarray
Compute a perturbation matrix from a covariance matrix. Same as the old one but no need to specify resnum and works with rectangular matrices
- Parameters:
covariance_matrix (ndarray of double, 2D) – A covariance matrix computed from positional data with shape (3*m, 3*n), where m and n are the numbers of residues in two systems.
- Returns:
perturbation_matrix – A normalized perturbation matrix of shape (m, n). Each element represents the aggregated perturbation computed from the directional components of the corresponding 3x3 block.
- Return type:
ndarray of double, 2D
- reforge.rfgmath.rcmath.td_perturbation_matrix(ccf, normalize=True) ndarray
Calculate the time-dependent perturbation matrix from a td-correlation matrix using block-wise norms.
The input covariance matrix ‘ccf’ is expected to have shape (3*m, 3*n, nt). For each block (i,j, it), the perturbation value is computed as the square root of the sum of the squares of the corresponding 3x3 block elements.
- Parameters:
ccf (ndarray of double, 3D) – Input covariance matrix with shape (3*m, 3*n, nt).
normalize (bool, optional) – If True, the output perturbation matrix is normalized so that the total sum of its elements equals 1 (default is True).
- Returns:
perturbation_matrix – An (m, n, nt) matrix of perturbation values computed from the blocks of ccf.
- Return type:
ndarray of double, 3D
reforge.rfgmath.rpykernels module
CUDA kernels for CuPy
- Description:
This module contains CUDA kernel versions of internal routines for performing optimized mathematical operations. It includes functions for calculating position-position Hessian matrices and perturbation matrices derived from coordinate and covariance data, accelerated using CUDA. The computations are implemented as CUDA kernels and are intended for internal use within the reForge workflow.
- Usage Example:
>>> import cupy as cp >>> import numpy as np >>> from rcmath_cuda import calculate_hessian_cuda, hessian_cuda, perturbation_matrix_cuda, td_perturbation_matrix_cuda >>> n = 10 >>> # Create random coordinate data on the GPU: >>> x = cp.asarray(np.random.rand(n)) >>> y = cp.asarray(np.random.rand(n)) >>> z = cp.asarray(np.random.rand(n)) >>> hess = calculate_hessian_cuda(n, x, y, z, 1.2, 1000.0, 0) >>> >>> # Alternatively, if the coordinates are stored in an (n x 3) array: >>> vec = cp.asarray(np.random.rand(n, 3)) >>> hess2 = hessian_cuda(vec, 1.2, 1000.0, 0) >>> >>> # Compute a perturbation matrix from a covariance matrix: >>> cov = cp.asarray(np.random.rand(3*n, 3*n)) >>> pert = perturbation_matrix_cuda(cov) >>> >>> # Compute a block-wise perturbation matrix: >>> td_pert = td_perturbation_matrix_cuda(cov)
- Requirements:
Python 3.x
NumPy
CuPy
reForge utilities (timeit, memprofit)
Author: Your Name Date: YYYY-MM-DD
- reforge.rfgmath.rpykernels.hessian_cuda(vec, cutoff=1.2, spring_constant=1000.0, dd=0)[source]
CUDA version of _hessian.
- Parameters:
vec (cupy.ndarray) – A coordinate matrix of shape (n, 3) with type float64.
cutoff (float, optional) – Distance cutoff.
spring_constant (float, optional) – Base spring constant.
dd (int, optional) – Exponent modifier.
- Returns:
Hessian matrix of shape (3*n, 3*n) as a cupy array.
- Return type:
cupy.ndarray
- reforge.rfgmath.rpykernels.perturbation_matrix_cuda(covar)[source]
CUDA version of _perturbation_matrix.
- Parameters:
covar (cupy.ndarray) – Covariance matrix of shape (3*m, 3*n) with type float64.
- Returns:
Perturbation matrix of shape (m, n) (normalization should be applied separately if needed).
- Return type:
cupy.ndarray
- reforge.rfgmath.rpykernels.td_perturbation_matrix_cuda(ccf, normalize=True)[source]
CUDA version of _td_perturbation_matrix.
- Parameters:
ccf (cupy.ndarray) – Covariance (or Hessian) matrix of shape (3*m, 3*n) with type float64.
normalize (bool, optional) – If True, the output matrix is normalized so that the total sum equals 1. (Normalization is performed on the CPU after kernel execution.)
- Returns:
Perturbation matrix of shape (m, n).
- Return type:
cupy.ndarray
reforge.rfgmath.rpymath module
Python math functions
- Description:
This module contains internal routines for performing various mathematical and signal processing operations required in our workflow. It includes FFT‐based correlation computations (serial, parallel, and GPU versions), covariance matrix calculation, dynamic coupling and flexibility index evaluations, sparse matrix inversion on both CPU and GPU, and additional helper functions such as percentile computation and FFT‐based convolution.
Note: This module is intended for internal use only.
- Usage Example:
>>> from rpymath import _sfft_ccf, fft_ccf >>> import numpy as np >>> # Generate random signals >>> x = np.random.rand(10, 256) >>> y = np.random.rand(10, 256) >>> # Compute serial FFT‐based correlation >>> corr = _sfft_ccf(x, y, ntmax=64, center=True, loop=True) >>> # Or use the unified FFT correlation wrapper >>> corr = fft_ccf(x, y, mode='serial', ntmax=64, center=True)
- Requirements:
Python 3.x
NumPy
SciPy
CuPy (for GPU-based functions)
joblib (for parallel processing)
MDAnalysis (if required elsewhere)
Author: DY Date: YYYY-MM-DD
- reforge.rfgmath.rpymath.sfft_ccf(x, y, ntmax=None, center=False, loop=True, dtype=None)[source]
Compute the correlation function between two signals using a serial FFT-based method.
- Parameters:
x (np.ndarray): First input signal of shape (n_coords, n_samples). y (np.ndarray): Second input signal of shape (n_coords, n_samples). ntmax (int, optional): Maximum number of time samples to retain. center (bool, optional): If True, subtract the mean from each signal. loop (bool, optional): If True, compute the correlation in a loop. dtype (data-type, optional): Desired data type (default: x.dtype).
- Returns:
np.ndarray: Correlation function array of shape (n_coords, n_coords, ntmax).
- reforge.rfgmath.rpymath.pfft_ccf(x, y, ntmax=None, center=False, dtype=None)[source]
Compute the correlation function using a parallel FFT-based method.
- Parameters:
x (np.ndarray): First input signal. y (np.ndarray): Second input signal. ntmax (int, optional): Maximum number of time samples to retain. center (bool, optional): If True, subtract the mean. dtype (data-type, optional): Desired data type.
- Returns:
np.ndarray: Correlation function array with shape (n_coords, n_coords, ntmax).
- reforge.rfgmath.rpymath.gfft_ccf(x, y, ntmax=None, center=True, dtype=None)[source]
Compute the correlation function on the GPU using FFT.
- Parameters:
x (np.ndarray): First input signal. y (np.ndarray): Second input signal. ntmax (int, optional): Maximum number of time samples to retain. center (bool, optional): If True, subtract the mean. dtype (data-type, optional): Desired CuPy data type (default: inferred from x).
- Returns:
cp.ndarray: The computed correlation function as a CuPy array.
- reforge.rfgmath.rpymath.gfft_ccf_auto(x, y, ntmax=None, center=True, buffer_c=0.95, dtype=None)[source]
Same as “gfft_ccf” but regulates GPU to CPU I/O based on the available GPU memory
- reforge.rfgmath.rpymath.fft_ccf(*args, mode='serial', **kwargs)[source]
Unified wrapper for FFT-based correlation functions.
- Parameters:
args: Positional arguments for the chosen correlation function. mode (str): Mode to use (‘serial’, ‘parallel’, or ‘gpu’). kwargs: Additional keyword arguments.
- Returns:
np.ndarray: The computed correlation function.
- Raises:
ValueError: If an unsupported mode is specified.
- reforge.rfgmath.rpymath.ccf(xs, ys, ntmax=None, n=1, mode='parallel', center=True, dtype=None)[source]
Compute the average cross-correlation function of two signals by segmenting them.
- Parameters:
xs (np.ndarray): First input signal of shape (n_coords, n_samples). ys (np.ndarray): Second input signal of shape (n_coords, n_samples). ntmax (int, optional): Maximum number of time samples per segment. n (int, optional): Number of segments. mode (str, optional): Mode (‘parallel’, ‘serial’, or ‘gpu’). center (bool, optional): If True, mean-center the signals. dtype (data-type, optional): Desired data type.
- Returns:
np.ndarray: The averaged cross-correlation function.
- reforge.rfgmath.rpymath.gfft_conv(x, y, loop=False, dtype=None)[source]
Compute element-wise convolution between two signals on the GPU using FFT.
- Parameters:
x (np.ndarray): First input signal. y (np.ndarray): Second input signal. loop (bool, optional): If True, use a loop-based computation. dtype (data-type, optional): Desired CuPy data type.
- Returns:
np.ndarray: Convolution result as a NumPy array.
- reforge.rfgmath.rpymath.sfft_cpsd(x, y, ntmax=None, center=True, loop=True, dtype=<class 'numpy.float64'>)[source]
Compute the Cross-Power Spectral Density (CPSD) between two signals using FFT.
- Parameters:
x (np.ndarray): First input signal. y (np.ndarray): Second input signal. ntmax (int, optional): Number of frequency bins to retain. center (bool, optional): If True, mean-center the signals. loop (bool, optional): If True, use loop-based computation. dtype (data-type, optional): Desired data type.
- Returns:
np.ndarray: The computed CPSD.
- reforge.rfgmath.rpymath.covariance_matrix(positions, dtype=<class 'numpy.float32'>)[source]
Calculate the position-position covariance matrix from a set of positions.
The function centers the input positions by subtracting their mean and then computes the covariance matrix using np.cov.
- Parameters:
positions (np.ndarray): Array of positions. dtype (data-type, optional): Data type (default: np.float32).
- Returns:
np.ndarray: The computed covariance matrix.
- reforge.rfgmath.rpymath.dci(perturbation_matrix, asym=False)[source]
Calculate the Dynamic Coupling Index (DCI) matrix from a perturbation matrix.
- Parameters:
perturbation_matrix (np.ndarray): Input perturbation matrix. asym (bool, optional): If True, return asymmetric DCI.
- Returns:
np.ndarray: The computed DCI matrix.
- reforge.rfgmath.rpymath.group_molecule_dci(perturbation_matrix, groups=None, asym=False)[source]
Compute the DCI for specified groups of atoms relative to the entire molecule.
- Parameters:
perturbation_matrix (np.ndarray): The perturbation matrix. groups (list of list, optional): List of groups of atom indices. Defaults to [[]]. asym (bool, optional): If True, adjust for asymmetry.
- Returns:
list: List of DCI values for each group.
- reforge.rfgmath.rpymath.group_group_dci(perturbation_matrix, groups=None, asym=False)[source]
Calculate the DCI matrix between different groups of atoms.
- Parameters:
perturbation_matrix (np.ndarray): The perturbation matrix. groups (list of list, optional): List of groups (each a list of indices). Defaults to [[]]. asym (bool, optional): If True, compute asymmetric DCI.
- Returns:
list: A nested list representing the DCI matrix between groups.
- reforge.rfgmath.rpymath.inverse_sparse_matrix_cpu(matrix, k_singular=6, n_modes=20, dtype=None, **kwargs)[source]
Compute the inverse of a sparse matrix on the CPU using eigen-decomposition.
- Parameters:
matrix (np.ndarray): Input matrix. k_singular (int, optional): Number of smallest eigenvalues to zero out. n_modes (int, optional): Number of eigenmodes to compute. dtype: Desired data type (default: matrix.dtype). kwargs: Additional arguments for eigensolver.
- Returns:
np.ndarray: The computed inverse matrix.
- reforge.rfgmath.rpymath.inverse_matrix_cpu(matrix, k_singular=6, n_modes=100, dtype=None, **kwargs)[source]
Compute the inverse of a matrix on the CPU using dense eigen-decomposition.
- Parameters:
matrix (np.ndarray): Input matrix. k_singular (int, optional): Number of smallest eigenvalues to zero out. n_modes (int, optional): Number of eigenmodes to consider. dtype: Desired data type (default: matrix.dtype). kwargs: Additional arguments for the solver.
- Returns:
np.ndarray: The inverse matrix computed on the CPU.
- reforge.rfgmath.rpymath.inverse_sparse_matrix_gpu(matrix, k_singular=6, n_modes=20, dtype=None, **kwargs)[source]
Compute the inverse of a sparse matrix on the GPU using eigen-decomposition.
- Parameters:
matrix (np.ndarray): Input matrix. k_singular (int, optional): Number of smallest eigenvalues to zero out. n_modes (int, optional): Number of eigenmodes to compute. dtype: Desired CuPy data type (default: matrix.dtype). kwargs: Additional arguments for the GPU eigensolver.
- Returns:
cp.ndarray: The inverse matrix computed on the GPU.
- reforge.rfgmath.rpymath.inverse_matrix_gpu(matrix, k_singular=6, n_modes=100, dtype=None, **kwargs)[source]
Compute the inverse of a matrix on the GPU using dense eigen-decomposition.
- Parameters:
matrix (np.ndarray): Input matrix. k_singular (int, optional): Number of smallest eigenvalues to zero out. n_modes (int, optional): Number of eigenmodes to consider. dtype: Desired CuPy data type (default: matrix.dtype). kwargs: Additional arguments for the solver.
- Returns:
cp.ndarray: The inverse matrix computed on the GPU.