Provides functionality to store and operate on mesh node coordinates. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/latest/src/axom/mint/mesh/MeshCoordinates.hpp>

Public Member Functions
	~MeshCoordinates ()
	Destructor, free's the allocated vectors. More...

void	append (const double *coords, IndexType n=1)
	Appends multiple nodes to the MeshCoordinates instance. More...

void	insert (IndexType nodeID, const double *coords, IndexType n=1)
	Inserts multiple nodes to the MeshCoordinates instance. More...

double	getCoordinate (IndexType nodeID, int dim) const
	Returns the coordinate of a point at the given dimension. More...

void	getCoordinates (IndexType nodeID, double *coords) const
	Copy the coordinates of the given node into the provided buffer. More...

Native Storage Constructors
	MeshCoordinates (int dimension, IndexType numNodes=0, IndexType capacity=USE_DEFAULT)
	Creates a MeshCoordinates instance of specified dimension and given number of nodes. Optionally, an initial max capacity may be specified in the constructor to reserve additional space for storing nodes. If a capacity is not specified, an internal initial default capacity will be computed instead. More...

External Storage Constructors
	MeshCoordinates (IndexType numNodes, IndexType capacity, double x, double y=nullptr, double *z=nullptr)
	Creates a MeshCoordinates object from the given coordinate buffers. More...

	MeshCoordinates (IndexType numNodes, double x, double y=nullptr, double *z=nullptr)

Attribute get/set Methods
int	dimension () const
	Returns the dimension of this MeshCoordinates instance. More...

IndexType	numNodes () const
	Returns the number of nodes in this MeshCoordinates instance. More...

void	resize (IndexType size)
	Changes the number of nodes to the specified size. More...

IndexType	capacity () const
	Get the maximum number of points that can currently be held. More...

void	reserve (IndexType capacity)
	Changes the max capacity to the specified capacity. More...

void	shrink ()
	Returns all extra memory to the system. More...

double	getResizeRatio () const
	Returns the resize ratio by which the capacity will increase. More...

void	setResizeRatio (double ratio)
	Sets the resize ratio by which the capacity will increase when a dynamically re-allocation is triggered. More...

bool	empty () const

bool	isExternal () const
	Return true iff constructed via the external constructor. More...

bool	isInSidre () const
	Return true iff constructed via the sidre constructors. More...

Data Access Methods
IndexType	append (double x)
	Appends a new node to the MeshCoordinates instance. More...

IndexType	append (double x, double y)

IndexType	append (double x, double y, double z)


void	append (const double x, const double y, IndexType n)
	Appends new nodes to the MeshCoordinates instance. More...

void	append (const double x, const double y, const double *z, IndexType n)


void	set (IndexType nodeID, double x)
	Sets the coordinates for the given node. More...

void	set (IndexType nodeID, double x, double y)

void	set (IndexType nodeID, double x, double y, double z)


void	insert (IndexType nodeID, double x)
	Insert a node to the MeshCoordinates instance. More...

void	insert (IndexType nodeID, double x, double y)

void	insert (IndexType nodeID, double x, double y, double z)


void	insert (IndexType nodeID, const double x, const double y, IndexType n)
	Insert multiple nodes to the MeshCoordinates instance. More...

void	insert (IndexType nodeID, const double x, const double y, const double *z, IndexType n)


double *	getCoordinateArray (int dim)
	Returns pointer to the coordinate array at the requested dimension. More...

const double *	getCoordinateArray (int dim) const

Detailed Description

Provides functionality to store and operate on mesh node coordinates.

A MeshCoordinates object is generally tied to an associated Mesh instance and provides the means to store, access and modify the node coordinates of a mesh.

The MeshCoordinates object may be constructed using (a) native storage, (b) external storage, or, (c) Sidre:

Native Storage

When using native storage, the MeshCoordinates object owns all associated memory. The storage can dynamically grow as needed, e.g., when adding more nodes. Typically, extra space is allocated to minimize the number of re-allocations. At any given instance, the total node capacity can be queried by calling the capacity() function. The extra memory can be returned to the system by calling the shrink() method.

When all extra memory is exhausted, appending a new node triggers a re-allocation. The amount of extra space that is allocated is according to the resize_ratio parameter, which is set to 2.0 by default. The resize_ratio may be queried and set to a different value by the getResizeRatio() and setResizeRatio() functions respectively.

When the MeshCoordinates object goes out-of-scope, all memory associated with the given instance is returned to the system.
External Storage

A MeshCoordinates object may also be constructed from external, user-supplied buffers that store the mesh node coordinates. In this case, the memory is owned by the caller. The MeshCoordinates object just keeps pointers to the user-supplied buffers.

Warning
Since the memory is not owned by the MeshCoordinates object when external buffers are supplied, the MeshCoordinates object cannot dynamically grow the storage. Consequently, the number of nodes the MeshCoordinates instance can hold is fixed. All calls to shrink() and reserve() will fail.

Moreover, when the MeshCoordinates object goes out-of-scope, the associated buffers are not deleted. The caller owns the external data and has the responsibility of properly de-allocating the associated memory.
Sidre

A MeshCoordinates object may also be constructed from a sidre::Group which conforms to the mesh blueprint .

A MeshCoordinates object that is bound to a particular sidre::Group supports all operations transparently including dynamically growing the storage to hold more nodes as needed, but, instead, Sidre owns the memory. All memory management operations are delegated to Sidre.

Warning
Once the MeshCoordinates object goes out-of-scope, the data stays remains persistent in Sidre.

Reallocations tend to be costly operations in terms of performance. Use reserve() when the number of nodes is known a priori, or opt to use a constructor that takes an actual size and capacity when possible.

See also
axom::deprecated::MCArray

mint::Mesh

sidre::Group

sidre::deprecated::MCArray

Constructor & Destructor Documentation

◆ MeshCoordinates() [1/3]

axom::mint::MeshCoordinates::MeshCoordinates	(	int	dimension,
		IndexType	numNodes = `0`,
		IndexType	capacity = `USE_DEFAULT`
	)

explicit

Creates a MeshCoordinates instance of specified dimension and given number of nodes. Optionally, an initial max capacity may be specified in the constructor to reserve additional space for storing nodes. If a capacity is not specified, an internal initial default capacity will be computed instead.

Parameters

[in]	dimension	the mesh dimension.
[in]	numNodes	the number of nodes this instance will hold initially
[in]	capacity	initial max capacity to reserve space for (optional).

Precondition: 1 <= dimension() <= 3

Postcondition: numNodes() <= capacity(); numNodes() == numNodes; if capacity == USE_DEFAULT then capacity() == max(DEFAULT_CAPACITY, numNodes()*DEFAULT_RESIZE_RATIO)

◆ MeshCoordinates() [2/3]

axom::mint::MeshCoordinates::MeshCoordinates	(	IndexType	numNodes,
		IndexType	capacity,
		double *	x,
		double *	y = `nullptr`,
		double *	z = `nullptr`
	)

Creates a MeshCoordinates object from the given coordinate buffers.

Parameters

[in]	numNodes	the number of nodes in the supplied array
[in]	capacity	the actual node capacity on the supplied buffers.
[in]	x	pointer to the x-coordinates
[in]	y	pointer to the y-coordinates, may be nullptr if 1D
[in]	z	pointer to the z-coordinates, may be nullptr if 2D or 1D

Warning: This constructor wraps the given coordinate buffers and does not own the data. Consequently, new nodes cannot be added to this MeshCoordinates instance when using this constructor.; All calls to shrink(), append(), resize() and reserve() will fail.

Precondition: x != nullptr; y != nullptr if dimension==2 || dimension==3; z != nullptr if dimension==3; numNodes >= 1

Postcondition: 1 <= dimension() <= 3; empty() == false; numNodes() == numNodes; numNodes() <= capacity()

◆ MeshCoordinates() [3/3]

axom::mint::MeshCoordinates::MeshCoordinates	(	IndexType	numNodes,
		double *	x,
		double *	y = `nullptr`,
		double *	z = `nullptr`
	)

◆ ~MeshCoordinates()

axom::mint::MeshCoordinates::~MeshCoordinates ( )

Destructor, free's the allocated vectors.

Member Function Documentation

◆ dimension()

int axom::mint::MeshCoordinates::dimension ( ) const

inline

Returns the dimension of this MeshCoordinates instance.

Returns: dim the dimension

Postcondition: 1 <= dim <= 3

◆ numNodes()

IndexType axom::mint::MeshCoordinates::numNodes ( ) const

inline

Returns the number of nodes in this MeshCoordinates instance.

Returns: N the number of nodes in this MeshCoordinates instance.

◆ resize()

void axom::mint::MeshCoordinates::resize ( IndexType size )

inline

Changes the number of nodes to the specified size.

Postcondition: numNodes()==size; numNodes() <= capacity()

References SLIC_ASSERT.

◆ capacity()

IndexType axom::mint::MeshCoordinates::capacity ( ) const

inline

Get the maximum number of points that can currently be held.

Returns: N the capacity of m_coordinates.

Postcondition: N >= numNodes()

◆ reserve()

void axom::mint::MeshCoordinates::reserve ( IndexType capacity )

inline

Changes the max capacity to the specified capacity.

Warning: The reserve() operation is invalid when a MeshCoordinates object is constructed using external buffers. Since, in this case the object does not own the associated memory, dynamic resizing is not allowed.

Parameters

[in] capacity the new max node capacity.

Postcondition: capacity() == capacity; numNodes() <= capacity()

References capacity(), isExternal(), SLIC_ASSERT, and SLIC_ERROR_IF.

◆ shrink()

void axom::mint::MeshCoordinates::shrink ( )

inline

Returns all extra memory to the system.

Warning: The shrink() operation is invalid when a MeshCoordinates object is constructed using external buffers. Since, in this case the object does not own the associated memory, dynamic resizing is not allowed.

Postcondition: numNodes() == capacity()

References SLIC_ASSERT.

◆ getResizeRatio()

double axom::mint::MeshCoordinates::getResizeRatio ( ) const

inline

Returns the resize ratio by which the capacity will increase.

Returns: N the ratio by which the capacity will increase

See also: Array::getResizeRatio()

◆ setResizeRatio()

void axom::mint::MeshCoordinates::setResizeRatio ( double ratio )

inline

Sets the resize ratio by which the capacity will increase when a dynamically re-allocation is triggered.

Parameters

[in] ratio the ratio by which the capacity will increase

See also: Array::setResizeRatio()

References SLIC_ASSERT.

◆ empty()

bool axom::mint::MeshCoordinates::empty ( ) const

inline

References numNodes().

◆ isExternal()

bool axom::mint::MeshCoordinates::isExternal ( ) const

inline

Return true iff constructed via the external constructor.

References SLIC_WARNING_IF.

◆ isInSidre()

bool axom::mint::MeshCoordinates::isInSidre ( ) const

inline

Return true iff constructed via the sidre constructors.

References SLIC_WARNING_IF.

◆ append() [1/6]

IndexType axom::mint::MeshCoordinates::append ( double x )

inline

Appends a new node to the MeshCoordinates instance.

Parameters

[in]	x	the first coordinate to append.
[in]	y	the second coordinate to append.
[in]	z	the third coordinate to append.

Note: Each method is valid only for the appropriate dimension of the mesh.

Postcondition: the number of nodes is incremented by one.

References dimension(), numNodes(), and SLIC_ASSERT.

◆ append() [2/6]

IndexType axom::mint::MeshCoordinates::append	(	double	x,
		double	y
	)

inline

References dimension(), numNodes(), and SLIC_ASSERT.

◆ append() [3/6]

IndexType axom::mint::MeshCoordinates::append	(	double	x,
		double	y,
		double	z
	)

inline

References dimension(), numNodes(), and SLIC_ASSERT.

◆ append() [4/6]

void axom::mint::MeshCoordinates::append	(	const double *	coords,
		IndexType	n = `1`
	)

inline

Appends multiple nodes to the MeshCoordinates instance.

Parameters

[in]	coords	pointer to the nodes to append, of length n * getDimension().
[in]	n	the number of nodes to append.

Note: coords is assumed to be in the array of structs format, ie coords = {x0, y0, z0, x1, y1, z1, ..., xn, yn, zn}.

Precondition: coords != nullptr; n >= 0

References getCoordinateArray(), numNodes(), and SLIC_ASSERT.

◆ append() [5/6]

void axom::mint::MeshCoordinates::append	(	const double *	x,
		const double *	y,
		IndexType	n
	)

inline

Appends new nodes to the MeshCoordinates instance.

Parameters

[in]	x	array of the first coordinates to append, of length n.
[in]	y	array of the second coordinates to append, of length n.
[in]	z	array of the third coordinates to append, of length n.
[in]	n	the number of coordinates to append.

Note: The first method is only valid for 2D meshes while the second is only for 3D.

Precondition: x != nullptr; y != nullptr; z != nullptr; n >= 0

Postcondition: the number of nodes is incremented by n

References SLIC_ASSERT.

◆ append() [6/6]

void axom::mint::MeshCoordinates::append	(	const double *	x,
		const double *	y,
		const double *	z,
		IndexType	n
	)

inline

References SLIC_ASSERT.

◆ set() [1/3]

void axom::mint::MeshCoordinates::set	(	IndexType	nodeID,
		double	x
	)

inline

Sets the coordinates for the given node.

Parameters

[in]	nodeID	the index of the node whose coordinates to set.
[in]	x	the new value of the first coordinate.
[in]	y	the new value of the second coordinate.
[in]	z	the new value of the third coordinate.

Note: Each method is valid only for the appropriate dimension of the mesh.

Postcondition: idx >=0 && idx == numNodes()-1

References dimension(), and SLIC_ASSERT.

◆ set() [2/3]

void axom::mint::MeshCoordinates::set	(	IndexType	nodeID,
		double	x,
		double	y
	)

inline

References dimension(), and SLIC_ASSERT.

◆ set() [3/3]

void axom::mint::MeshCoordinates::set	(	IndexType	nodeID,
		double	x,
		double	y,
		double	z
	)

inline

References dimension(), and SLIC_ASSERT.

◆ insert() [1/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		double	x
	)

inline

Insert a node to the MeshCoordinates instance.

Parameters

[in]	nodeID	the position to insert at.
[in]	x	the value of the first coordinate to insert.
[in]	y	the value of the second coordinate to insert.
[in]	z	the value of the third coordinate to insert.

Note: Each method is valid only for the appropriate dimension of the mesh.

Precondition: 0 <= nodeID <= getNumberOfNodes

Postcondition: the number of nodes is incremented by 1

References dimension(), numNodes(), and SLIC_ASSERT.

◆ insert() [2/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		double	x,
		double	y
	)

inline

References dimension(), numNodes(), and SLIC_ASSERT.

◆ insert() [3/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		double	x,
		double	y,
		double	z
	)

inline

References dimension(), numNodes(), and SLIC_ASSERT.

◆ insert() [4/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		const double *	coords,
		IndexType	n = `1`
	)

inline

Inserts multiple nodes to the MeshCoordinates instance.

Parameters

[in]	coords	pointer to the nodes to insert, of length n * getDimension().
[in]	n	the number of nodes to append.

Note: coords is assumed to be in the array of structs format, ie coords = {x0, y0, z0, x1, y1, z1, ..., xn, yn, zn}.

Precondition: 0 <= nodeID <= getNumberOfNodes; coords != nullptr; n >= 0

Postcondition: the number of nodes is incremented by n

References getCoordinateArray(), numNodes(), and SLIC_ASSERT.

◆ insert() [5/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		const double *	x,
		const double *	y,
		IndexType	n
	)

inline

Insert multiple nodes to the MeshCoordinates instance.

Parameters

[in]	nodeID	the position to insert at.
[in]	x	the array of the first coordinates to insert.
[in]	y	the array of the second coordinates to insert.
[in]	z	the array of the third coordinates to insert.
[in]	n	the number of nodes to insert.

Precondition: getDimension() == 3; 0 <= nodeID <= getNumberOfNodes x != nullptr y != nullptr z != nullptr; n >= 0

Postcondition: the number of nodes is incremented by n

References numNodes(), and SLIC_ASSERT.

◆ insert() [6/6]

void axom::mint::MeshCoordinates::insert	(	IndexType	nodeID,
		const double *	x,
		const double *	y,
		const double *	z,
		IndexType	n
	)

inline

References numNodes(), and SLIC_ASSERT.

◆ getCoordinate()

double axom::mint::MeshCoordinates::getCoordinate	(	IndexType	nodeID,
		int	dim
	)		const

inline

Returns the coordinate of a point at the given dimension.

Parameters

[in]	nodeID	the index of the point in query.
[in]	dim	the dimension in query.

Returns: coord the coordinate of the point.

Precondition: dim < m_ndims; (nodeID >= 0) && (nodeID < getNumberOfPoints())

References numNodes(), and SLIC_ASSERT.

◆ getCoordinates()

void axom::mint::MeshCoordinates::getCoordinates	(	IndexType	nodeID,
		double *	coords
	)		const

inline

Copy the coordinates of the given node into the provided buffer.

Parameters

[in]	nodeID	the ID of the node in question.
[in]	coords	the buffer to copy the coordinates into, of length at least getDimension().

Precondition: 0 <= nodeID < getNumberOfNodes(); coords != nullptr

References getCoordinate(), and SLIC_ASSERT.

◆ getCoordinateArray() [1/2]

double* axom::mint::MeshCoordinates::getCoordinateArray ( int dim )

inline

Returns pointer to the coordinate array at the requested dimension.

Parameters

[in] dim the requested dimension.

Returns: coord_array pointer to the coordinate array

Precondition: dim < m_ndims

Postcondition: coord_array != nullptr.

References SLIC_ASSERT, and SLIC_ERROR_IF.

◆ getCoordinateArray() [2/2]

const double* axom::mint::MeshCoordinates::getCoordinateArray ( int dim ) const

inline

References SLIC_ASSERT, and SLIC_ERROR_IF.

The documentation for this class was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/latest/src/axom/mint/mesh/MeshCoordinates.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ MeshCoordinates() [1/3]

◆ MeshCoordinates() [2/3]

◆ MeshCoordinates() [3/3]

◆ ~MeshCoordinates()

Member Function Documentation

◆ dimension()

◆ numNodes()

◆ resize()

◆ capacity()

◆ reserve()

◆ shrink()

◆ getResizeRatio()

◆ setResizeRatio()

◆ empty()

◆ isExternal()

◆ isInSidre()

◆ append() [1/6]

◆ append() [2/6]

◆ append() [3/6]

◆ append() [4/6]

◆ append() [5/6]

◆ append() [6/6]

◆ set() [1/3]

◆ set() [2/3]

◆ set() [3/3]

◆ insert() [1/6]

◆ insert() [2/6]

◆ insert() [3/6]

◆ insert() [4/6]

◆ insert() [5/6]

◆ insert() [6/6]

◆ getCoordinate()

◆ getCoordinates()

◆ getCoordinateArray() [1/2]

◆ getCoordinateArray() [2/2]