C++ reference

Generated from include/meshsearch/MeshGrid.h by Doxygen, with only what carries a comment included. Private members are not documented here: their comments, where they exist, are for someone reading the source.

The grid

class MeshGrid

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

Objects are identified by the index of their coordinates as passed to the constructor. Indices are stable: removeObject leaves an index permanently invalid, addObject issues a new one, and indices are never reused or renumbered. Naming a removed index raises.

Const members may be called concurrently on the same grid. Non-const members may not.

Coordinates, cellsize and radii must all be in the same unit; none is imposed.

Any member that allocates may throw std::bad_alloc, which is not translated into Error. A constructor that throws builds nothing, and addObject leaves the grid as it was if it throws.

GridOffset and the protected members are implementation details: they are not part of the interface and may change between versions.

Public Functions

MeshGrid() = default

Empty grid. Every member raises or returns empty until it is assigned to.

MeshGrid(const std::vector<double> &X, const std::vector<double> &Y, const std::vector<double> &Z, double cellsize, const std::vector<std::vector<double>> &limits = {})

Build the grid.

Each side of the box is grown symmetrically to a whole number of cells. get_lims returns the grown box, and members validate points against it, so a point outside limits may still be accepted.

An axis of zero extent, where every coordinate is equal or lo == hi, gets one cell, and the box is grown symmetrically around it to one cellsize.

Every check is made before anything is allocated.

Parameters:

  • X, Y, Z – coordinates, all of the same length, copied into the grid

  • cellsize – cell side, finite and positive; one to four mean separations of the data is the usual range, and docs/benchmark.md measures what it costs

  • limits – box as {{xlo,xhi},{ylo,yhi},{zlo,zhi}}, finite, with lo <= hi on each axis; if empty, the data range padded by a margin proportional to it

Throws:

Error – if the vectors differ in length; if cellsize is not finite and positive; if limits is not 3x2, not finite, or has lo > hi on an axis; if a coordinate is not finite or lies outside limits; if the grid would need more than 2147483647 cells along an axis, or more cells or memory than 64-bit sizes can count; or if there are more than 4294967295 objects

unsigned int get_nObjects() const

Number of objects in the grid, excluding removed ones.

bool isAlive(unsigned int index) const

True if index names an object still in the grid.

std::vector<std::vector<double>> get_lims() const

The box, grown to whole cells.

std::array<unsigned int, 3> get_nCells() const

Cells per axis.

double get_cellsize() const

Cell side.

unsigned int nearestObject(double X, double Y, double Z) const

Index of the object nearest to a point.

Nothing is excluded: an object lying on the point is at distance 0 and is the answer.

Throws:

Error – if the point is outside the box, or if the grid holds no objects

unsigned int nearestObject(unsigned int index) const

Index of the object nearest to object index, which is excluded.

index is excluded by identity, not by distance: another object coincident with it is at distance 0 and may be the answer.

Throws:

  • IndexError – if index is out of range or removed

  • Error – if no other object remains

std::vector<unsigned int> nearestObjects(unsigned int N, double X, double Y, double Z) const

The N objects nearest to a point, nearest first.

Nothing is excluded: an object lying on the point is at distance 0 and is among them.

Parameters:

  • N – at most get_nObjects(); 0 returns an empty vector

  • X, Y, Z – the point, which must lie inside the box

Throws:

Error – if the point is outside the box, or if N is too large

std::vector<unsigned int> nearestObjects(unsigned int N, unsigned int index) const

The N objects nearest to object index, which is excluded.

index is excluded by identity, not by distance: another object coincident with it is at distance 0 and is among them.

Parameters:

  • N – at most get_nObjects()-1; 0 returns an empty vector

  • index – the object to measure from, itself excluded

Throws:

  • IndexError – if index is out of range or removed

  • Error – if N is too large

std::vector<unsigned int> closeObjects(double X, double Y, double Z, double Rmax, double Rmin = 0.) const

Objects at distance d from a point, with Rmin <= d <= Rmax.

The interval is closed at both ends, so a ball holds every object within Rmax of the point and an object at exactly either end is returned. Rmin == Rmax selects the objects at exactly that distance.

Nothing is excluded by identity: an object lying on the point is at d = 0 and is returned.

A shell reaching past the box is truncated, not an error. An infinite Rmax is accepted and selects every object from Rmin outwards.

Parameters:

  • X, Y, Z – the point, which must lie inside the box

  • Rmax – outer radius, inclusive; +inf is accepted

  • Rmin – inner radius, inclusive; 0 by default, giving a ball

Throws:

Error – if the point is outside the box, if a radius is negative or NaN, or if Rmin exceeds Rmax

Returns:

the indices, in unspecified order

std::vector<unsigned int> closeObjects(unsigned int index, double Rmax, double Rmin = 0.) const

Objects at distance d from object index, with Rmin <= d <= Rmax. The object itself is excluded.

The interval is the point overload’s, closed at both ends. index is excluded by identity, not by distance, so another object coincident with it is at d = 0 and is returned.

An infinite Rmax is accepted and selects every object from Rmin outwards.

Parameters:

  • index – the object to measure from, itself excluded

  • Rmax – outer radius, inclusive; +inf is accepted

  • Rmin – inner radius, inclusive; 0 by default, giving a ball

Throws:

  • IndexError – if index is out of range or removed

  • Error – if a radius is negative or NaN, or if Rmin exceeds Rmax

Returns:

the indices, in unspecified order

size_t get_Cell(double X, double Y, double Z) const

Linear index of the cell containing a point.

Throws:

Error – if the point is outside the box

std::array<unsigned int, 3> get_CellCoords(double X, double Y, double Z) const

Cell coordinates {ix, iy, iz} of the cell containing a point.

Throws:

Error – if the point is outside the box

std::vector<unsigned int> get_ObjectsInCell(double X, double Y, double Z) const

Objects in the cell containing a point.

Throws:

Error – if the point is outside the box

void removeObject(unsigned int index)

Remove an object from the grid.

Its coordinates are retained but unreachable, and its index stays invalid for the lifetime of the grid.

Throws:

IndexError – if index is out of range or already removed

unsigned int addObject(double X, double Y, double Z)

Add an object to the grid.

The box is not refitted. Indices of removed objects are not reused, so their storage is not reclaimed.

Throws:

Error – if the point is outside the box, or if 4294967295 indices have already been issued

Returns:

its index, one past the highest ever issued

Errors

class Error : public std::runtime_error

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

Subclassed by meshsearch::IndexError

Public Functions

explicit Error(const std::string &what)
Parameters:

what – the message, returned by what()

class IndexError : public meshsearch::Error

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

Public Functions

explicit IndexError(const std::string &what)
Parameters:

what – the message, returned by what()

Supporting types

struct GridOffset

Cell offset relative to a target cell. Implementation detail, not part of the interface.

Public Members

int i

offset along x, in cells

int j

offset along y, in cells

int k

offset along z, in cells