Skip to content

Regions

RectangularRegion(center, lengths)

Bases: Region

A 3D rectangular region defined by its center and dimensions.

This class represents a rectangular box in 3D space, capable of generating a grid of points that fill the box.

Initialize a rectangular region.

PARAMETER DESCRIPTION

center

The x, y, and z coordinates of the center of the box.

TYPE: list[float]

lengths

The lengths of the box along the x, y, and z axes.

TYPE: list[float]

center = np.array(center)

A list of three floats representing the x, y, and z coordinates of the box's center, in Angstroms.

lengths = np.array(lengths)

A list of three floats representing the lengths of the box along the x, y, and z axes, in Angstroms.

__str__()

Returns a string representation of the rectangular region.

get_points(res)

Generates a grid of points filling the rectangular region.

PARAMETER DESCRIPTION

res

The resolution of the grid, defining the spacing between points.
RETURNS DESCRIPTION

A numpy array of shape (n, 3), where each row is a [x, y, z]

coordinate representing a point within the rectangular region.

Region()

Bases: ABC

Abstract base class representing a 3D region.

This class provides a blueprint for defining specific types of 3D regions. Subclasses must implement methods to provide a string representation of the region and to generate a grid of points filling the region.

__str__()

Returns a string representation of the region.

get_points(res)

Generates a grid of equally spaced points filling the region.

PARAMETER DESCRIPTION

res

The resolution of the grid, defining the spacing between points.

TYPE: float

RETURNS DESCRIPTION
NDArray[float64]

A numpy array of shape (n, 3), where each row is a [x, y, z]
NDArray[float64]

coordinate representing a point in the region.

SphericalRegion(center, radius)

Bases: Region

A 3D spherical region defined by a center and a radius.

This class represents a sphere in 3D space, capable of generating a grid of points that fill the sphere. Points outside the sphere boundary are excluded.

Initialize a spherical region.

PARAMETER DESCRIPTION

center

The x, y, and z coordinates of the center of the sphere.

TYPE: list[float]

radius

The radius of the sphere in Angstroms.

TYPE: float

center = np.array(center)

x, y, and z coordinates in Angstroms of the center.

radius = radius

Sphere radius in Angstroms.

__str__()

Returns a string representation of the spherical region.

get_points(res)

Generates a grid of points filling the spherical region.

PARAMETER DESCRIPTION

res

The resolution of the grid, defining the spacing between points.

TYPE: float

RETURNS DESCRIPTION
NDArray[float64]

A numpy array of shape (n, 3), where each row is a [x, y, z]
NDArray[float64]

coordinate representing a point within the spherical region.

build_mesh_grid(xs, ys, zs, res)

Creates a 3D grid of points using given x, y, and z coordinate vectors.

This function generates all possible combinations of xs, ys, and zs to create a rectangular 3D grid, then snaps the resulting points to the nearest fixed grid using the specified resolution.

PARAMETER DESCRIPTION

xs

A 1D numpy array representing the x-coordinates of the grid.

TYPE: NDArray[float64]

ys

A 1D numpy array representing the y-coordinates of the grid.

TYPE: NDArray[float64]

zs

A 1D numpy array representing the z-coordinates of the grid.

TYPE: NDArray[float64]

res

The resolution of the final snapped grid.

TYPE: float

RETURNS DESCRIPTION
NDArray[float64]

A 2D numpy array of shape (n, 3), where each row is a point on the
NDArray[float64]

3D grid after snapping to the fixed resolution.
Example 
>>> import numpy as np
>>> xs = np.array([0.0, 1.0, 2.0])
>>> ys = np.array([0.0, 1.0])
>>> zs = np.array([0.0, 1.0])
>>> build_mesh_grid(xs, ys, zs, res=0.5)
array([[0.0, 0.0, 0.0],
       [0.0, 0.0, 0.5],
       [0.0, 0.5, 0.0],
       ...
       [2.0, 1.0, 1.0]])

collect_regions(spherical_configs, rectangular_configs)

Creates a collection of 3D regions from spherical and rectangular configurations.

This function takes configurations for spherical and rectangular regions, instantiates the respective region objects, and returns a combined list of these regions. Empty or invalid configurations are skipped.

PARAMETER DESCRIPTION

spherical_configs

A list of dictionaries, each specifying a spherical region. Each dictionary must have:

  • "center" (list[float]): The x, y, and z coordinates of the sphere's center.
  • "radius" (float): The radius of the sphere.

If None, no spherical regions are added.

TYPE: list[dict[str, list[float] | float]] | None

rectangular_configs

A list of dictionaries, each specifying a rectangular region. Each dictionary must have:

  • "center" (list[float]): The x, y, and z coordinates of the box's center.
  • "lengths" (list[float]): The lengths of the box along the x, y, and z axes.

If None, no rectangular regions are added.

TYPE: list[dict[str, list[float]]] | None

RETURNS DESCRIPTION
list[SphericalRegion | RectangularRegion]

A list containing SphericalRegion and RectangularRegion objects created based on the provided configurations.
Example 
>>> spherical_configs = [
...     {"center": [0.0, 0.0, 0.0], "radius": 5.0},
...     {"center": [10.0, 10.0, 10.0], "radius": 3.0},
... ]
>>> rectangular_configs = [
...     {"center": [0.0, 0.0, 0.0], "lengths": [10.0, 5.0, 2.0]}
... ]
>>> regions = collect_regions(spherical_configs, rectangular_configs)
>>> for region in regions:
...     print(region)
sphere at (0.0, 0.0, 0.0), radius = 5.0
sphere at (10.0, 10.0, 10.0), radius = 3.0
box centered at (0.0, 0.0, 0.0) with dimensions (10.0, 5.0, 2.0)

snap_points(points, res)

Aligns a set of 3D points to the nearest points on a uniform grid.

This function "snaps" each point to the nearest grid point based on a specified grid resolution. It is useful for discretizing continuous 3D coordinates into a fixed grid.

PARAMETER DESCRIPTION

points

A numpy array of shape (n, 3), where n is the number of points. Each row represents a point in 3D space with [x, y, z] coordinates.

TYPE: NDArray[float64]

res

The resolution of the grid, defining the distance between adjacent grid points.

TYPE: float

RETURNS DESCRIPTION
NDArray[float64]

A numpy array of the same shape as points, where each point is
NDArray[float64]

adjusted to lie on the nearest grid point defined by res.
Example 
>>> import numpy as np
>>> points = np.array([[1.2, 3.5, 7.8], [2.7, 4.1, 6.3]])
>>> snap_points(points, res=1.0)
array([[1.0, 4.0, 8.0],
       [3.0, 4.0, 6.0]])