pestifer.psfutil.psftopoelement module¶

Defines the PSFTopoElement and PSFTopoElementList classes for handling PSF topology elements.

These classes provide a framework for representing and manipulating the various elements found in PSF files, including atoms, bonds, angles, and dihedrals.

class pestifer.psfutil.psftopoelement.LineList(data)[source]¶

Bases: UserList

A class for handling a list of lines, typically used for reading and writing PSF topology elements. This class inherits from collections.UserList and provides additional functionality for managing a list of lines that represent PSF topology elements.

class pestifer.psfutil.psftopoelement.PSFTopoElement(idx_list: list[int])[source]¶

Bases: Namespace

A class representing a single PSF topology element, such as an atom, bond, angle, or dihedral. This class inherits from argparse.Namespace, allowing it to store attributes as if they were command-line arguments. It provides methods for ingesting coordinates, calculating properties, and validating images. The class also includes methods for mic-shifting coordinates, copying the element, and matching against specific criteria.

Parameters:: idx_list (list) – A list of indices representing the serial numbers of the atoms involved in this topology element. The indices are used to uniquely identify the atoms in the PSF file.

assign_cell_index(LC: Linkcell)[source]¶

Assign the link cell index to the topology element based on its center of mass. This method uses the linkcell module to determine the link cell index of the center of mass (COM) of the topology element.

Parameters:: LC (LinkCell) – An instance of the LinkCell class that provides methods for determining link cell indices.

calculate_stuff()[source]¶

Calculate various properties of the topology element based on its coordinates. This method computes the center of mass (COM), radii, normalized radii, and the distance matrix between points. It also calculates the vector differences between all pairs of points and their corresponding distances.

COM¶

The center of mass of the points in the topology element.

Type:: numpy.ndarray

Radii¶

The vector differences of the points from the center of mass.

Type:: numpy.ndarray

radii¶

The normalized radii of the points, calculated as the vector differences divided by their magnitudes.

Type:: numpy.ndarray

B¶

The vector differences between all pairs of points in the topology element.

Type:: numpy.ndarray

b¶

The distances between all pairs of points, calculated as the magnitudes of the vector differences.

Type:: numpy.ndarray

copy()[source]¶: Create a deep copy of the PSFTopoElement instance. This method returns a new instance of the PSFTopoElement class with the same attributes as the original instance.

ingest_coordinates(A: DataFrame, pos_key: list[str] = ['posX', 'posY', 'posZ'], meta_key: list[str] = [])[source]¶

Ingest coordinates from a DataFrame and store them in the topology element. This method extracts the coordinates of the points associated with the indices in self.idx_list and stores them in the self.P attribute. It also calculates properties if there are multiple points.

Parameters:

A (pandas.DataFrame) – A DataFrame containing the coordinates and metadata for the topology element.
pos_key (list, optional) – A list of column names in the DataFrame that contain the position coordinates (default is [‘posX’, ‘posY’, ‘posZ’]).
meta_key (list, optional) – A list of column names in the DataFrame that contain metadata for the topology element (default is an empty list).

P¶

An array of shape (n, 3) containing the coordinates of the points in the topology element.

Type:: numpy.ndarray

same_image¶

A boolean indicating whether all points are in the same image based on their coordinates.

Type:: bool

match(**crits)[source]¶

Check if the topology element matches the specified criteria. This method compares the attributes of the topology element against the provided keyword arguments (criteria).

Parameters:: **crits (dict) – A dictionary of criteria where the keys are attribute names and the values are the expected values for those attributes.
Returns:: A boolean indicating whether the topology element matches the specified criteria. If all criteria are met, it returns True; otherwise, it returns False.
Return type:: bool

mic_shift(reference_point: ndarray, box: ndarray)[source]¶

Perform a minimum image convention (MIC) shift on the coordinates of the topology element. This method shifts the coordinates of the points in the topology element so that they are within the minimum image convention, relative to a reference point, and within the specified box dimensions.

Parameters:

reference_point (numpy.ndarray) – A 1D array representing the reference point for the MIC shift.
box (numpy.ndarray) – A 2D array representing the box dimensions, where each row corresponds to a dimension (x, y, z) and contains the lower and upper bounds of that dimension.

validate_image(box: ndarray)[source]¶

Validate whether all points in the topology element are within the same image based on the provided box dimensions. This method checks if the distance from the center of mass (COM) to each point is less than half the box length in each dimension.

Parameters:: box (numpy.ndarray) – A 2D array representing the box dimensions, where each row corresponds to a dimension (x, y, z) and contains the lower and upper bounds of that dimension.
Returns:: A boolean indicating whether all points are in the same image. If all points are within half the box length in each dimension, it returns True; otherwise, it returns False.
Return type:: bool

class pestifer.psfutil.psftopoelement.PSFTopoElementList(data: list[PSFTopoElement])[source]¶

Bases: UserList[PSFTopoElement]

A class representing a list of PSF topology elements, such as atoms, bonds, angles, or dihedrals. This class inherits from collections.UserList and provides methods for managing a list of PSF topology elements. It can be initialized from a list of lines or from another PSFTopoElementList object.

Parameters:: data (list) – A list of PSF topology elements or lines representing the topology elements.

assign_cell_indexes(LC: Linkcell)[source]¶

Assign the link cell index to each topology element in the list based on their center of mass. This method iterates over each PSF topology element in the list and calls the assign_cell_index method of each element to determine and assign the link cell index using the provided link cell object.

Parameters:: LC (LinkCell) – The link cell object used to assign the link cell index to each topology element.

get(**crits)[source]¶

ingest_coordinates(A: DataFrame, pos_key: list[str] = ['posX', 'posY', 'posZ'], meta_key: list[str] = [])[source]¶

Ingest coordinates from a DataFrame and store them in each topology element in the list. This method iterates over each PSF topology element in the list and calls the ingest_coordinates method of each element to extract and store the coordinates from the DataFrame.

Parameters:

A (pandas.DataFrame) – The DataFrame containing the coordinates to be ingested.
pos_key (list of str) – The list of column names in the DataFrame corresponding to the position coordinates.
meta_key (list of str) – The list of column names in the DataFrame corresponding to the metadata.

validate_images(box: ndarray)[source]¶

Validate whether all topology elements in the list are within the same image based on the provided box dimensions. This method checks if each topology element’s coordinates are within half the box length in each dimension.

Parameters:: box (Box) – The box object representing the simulation box dimensions.
Returns:: A boolean indicating whether all topology elements are in the same image. If all elements are within half the box length in each dimension, it returns True; otherwise, it returns False.
Return type:: bool