odatse.util.neighborlist module

class odatse.util.neighborlist.Cells(mins: ndarray, maxs: ndarray, cellsize: float)

Bases: object

A class to represent a grid of cells for spatial partitioning.

This class divides a spatial region into a grid of cells to efficiently find neighboring points within a specified radius. Each cell contains a set of point indices that fall within its spatial boundaries.

cells

List of sets, where each set contains indices of points in that cell.

Type:

List[Set[int]]

dimension

Number of spatial dimensions.

Type:

int

mins

Minimum coordinates of the grid in each dimension.

Type:

np.ndarray

maxs

Maximum coordinates of the grid in each dimension.

Type:

np.ndarray

Ns

Number of cells in each dimension.

Type:

np.ndarray

ncell

Total number of cells in the grid.

Type:

int

cellsize

Size of each cell.

Type:

float

Examples

>>> mins = np.array([0.0, 0.0, 0.0])
>>> maxs = np.array([10.0, 10.0, 10.0])
>>> cells = Cells(mins, maxs, cellsize=2.0)
>>> point_index = 0
>>> point_coords = np.array([1.5, 3.2, 4.7])
>>> cell_index = cells.coord2cellindex(point_coords)
>>> cells.cells[cell_index].add(point_index)

Initialize the Cells object.

Parameters:

• mins (np.ndarray) – The minimum coordinates of the grid in each dimension.

• maxs (np.ndarray) – The maximum coordinates of the grid in each dimension.

• cellsize (float) – The size of each cell.

Returns:

This method initializes the object’s attributes.

Return type:

None

Examples

>>> mins = np.array([0.0, 0.0, 0.0])
>>> maxs = np.array([10.0, 10.0, 10.0])
>>> cells = Cells(mins, maxs, cellsize=2.0)

__init__(mins: ndarray, maxs: ndarray, cellsize: float) → None

Initialize the Cells object.

Parameters:

• mins (np.ndarray) – The minimum coordinates of the grid in each dimension.

• maxs (np.ndarray) – The maximum coordinates of the grid in each dimension.

• cellsize (float) – The size of each cell.

Returns:

This method initializes the object’s attributes.

Return type:

None

Examples

>>> mins = np.array([0.0, 0.0, 0.0])
>>> maxs = np.array([10.0, 10.0, 10.0])
>>> cells = Cells(mins, maxs, cellsize=2.0)

cellcoord2cellindex(ns: ndarray) → int

Convert cell coordinates to a cell index.

This method converts multi-dimensional cell coordinates to a single index that uniquely identifies the cell in the flat cells list.

Parameters:

ns (np.ndarray) – The cell coordinates (integer indices for each dimension).

Returns:

The index of the cell in the flat cells list.

Return type:

int

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> cells.cellcoord2cellindex(np.array([1, 2]))
12

cellindex2cellcoord(index: int) → ndarray

Convert a cell index to cell coordinates.

This method is the inverse of cellcoord2cellindex and converts a flat cell index back to multi-dimensional cell coordinates.

Parameters:

index (int) – The index of the cell in the flat cells list.

Returns:

The cell coordinates (integer indices for each dimension).

Return type:

np.ndarray

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> cells.cellindex2cellcoord(12)
array([1, 2])

coord2cellcoord(x: ndarray) → ndarray

Convert spatial coordinates to cell coordinates.

Cell coordinates are integer indices that identify the position of a cell within the grid along each dimension.

Parameters:

x (np.ndarray) – The spatial coordinates of a point.

Returns:

The cell coordinates (integer indices for each dimension).

Return type:

np.ndarray

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> cells.coord2cellcoord(np.array([3.5, 4.2]))
array([1, 2])

coord2cellindex(x: ndarray) → int

Convert spatial coordinates to a cell index.

This method transforms a point’s spatial coordinates into the index of the cell containing it, by first converting to cell coordinates and then to a cell index.

Parameters:

x (np.ndarray) – The spatial coordinates of a point.

Returns:

The index of the cell containing the point.

Return type:

int

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> cells.coord2cellindex(np.array([3.5, 4.2]))
12

neighborcells(index: int) → List[int]

Get the indices of neighboring cells, including the cell itself.

This method returns the indices of all cells that are adjacent to the specified cell in all dimensions, along with the cell itself.

Parameters:

index (int) – The index of the cell.

Returns:

The indices of the neighboring cells (including the cell itself).

Return type:

List[int]

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> neighbors = cells.neighborcells(12)
>>> len(neighbors)  # 3x3 neighborhood in 2D
9

out_of_bound(ns: ndarray) → bool

Check if cell coordinates are out of bounds.

This method verifies whether the given cell coordinates are within the valid range of the grid.

Parameters:

ns (np.ndarray) – The cell coordinates to check.

Returns:

True if the coordinates are out of bounds, False otherwise.

Return type:

bool

Examples

>>> cells = Cells(np.array([0, 0]), np.array([10, 10]), 2.0)
>>> cells.out_of_bound(np.array([-1, 2]))
True
>>> cells.out_of_bound(np.array([3, 4]))
False

odatse.util.neighborlist.load_neighbor_list(filename: PathLike, nnodes: int = None) → List[List[int]]

Load a neighbor list from a file.

The file format is expected to have one line per node, with the first number being the node index and subsequent numbers being its neighbors.

Parameters:

• filename (PathLike) – The path to the file containing the neighbor list.

• nnodes (int, optional) – The number of nodes. If None, it will be determined from the file by counting the number of non-empty lines.

Returns:

The neighbor list loaded from the file.

Return type:

List[List[int]]

Examples

>>> # Example file content:
>>> # 0 1 2
>>> # 1 0 2
>>> # 2 0 1
>>> neighbor_list = load_neighbor_list("neighborlist.txt")
>>> neighbor_list
[[1, 2], [0, 2], [0, 1]]

odatse.util.neighborlist.main() → None

Command-line utility for creating neighbor lists from mesh data files.

This function parses command-line arguments and creates a neighbor list file from a given input mesh file.

Returns:

This function is the main entry point for the command-line utility.

Return type:

None

odatse.util.neighborlist.make_neighbor_list(X: ndarray, radius: float, allow_selfloop: bool = False, check_allpairs: bool = False, show_progress: bool = False, comm: Comm = None) → List[List[int]]

Create a neighbor list for given points.

This function serves as a unified interface to create neighbor lists, choosing between cell-based or naive implementation based on the parameters.

Parameters:

• X (np.ndarray) – The coordinates of the points (N x D array where N is the number of points and D is the dimensionality).

• radius (float) – The radius within which points are considered neighbors.

• allow_selfloop (bool, optional) – Whether to allow a point to be its own neighbor, by default False.

• check_allpairs (bool, optional) – Whether to use the naive all-pairs approach instead of the cell-based one, by default False.

• show_progress (bool, optional) – Whether to show a progress bar during computation, by default False.

• comm (mpi.Comm, optional) – The MPI communicator for parallel processing, by default None.

Returns:

A list of lists, where each inner list contains the indices of neighboring points for a given point.

Return type:

List[List[int]]

Examples

>>> coords = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [5.0, 5.0]])
>>> neighbor_list = make_neighbor_list(coords, radius=1.5)
>>> neighbor_list
[[1, 2], [0, 2], [0, 1], []]

>>> # Force all-pairs algorithm
>>> neighbor_list = make_neighbor_list(coords, radius=1.5, check_allpairs=True)
>>> neighbor_list
[[1, 2], [0, 2], [0, 1], []]

odatse.util.neighborlist.make_neighbor_list_cell(X: ndarray, radius: float, allow_selfloop: bool, show_progress: bool, comm: Comm = None) → List[List[int]]

Create a neighbor list using cell-based spatial partitioning.

This function uses the Cells class to efficiently find neighboring points within the specified radius by only considering points in adjacent cells.

Parameters:

• X (np.ndarray) – The coordinates of the points (N x D array where N is the number of points and D is the dimensionality).

• radius (float) – The radius within which points are considered neighbors.

• allow_selfloop (bool) – Whether to allow a point to be its own neighbor.

• show_progress (bool) – Whether to show a progress bar during computation.

• comm (mpi.Comm, optional) – The MPI communicator for parallel processing, by default None.

Returns:

A list of lists, where each inner list contains the indices of neighboring points for a given point.

Return type:

List[List[int]]

Examples

>>> coords = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [5.0, 5.0]])
>>> neighbor_list = make_neighbor_list_cell(coords, radius=1.5,
...                                        allow_selfloop=False,
...                                        show_progress=False)
>>> neighbor_list
[[1, 2], [0, 2], [0, 1], []]

odatse.util.neighborlist.make_neighbor_list_naive(X: ndarray, radius: float, allow_selfloop: bool, show_progress: bool, comm: Comm = None) → List[List[int]]

Create a neighbor list using a naive all-pairs approach.

This function computes the distance between all pairs of points to find neighbors within the specified radius. This is less efficient than the cell-based approach for large point sets but may be more straightforward.

Parameters:

• X (np.ndarray) – The coordinates of the points (N x D array where N is the number of points and D is the dimensionality).

• radius (float) – The radius within which points are considered neighbors.

• allow_selfloop (bool) – Whether to allow a point to be its own neighbor.

• show_progress (bool) – Whether to show a progress bar during computation.

• comm (mpi.Comm, optional) – The MPI communicator for parallel processing, by default None.

Returns:

A list of lists, where each inner list contains the indices of neighboring points for a given point.

Return type:

List[List[int]]

Examples

>>> coords = np.array([[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [5.0, 5.0]])
>>> neighbor_list = make_neighbor_list_naive(coords, radius=1.5,
...                                         allow_selfloop=False,
...                                         show_progress=False)
>>> neighbor_list
[[1, 2], [0, 2], [0, 1], []]

odatse.util.neighborlist.write_neighbor_list(filename: str, nnlist: List[List[int]], radius: float = None, unit: ndarray = None) → None

Write the neighbor list to a file.

The file format has one line per node, with the first number being the node index and subsequent numbers being its neighbors. Optional metadata can be included as comments at the beginning of the file.

Parameters:

• filename (str) – The path to the output file.

• nnlist (List[List[int]]) – The neighbor list to write.

• radius (float, optional) – The neighborhood radius, written as a comment in the file, by default None.

• unit (np.ndarray, optional) – The unit lengths for each coordinate dimension, written as a comment in the file, by default None.

Returns:

This function writes the neighbor list to a file.

Return type:

None

Examples

>>> neighbor_list = [[1, 2], [0, 2], [0, 1]]
>>> write_neighbor_list("neighborlist.txt", neighbor_list, radius=1.5,
...                    unit=np.array([1.0, 1.0, 1.0]))