Python reference

Generated from the docstrings of the installed module, which are the ones help(meshsearch) prints. Every entry here is the same code the C++ reference documents, reached through nanobind.

The grid

class meshsearch.MeshGrid(*args, **kwargs)

Uniform cubic mesh over a set of points, for neighbour queries.

Objects are identified by their position in the coordinate arrays. Indices are stable: remove_object leaves an index permanently invalid, add_object issues a new one, and indices are never reused.

__init__(self, x: collections.abc.Sequence[float], y: collections.abc.Sequence[float], z: collections.abc.Sequence[float], cellsize: float, limits: collections.abc.Sequence[collections.abc.Sequence[float]] | None = None) → None

Build the grid over the points, which must be of equal length. limits is ((xlo,xhi),(ylo,yhi),(zlo,zhi)); when omitted, the data range padded by a margin proportional to it. Each side of the box is grown symmetrically to a whole number of cells; an axis of zero extent gets one cell.

Raises meshsearch.Error for a cellsize that is not finite and positive, limits that are not finite or have lo > hi, a coordinate that is not finite or outside limits, or a grid too large to count; MemoryError if the grid cannot be allocated.

__len__(self) → int

Number of objects in the grid, excluding removed ones.

add_object(self, x: float, y: float, z: float) → int

Add an object and return its index, one past the highest ever issued.

close_objects(self, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], rmax: float, rmin: float = 0.0) → tuple
close_objects(self, x: float, y: float, z: float, rmax: float, rmin: float = 0.0) → numpy.ndarray[dtype=uint32, shape=(*)]
close_objects(self, index: int, rmax: float, rmin: float = 0.0) → numpy.ndarray[dtype=uint32, shape=(*)]

Overloaded function.

  1. close_objects(self, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], rmax: float, rmin: float = 0.0) -> tuple

Objects at distance d from each of an array of points, with rmin <= d <= rmax, as (indices, offsets) in compressed-row form: the results of query i are indices[offsets[i]:offsets[i+1]]. offsets has n_query + 1 entries, starts at 0 and ends at len(indices). A query with no results gives an empty slice, never a missing entry.

  1. close_objects(self, x: float, y: float, z: float, rmax: float, rmin: float = 0.0) -> numpy.ndarray[dtype=uint32, shape=(*)]

Objects at distance d from a point, with rmin <= d <= rmax, in unspecified order. The interval is closed at both ends, so an object at exactly either radius is returned. An object lying on the point is at d = 0 and is returned.

  1. close_objects(self, index: int, rmax: float, rmin: float = 0.0) -> numpy.ndarray[dtype=uint32, shape=(*)]

Objects at distance d from an object, with rmin <= d <= rmax, in unspecified order. The query object is excluded by identity, not by distance: another object coincident with it is at d = 0 and is returned.

get_cell(self, x: float, y: float, z: float) → int

Linear index of the cell containing a point.

get_cell_coords(self, x: float, y: float, z: float) → tuple

Cell coordinates (ix, iy, iz) of the cell containing a point.

get_objects_in_cell(self, x: float, y: float, z: float) → numpy.ndarray[dtype=uint32, shape=(*)]

Objects in the cell containing a point.

is_alive(self, index: int) → bool

True if index names an object still in the grid.

nearest_object(self, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False]) → numpy.ndarray[dtype=uint32, shape=(*)]
nearest_object(self, x: float, y: float, z: float) → int
nearest_object(self, index: int) → int

Overloaded function.

  1. nearest_object(self, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False]) -> numpy.ndarray[dtype=uint32, shape=(*)]

The object nearest to each of an array of points: one index per query, in query order.

  1. nearest_object(self, x: float, y: float, z: float) -> int

Index of the object nearest to a point. An object lying on the point is at distance 0 and is the answer.

  1. nearest_object(self, index: int) -> int

Index of the object nearest to an object. The query object is excluded by identity, not by distance: another object coincident with it is at distance 0 and may be the answer.

nearest_objects(self, n: int, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False]) → numpy.ndarray[dtype=uint32, shape=(*, *)]
nearest_objects(self, n: int, x: float, y: float, z: float) → numpy.ndarray[dtype=uint32, shape=(*)]
nearest_objects(self, n: int, index: int) → numpy.ndarray[dtype=uint32, shape=(*)]

Overloaded function.

  1. nearest_objects(self, n: int, x: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], y: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False], z: ndarray[dtype=float64, shape=(*), order='C', device='cpu', writable=False]) -> numpy.ndarray[dtype=uint32, shape=(*, *)]

The n objects nearest to each of an array of points, nearest first: an (n_query, n) array, rectangular because every query returns exactly n.

  1. nearest_objects(self, n: int, x: float, y: float, z: float) -> numpy.ndarray[dtype=uint32, shape=(*)]

The n objects nearest to a point, nearest first.

  1. nearest_objects(self, n: int, index: int) -> numpy.ndarray[dtype=uint32, shape=(*)]

The n objects nearest to an object, nearest first. The query object is excluded by identity, not by distance: another object coincident with it is at distance 0 and is among them.

remove_object(self, index: int) → None

Remove an object. Its index stays invalid for the life of the grid.

property cellsize

Cell side.

property lims

The box, grown to whole cells, as a 3x2 array.

property n_cells

Cells per axis.

Errors

exception meshsearch.Error

Bases: ValueError

Thrown on invalid input or on a point outside the box.

exception meshsearch.IndexError

Bases: Error, IndexError

Thrown on an index that is out of range or names a removed object.