pysoftk.pysoftwhere package

Submodules

pysoftk.pysoftwhere.icsi module

class pysoftk.pysoftwhere.icsi.icsi(u, cluster_resids, cluster_atoms_positions, core_sel_atoms_positions, shell_sel_atoms_positions, frame=-1, no_bins=31, no_random_points=10000, normalisation_run=False)[source]

Bases: object

Calculates the Intrinsic Surface Density (ISD) of a defined cluster within a molecular dynamics simulation.

The Intrinsic Surface Density (ISD) provides a quantitative measure of the local density fluctuations at the interface of a molecular cluster. This class implements the ISD calculation, as described in scientific literature, to characterize the roughness or compactness of a cluster’s surface. It processes molecular positions, converts them to spherical coordinates, and performs binning to determine the intrinsic radius, spherical radius, and interface values.

Parameters:

  • u (MDAnalysis.Universe) – An MDAnalysis Universe object containing the trajectory and topology information of the molecular system. This universe provides the context for atom selections and positions.

  • cluster_resids (list of int) – A list of residue IDs (integers) that collectively define the cluster of interest. All atoms belonging to these residues will be considered part of the cluster.

  • cluster_atoms_positions (numpy.ndarray) – A 3D NumPy array of shape (n_atoms, 3) representing the Cartesian coordinates (x, y, z) of all atoms within the cluster_resids for a specific frame.

  • core_sel_atoms_positions (numpy.ndarray) – A 3D NumPy array of shape (n_core_atoms, 3) representing the Cartesian coordinates (x, y, z) of atoms defined as the core region of the cluster. These atoms are used to establish the “inner” boundary for the intrinsic radius calculation.

  • shell_sel_atoms_positions (numpy.ndarray) – A 3D NumPy array of shape (n_shell_atoms, 3) representing the Cartesian coordinates (x, y, z) of atoms defined as the shell region of the cluster. These atoms represent the “outer” boundary and are used to probe the surface.

  • frame (int, optional) – The index of the trajectory frame to use for the ISD calculation. A value of -1 (default) indicates the last frame of the trajectory.

  • no_bins (int, optional) – The number of bins to use for constructing the 2D histogram in spherical coordinate space ($cos( heta)$ and $phi$). A higher number of bins provides finer resolution but may lead to sparser data. Defaults to 31.

  • no_random_points (int, optional) – The number of random points to generate for normalization purposes when normalisation_run is set to True. These points are uniformly distributed within the simulation box. Defaults to 10000.

  • normalisation_run (bool, optional) – A flag indicating whether the calculation should use randomly generated points for normalization instead of the actual shell_sel_atoms_positions. Set to True for normalization runs, False (default) for actual ISD calculation.

intrinsic_r

A list containing the calculated intrinsic radii for each shell atom. The intrinsic radius represents the distance from the cluster’s effective surface to the shell atom.

Type:

list of float

spherical_r

A list containing the calculated spherical radii for each shell atom. The spherical radius is the radial distance of the shell atom from the center of mass of the cluster.

Type:

list of float

interface_vals

A 2D NumPy array representing the calculated interface values across the binned spherical coordinate space. This array effectively maps the “edge” of the core region in different angular directions.

Type:

numpy.ndarray

Raises:

ValueError – If an invalid frame index is provided (e.g., out of trajectory bounds).

See also

MDAnalysis.Universe

For details on the MDAnalysis Universe object.

scipy.stats.binned_statistic_2d

For details on the 2D histogramming function.

Notes

The calculation of the intrinsic surface density involves: 1. Defining a cluster, its core, and its shell regions. 2. Translating all atomic coordinates to the center of mass of the cluster. 3. Converting Cartesian coordinates of core and shell atoms to spherical

coordinates (r, $ heta$, $phi$).

  1. Binning the spherical coordinates to create a 2D histogram.

  2. Determining the “interface” position, typically by finding the maximum radial distance of core atoms within each angular bin.

  3. Calculating the intrinsic radius for each shell atom as the difference between its spherical radius and the interface position in its corresponding angular bin.

The method handles missing data (NaNs) in the interface values by averaging from neighboring bins, ensuring a continuous interface definition.

Module contents