molgri.space.fullgrid

Full discretisation of space in spherical layers.

The module fullgrid combines a linear translation grid with two spherical grids: discretisation of approach vectors (3D sphere, orientation grid) and of internal rotations of the second body (4D half-sphere of quaternions, body grid). The three grids are commonly referred to as t_grid, o_grid and b_grid.

Position grid is a product of t_grid and o_grid and represents a set of spherical points in 3D space that are repeated at different radii. Based on a position grid it is possible to create a Voronoi discretisation of 3D space using identical (up to radius) layers of Voronoi surfaces between layers of grid points and connecting them with ray points from the origin to are vertices of Voronoi cells. Methods to calculate volumes, areas and distances between centers of such discretisation sof position space are provided.

Classes

`ConvergenceFullGridO`(b_grid_name, ...[, ...])
`FullGrid`(b_grid_name, o_grid_name, t_grid_name)	A combination object that enables work a combination of three grids (provided by their names)
`FullVoronoiGrid`(full_grid)	Created from FullGrid, implements functionality that is specifically Voronoi-based.
`Point`(index_position_grid, full_sv)	A Point represents a single cell in a particular FullVoronoiGrid.

class molgri.space.fullgrid.FullGrid(b_grid_name: str, o_grid_name: str, t_grid_name: str, use_saved: bool = True, filter_non_unique: bool = False)

A combination object that enables work a combination of three grids (provided by their names)

Args:: b_grid_name: body rotation grid (a 4D sphere grid of quaternions used to generate orientations) o_grid_name: origin rotation grid (a 3D sphere grid used to create approach vectors) t_grid_name: translation grid (a linear grid used to determine distances to origin)
Args:: b_grid_name: of the form ‘ico_17’ o_grid_name: of the form ‘cube4D_12’ t_grid_name: of the form ‘[1, 3, 4.5]’ use_saved: try to obtain saved data if possible filter_non_unique: remove repeating points from spherical grids so that Voronoi cells can be built

__init__(b_grid_name: str, o_grid_name: str, t_grid_name: str, use_saved: bool = True, filter_non_unique: bool = False)

Args:: b_grid_name: of the form ‘ico_17’ o_grid_name: of the form ‘cube4D_12’ t_grid_name: of the form ‘[1, 3, 4.5]’ use_saved: try to obtain saved data if possible filter_non_unique: remove repeating points from spherical grids so that Voronoi cells can be built

get_name() → str: Name that is appropriate for saving.

get_full_grid() → Tuple[SphereGridNDim, SphereGridNDim, TranslationParser]: Get all relevant sub-grids.

get_radii() → ndarray[Any, dtype[ScalarType]]: Get the radii at which points are positioned. Result is in Angstroms.

get_between_radii() → ndarray[Any, dtype[ScalarType]]

Get the radii at which Voronoi cells of the position grid should be positioned. This should be right in-between two orientation point layers (except the first layer that is fully encapsulated by the first voronoi layer and the last one that is simply in-between two voronoi layers).

Returns:: an array of distances, same length as the self.get_radii array but with all distances larger than the corresponding point radii

get_body_rotations() → Rotation: Get a Rotation object (may encapsulate a list of rotations) from the body grid.

get_position_grid() → ndarray[Any, dtype[ScalarType]]

Get a ‘product’ of o_grid and t_grid so you can visualise points in space at which COM of the second molecule will be positioned. Important: Those are points on spheres in real space.

Returns:: an array of shape (len_o_grid, len_t_grid, 3) in which the elements of result[0] have the first rotational position, each line at a new (increasing) distance, result[1] the next rotational position, again at all possible distances …

get_flat_position_grid() → ndarray[Any, dtype[ScalarType]]: Get a position grid that is not structured layer-by-layer but is simply a 2D array of shape (N_t*N_o, 3) where N_t is the length of translation grid and N_o the length of orientation grid.

save_full_grid(): Save position grid.

get_full_voronoi_grid() → FullVoronoiGrid | None: Get the corresponding FullVoronoiGrid object.

point2cell_position_grid(points_vector: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]: This method is used to back-map any points in 3D space to their corresponding Voronoi cell indices (of position grid). This means that, given an array of shape (k, 3) as points_vector, the result will be a vector of length k in which each item is an index of the flattened position grid. The point falls into the Voronoi cell associated with this index.

nan_free_assignments(points_vector: ndarray[Any, dtype[ScalarType]]) → Tuple[ndarray[Any, dtype[ScalarType]], ndarray[Any, dtype[ScalarType]]]: Same as point2cell_position_grid, but remove any cells that don’t belong to the grid. In this way, there are no NaNs in the assignment array and it can be converted to the integer type

points2cell_scipy(points_vector: ndarray[Any, dtype[ScalarType]]) → ndarray[Any, dtype[ScalarType]]: For comparison to self.point2cell_position_grid(), here is a method that assigns belonging to a grid point simply based on distance and not considering the spherical nature of the grid.

class molgri.space.fullgrid.FullVoronoiGrid(full_grid: FullGrid)

Created from FullGrid, implements functionality that is specifically Voronoi-based.

Enables calculations of all distances, areas, and volumes of/between cells.

__init__(full_grid: FullGrid)

get_name() → str: Name for saving files.

get_voronoi_discretisation() → list: Create a list of spherical voronoi-s that are identical except at different radii. The radii are set in such a way that there is always a Voronoi cell layer right in-between two layers of grid cells. (see FullGrid method get_between_radii for details.

find_voronoi_vertices_of_point(point_index: int, which: str = 'all') → ndarray[Any, dtype[ScalarType]]

Using an index (from flattened position grid), find which voronoi vertices belong to this point.

Args:: point_index: for which point in flattened position grid the vertices should be found which: which vertices: all, upper or lower
Returns:: an array of vertices, each row is a 3D point.

get_distance_between_centers(index_1: int, index_2: int, print_message=True) → float | None

Calculate the distance between two position grid points selected by their indices. Optionally print message if they are not neighbours.

There are three options:

point1 is right above point2 or vide versa -> the distance is measured in a straight line from the center
point1 and point2 are sideways neighbours -> the distance is measured on the circumference of their radius
point1 and point2 are not neighbours -> return None

Returns:

None if not neighbours, distance in angstrom else

get_division_area(index_1: int, index_2: int, print_message: bool = True) → float | None: Calculate the area (in Angstrom squared) that is the border area between two Voronoi cells. This is either a curved area (a part of a sphere) if the two cells are one above the other or a flat, part of circle or circular ring if the cells are neighbours at the same level. If points are not neighbours, returns None.

get_volume(index: int) → float: Get the volume of any

get_all_voronoi_volumes() → ndarray[Any, dtype[ScalarType]]: Get an array in the same order as flat position grid, listing the volumes of Voronoi cells.

get_all_voronoi_surfaces() → csc_array: If l is the length of the flattened position array, returns a lxl (sparse) array where the i-th row and j-th column (as well as the j-th row and the i-th column) represent the size of the Voronoi surface between points i and j in position grid. If the points do not share a division area, no value will be set.

get_all_distances_between_centers() → csc_array: Get a sparse matrix where for all sets of neighbouring cells the distance between Voronoi centers is provided. Therefore, the value at [i][j] equals the value at [j][i]. For more information, check self.get_distance_between_centers.

get_all_voronoi_surfaces_as_numpy() → ndarray[Any, dtype[ScalarType]]: See self.get_all_voronoi_surfaces, only transforms sparse array to normal array.

get_all_distances_between_centers_as_numpy() → ndarray[Any, dtype[ScalarType]]: See self.get_all_distances_between_centers, only transforms sparse array to normal array.

class molgri.space.fullgrid.Point(index_position_grid: int, full_sv: FullVoronoiGrid)

A Point represents a single cell in a particular FullVoronoiGrid. It holds all relevant information, eg. the index of the cell within a single layer and in a full flattened position grid. It enables the identification of Voronoi vertices and connected calculations (distances, areas, volumes).

__init__(index_position_grid: int, full_sv: FullVoronoiGrid)

get_normalised_point() → ndarray[Any, dtype[ScalarType]]: Get the vector to the grid point (center of Voronoi cell) normalised to length 1.

get_radius_above() → float: Get the radius of the SphericalVoronoi cell that is the upper surface of the cell.

get_radius_below() → float: Get the radius of the SphericalVoronoi cell that is the lower surface of the cell (return zero if there is no Voronoi layer below).

get_area_above() → float: Get the area of the Voronoi surface that is the upper side of the cell (curved surface, part of sphere).

get_area_below() → float: Get the area of the Voronoi surface that is the lower side of the cell (curved surface, part of sphere).

get_vertices_above() → ndarray[Any, dtype[ScalarType]]: Get the vertices of this cell that belong to the SphericalVoronoi above the point.

get_vertices_below() → ndarray[Any, dtype[ScalarType]]: Get the vertices of this cell that belong to the SphericalVoronoi below the point (or just the origin if the point belongs to the first layer.

get_vertices(): Get all vertices of this cell as a single array.

get_cell_volume(): Get the volume of this cell (calculated as the difference between the part of sphere volume at radius above minus the same area at smaller radius).

class molgri.space.fullgrid.ConvergenceFullGridO(b_grid_name: str, t_grid_name: str, o_alg_name: str, N_set=None, use_saved=False, **kwargs)

__init__(b_grid_name: str, t_grid_name: str, o_alg_name: str, N_set=None, use_saved=False, **kwargs)

get_name()

classmethod create(b_grid_name: str, t_grid_name: str, o_alg_name: str, N_set, **kwargs) → list

get_voronoi_volumes()