peano4::datamanagement::VertexMarker Struct Reference

Vertex marker to provide information about selected vertex. More...

#include <VertexMarker.h>

Collaboration diagram for peano4::datamanagement::VertexMarker:

Public Member Functions
	VertexMarker (const ::peano4::grid::GridTraversalEvent &event, int select=0)
	VertexMarker (const VertexMarker &marker, int select)
	Copy over another marker, but select a different vertex.
VertexMarker &	select (int number)
	Picks a vertex within a cell.
int	getSelectedVertexNumber () const
	Information about selected vertex.
tarch::la::Vector< Dimensions, double >	x (int i) const
	We do enumerate the vertices in a lexicographic way, i.e.
tarch::la::Vector< Dimensions, double >	x () const
bool	isParentOfSubtree (int i) const
bool	isParentOfSubtree () const
tarch::la::Vector< Dimensions, double >	h () const
std::string	toString () const
bool	hasBeenRefined () const
	A vertex is refined iff it is surrounded by \( 2^d \) cells which are refined.
bool	hasBeenRefined (int i) const
bool	willBeRefined () const
bool	willBeRefined (int i) const
int	getNumberOfAdjacentTrees () const
	Number of adjacent trees of current vertex.
int	getNumberOfAdjacentTrees (int i) const
bool	isLocal () const
bool	isLocal (int i) const
	Is a vertex local, i.e.
bool	isHanging () const
bool	isHanging (int i) const
bool	isAdjacentToParallelDomainBoundary () const
	Is currently selected/analysed vertex adjacent to parallel domain boundary.
bool	isAdjacentToParallelDomainBoundary (int i) const
	Is one vertex of cell adjacent to parallel domain boundary.
bool	isParentCellLocal () const
	Whenever we touch a vertex the first or the last time, we touch it from a cell: If we touch a vertex the first time, the traversal is just about to enter a cell and sees that one of its vertices is not loaded yet.
bool	isParentVertexLocal (int i) const
	Is the parent vertex local.
tarch::la::Vector< Dimensions, int >	getRelativePositionWithinFatherCell () const
	Relative position within parent cell.
tarch::la::Vector< Dimensions, int >	getRelativePositionWithinFatherCell (int i) const
bool	coincidesWithCoarseGridVertex () const
	Does vertex spatially coincide with coarser level's vertex.
bool	isContainedInAdjacentCells (const tarch::la::Vector< Dimensions, double > &x, double scaleAdjacentCells=1.0, double tolerance=tarch::la::NUMERICAL_ZERO_DIFFERENCE) const
	Will return true if x is contained within the adjacent cells.
bool	isContainedInAdjacentCellsByDimension (const tarch::la::Vector< Dimensions, double > &x, const int dim, double scaleAdjacentCells=1.0, double tolerance=tarch::la::NUMERICAL_ZERO_DIFFERENCE) const
	One-dimensional version of isContainedInAdjacentCells()
tarch::la::Vector< Dimensions, int >	getRelativeAdjacentCell (const tarch::la::Vector< Dimensions, double > &x) const
	Each vertex is surrounded by \( 2^d \) cells.
tarch::la::Vector< Dimensions, double >	getInvokingCellCentre () const
	Return centre of cell from which this vertex marker is constructed.
tarch::la::Vector< Dimensions, double >	getInvokingParentCellsCentre () const
	See getInvokingCellCentre().
std::bitset< TwoPowerD >	areAdjacentCellsLocal () const
	Are adjacent cells of selected vertex local.

Private Member Functions
bool	isParentLocal () const
	VertexMarker ()=default
	Some unit tests prefer to construct a marker manually, so I offer a dummy default constructor.

Private Attributes
tarch::la::Vector< Dimensions, double >	_cellCentre
	Centre of the underlying cell.
tarch::la::Vector< Dimensions, double >	_h
	Size of the underlying cell.
int	_select
std::bitset< TwoPowerD >	_hasBeenRefined
std::bitset< TwoPowerD >	_willBeRefined
std::bitset< TwoPowerD >	_isLocal
std::bitset< TwoPowerD >	_isHanging
std::bitset< TwoPowerD >	_isParentVertexLocal
std::bitset< ThreePowerD >	_isAdjacentCellLocal
std::bitset< TwoPowerD >	_isParentOfSubtree
bool	_isParentCellLocal
std::bitset< TwoPowerD >	_isAdjacentToParallelDomainBoundary
tarch::la::Vector< Dimensions, int >	_relativePositionOfCellWithinFatherCell
	Entries from (0,1,2).
tarch::la::Vector< TwoPowerD, int >	_numberOfAdjacentTrees
	Number of adjacent trees per vertex.

Friends
class	toolbox::particles::tests::MultiscaleTransitionsTest
	For unit tests.
class	toolbox::particles::tests::TestHelpers

Detailed Description

Vertex marker to provide information about selected vertex.

A vertex marker is handed into each and every observer/action set routine which is vertex-based. That is routines such as touchVertexFirstTime(). The marker provides information about the underlying vertex.

Notably, we can provide

• geometric information such as the position of a vertex or the size of the adjacent cells.
• status information such as whether a vertex is hanging.
• grid layout information such as the vertex's position within the parent cell.

Rationale

Peano's events (observer and action set routines) are internally all implemented on a per cell basis. So we invoke touchVertexFirstTime() from the cell when the first adjacent cell of a vertex is entered. Therefore, we know the selected vertex.

Peano runs through the mesh with a tree automaton. A lot of information about vertices thus is recomputed on-the-fly all the time, as it is easy to derive it from the context. We know, for example, from the state of the traversal automaton if a vertex is hanging or not or which position in space it has. Therefore, such information is not stored within the vertex (unless for debugging purposes). Not only would the information be redundant, it would also be very inefficient: If you work with k data records per vertex, each one would hold the same information about the underlying vertex's position. So it makes more sense to encode such information with a separate object.

See also

FaceMarker for the analogous information for faces.

Definition at line 90 of file VertexMarker.h.

Constructor & Destructor Documentation

VertexMarker() [1/3]

peano4::datamanagement::VertexMarker::VertexMarker ( )

privatedefault

Some unit tests prefer to construct a marker manually, so I offer a dummy default constructor.

The normal code should and does not use a default constructor.

VertexMarker() [2/3]

peano4::datamanagement::VertexMarker::VertexMarker	(	const ::peano4::grid::GridTraversalEvent &	event,
		int	select = 0 )

VertexMarker() [3/3]

peano4::datamanagement::VertexMarker::VertexMarker	(	const VertexMarker &	marker,
		int	select )

Copy over another marker, but select a different vertex.

Member Function Documentation

areAdjacentCellsLocal()

std::bitset< TwoPowerD > peano4::datamanagement::VertexMarker::areAdjacentCellsLocal

(

)

const

Are adjacent cells of selected vertex local.

Correctness

I originally thought I could add the assertion

assertion2( result.all() or isAdjacentToParallelDomainBoundary(), result, toString() );

However, this assertion fails at the global domain boundary, where some adjacent cells are not local (they are outside) and the vertices nevertheless are not parallel boundary vertices either.

coincidesWithCoarseGridVertex()

bool peano4::datamanagement::VertexMarker::coincidesWithCoarseGridVertex

(

)

const

Does vertex spatially coincide with coarser level's vertex.

The vertex (0,0,0) coincides with a coarse grid vertex, the (3,0,0) does so too, and so forth.

Frequent use case

If you want to program some simply injection, it helps to identify vertices which coincide spatially with vertices on the next coarser level. A classic are codes like

if ( marker.coincidesWithCoarseGridVertex() ) {
  tarch::la::Vector<Dimensions,int> parent = marker.getRelativePositionWithinFatherCell() / 3;
  coarseGridVerticesX( peano4::utils::dLinearised(parent,2) ).set...
}

within touchVertexLastTime. This snippet looks if two vertices coincide spatially. If so, it computes the parent's relative position within the parent cell which is simply a division by 3. We then linearise this vector index and thus have access to the parent.

getInvokingCellCentre()

tarch::la::Vector< Dimensions, double > peano4::datamanagement::VertexMarker::getInvokingCellCentre

(

)

const

Return centre of cell from which this vertex marker is constructed.

Peano runs through the mesh element-wisely. That is, each touchVertexFirstTime() and touchVertexLastTime() is called from a cell. It looks at its \( 2^d \) adjacent vertices and then invokes the vertex events for these vertices if necessary. This routine yields the centre of this cell.

getInvokingParentCellsCentre()

tarch::la::Vector< Dimensions, double > peano4::datamanagement::VertexMarker::getInvokingParentCellsCentre

(

)

const

See getInvokingCellCentre().

This routine gives you the centre of its parent cell.

getNumberOfAdjacentTrees() [1/2]

int peano4::datamanagement::VertexMarker::getNumberOfAdjacentTrees

(

)

const

Number of adjacent trees of current vertex.

This routine is valid if and only if you call it for a local, non-hanging vertex. Otherwise, its behaviour is undefined (and will actually trigger an assertion).

getNumberOfAdjacentTrees() [2/2]

int peano4::datamanagement::VertexMarker::getNumberOfAdjacentTrees

(

int

i

)

const

getRelativeAdjacentCell()

tarch::la::Vector< Dimensions, int > peano4::datamanagement::VertexMarker::getRelativeAdjacentCell

(

const tarch::la::Vector< Dimensions, double > &

x

)

const

Each vertex is surrounded by \( 2^d \) cells.

In reality, it might be fewer of them, as we might have to deal with a hanging vertex, but logically we can always assume that there were \( 2^d \). Let's assume that they are grouped lexicographically around the vertex, i.e. we have

2 | 3
--+--
0 | 1

cells centred around a central vertex denoted by the plus in this fancy ASCII art. If x falls into the cell 1, this routine would return (1,0). If it falls into cell 3, it would return (1,1).

getRelativePositionWithinFatherCell() [1/2]

tarch::la::Vector< Dimensions, int > peano4::datamanagement::VertexMarker::getRelativePositionWithinFatherCell

(

)

const

Relative position within parent cell.

Return relative position within father cell. The result is from (0,1,2,3)^d and denotes the vertex position within a 3x3 or 3x3x3 respectively mesh.

You can reconstruct the left bottom vertex of the coarser cell through

marker.x() - tarch::la::multiplyComponents(
  tarch::la::convertScalar<double>(marker.getRelativePositionWithinFatherCell()),
  marker.h()
)

If you want to know a particular position of a coarse grid vertex identified through the bitset target, you can do through

marker.x()
-
tarch::la::multiplyComponents(
  tarch::la::convertScalar<double>(marker.getRelativePositionWithinFatherCell()),
  marker.h()
)
+
tarch::la::multiplyComponents(
  tarch::la::Vector<Dimensions,double>(target),
  3.0*marker.h()
)

See also

coincidesWithCoarseGridVertex()

getRelativePositionWithinFatherCell() [2/2]

tarch::la::Vector< Dimensions, int > peano4::datamanagement::VertexMarker::getRelativePositionWithinFatherCell

(

int

i

)

const

getSelectedVertexNumber()

int peano4::datamanagement::VertexMarker::getSelectedVertexNumber

(

)

const

Information about selected vertex.

Even though you are given a vertex marker for a vertex routine such as touchVertexFirstTime(), Peano behind the scenes invokes this routine from a cell. That is, it enters a cell, then runs over all \( 2^d \) adjacent vertex and puzzles out for each vertex if it has to call touchVertexFirstTime() or not.

getSelectedVertexNumber() tells you which logical number a vertex has within the underlying cell behind the scenes.

The routine is barely used by user codes. Some technical helper routines use the selected number for some arithmetics, but the code indeed might be cleaner if we did hide this routine from the user altogether and make the routine explicitly available only to friends.

h()

tarch::la::Vector< Dimensions, double > peano4::datamanagement::VertexMarker::h

(

)

const

hasBeenRefined() [1/2]

bool peano4::datamanagement::VertexMarker::hasBeenRefined

(

)

const

A vertex is refined iff it is surrounded by \( 2^d \) cells which are refined.

hasBeenRefined() [2/2]

bool peano4::datamanagement::VertexMarker::hasBeenRefined

(

int

i

)

const

isAdjacentToParallelDomainBoundary() [1/2]

bool peano4::datamanagement::VertexMarker::isAdjacentToParallelDomainBoundary

(

)

const

Is currently selected/analysed vertex adjacent to parallel domain boundary.

isAdjacentToParallelDomainBoundary() [2/2]

bool peano4::datamanagement::VertexMarker::isAdjacentToParallelDomainBoundary

(

int

i

)

const

Is one vertex of cell adjacent to parallel domain boundary.

Peano runs through the mesh cell by cell. Within a cell, you can ask if the ith vertex actually is adjacent to a parallel domain boundary.

isContainedInAdjacentCells()

bool peano4::datamanagement::VertexMarker::isContainedInAdjacentCells	(	const tarch::la::Vector< Dimensions, double > &	x,
		double	scaleAdjacentCells = 1.0,
		double	tolerance = tarch::la::NUMERICAL_ZERO_DIFFERENCE ) const

Will return true if x is contained within the adjacent cells.

You can use shrink those cells via the additional parameter if you want.

The geometric operation is defined over the closed interval, i.e. we look into the adjacent cubes to the vertex and their faces still count as "inside". If x is exactly on the face of a cube adjacent to the vertex, we will get back a true. Indeed, the cubes are even slightly bigger due to machine precision.

isContainedInAdjacentCellsByDimension()

bool peano4::datamanagement::VertexMarker::isContainedInAdjacentCellsByDimension	(	const tarch::la::Vector< Dimensions, double > &	x,
		const int	dim,
		double	scaleAdjacentCells = 1.0,
		double	tolerance = tarch::la::NUMERICAL_ZERO_DIFFERENCE ) const

One-dimensional version of isContainedInAdjacentCells()

Same as isContainedInAdjacentCells(), but only checks along a single dimension provided by int dim. This variant is sometimes way faster, as it only checks the direction of interest.

Parameters

dim	Positive integer with 0 <= dim < Dimensions which indicates the search direction.

isHanging() [1/2]

bool peano4::datamanagement::VertexMarker::isHanging

(

)

const

isHanging() [2/2]

bool peano4::datamanagement::VertexMarker::isHanging

(

int

i

)

const

isLocal() [1/2]

bool peano4::datamanagement::VertexMarker::isLocal

(

)

const

See also

isLocal(int) for currently selected/represented vertex

isLocal() [2/2]

bool peano4::datamanagement::VertexMarker::isLocal

(

int

i

)

const

Is a vertex local, i.e.

not adjacent to any boundary or remote

isParentCellLocal()

bool peano4::datamanagement::VertexMarker::isParentCellLocal

(

)

const

Whenever we touch a vertex the first or the last time, we touch it from a cell: If we touch a vertex the first time, the traversal is just about to enter a cell and sees that one of its vertices is not loaded yet.

When we issue a touchVertexLastTime() event, the traversal is just about to leave a cell.

So there's a cell state associated with any vertex event, and, therefore, we know if the corresponding cell is local and whether its parent cell is local.

See also

isParentVertexLocal()

isParentLocal()

bool peano4::datamanagement::VertexMarker::isParentLocal ( ) const

private

isParentOfSubtree() [1/2]

bool peano4::datamanagement::VertexMarker::isParentOfSubtree

(

)

const

isParentOfSubtree() [2/2]

bool peano4::datamanagement::VertexMarker::isParentOfSubtree

(

int

i

)

const

isParentVertexLocal()

bool peano4::datamanagement::VertexMarker::isParentVertexLocal

(

int

i

)

const

Is the parent vertex local.

Is a parent vertex local, i.e. not adjacent to any boundary or remote. Peano traverses the tree in a strict octant-wise (multiscale-wise) order. That is, whenever you receive a touchVertexFirstTime() or touchVertexLastTime() event, the Peano core has actually entered a cell and recognised "whoops, I haven't used that vertex yet" or "this will be the last time this vertex is available". See the generic event description on an overview of all of these events.

As a logical consequence, there are always \( 2^d \) parent vertices when you encounter a vertex for the first or last time. But you never know which parent cell it will be. The code could have stepped down from A into a or from B into b. So the parent vertices could be the green or the blue ones.

This routine allows you to find out if these vertices are local. It will always return if isParentCellLocal() does not hold.

select()

VertexMarker & peano4::datamanagement::VertexMarker::select

(

int

number

)

Picks a vertex within a cell.

After that, the routine returns.

This routine is only called by Peano's internal observer, i.e. the class constructing VertexMarker objects. Users never call this routine.

toString()

std::string peano4::datamanagement::VertexMarker::toString

(

)

const

willBeRefined() [1/2]

bool peano4::datamanagement::VertexMarker::willBeRefined

(

)

const

willBeRefined() [2/2]

bool peano4::datamanagement::VertexMarker::willBeRefined

(

int

i

)

const

x() [1/2]

tarch::la::Vector< Dimensions, double > peano4::datamanagement::VertexMarker::x

(

)

const

Returns

Position in space of currently selected vertex.

x() [2/2]

tarch::la::Vector< Dimensions, double > peano4::datamanagement::VertexMarker::x

(

int

i

)

const

We do enumerate the vertices in a lexicographic way, i.e.

we start with the bottom left vertex. Then we run along the first Cartesian axis, then the second, and so forth. This yields a z-pattern for the enumeration.

Returns

Position of ith vertex

Friends And Related Symbol Documentation

toolbox::particles::tests::MultiscaleTransitionsTest

friend class toolbox::particles::tests::MultiscaleTransitionsTest

friend

For unit tests.

Definition at line 95 of file VertexMarker.h.

toolbox::particles::tests::TestHelpers

friend class toolbox::particles::tests::TestHelpers

friend

Definition at line 96 of file VertexMarker.h.

Field Documentation

_cellCentre

tarch::la::Vector<Dimensions, double> peano4::datamanagement::VertexMarker::_cellCentre

private

Centre of the underlying cell.

Definition at line 101 of file VertexMarker.h.

_h

tarch::la::Vector<Dimensions, double> peano4::datamanagement::VertexMarker::_h

private

Size of the underlying cell.

Definition at line 106 of file VertexMarker.h.

_hasBeenRefined

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_hasBeenRefined

private

Definition at line 110 of file VertexMarker.h.

_isAdjacentCellLocal

std::bitset<ThreePowerD> peano4::datamanagement::VertexMarker::_isAdjacentCellLocal

private

Definition at line 115 of file VertexMarker.h.

_isAdjacentToParallelDomainBoundary

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_isAdjacentToParallelDomainBoundary

private

Definition at line 122 of file VertexMarker.h.

_isHanging

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_isHanging

private

Definition at line 113 of file VertexMarker.h.

_isLocal

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_isLocal

private

Definition at line 112 of file VertexMarker.h.

_isParentCellLocal

bool peano4::datamanagement::VertexMarker::_isParentCellLocal

private

Definition at line 118 of file VertexMarker.h.

_isParentOfSubtree

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_isParentOfSubtree

private

Definition at line 116 of file VertexMarker.h.

_isParentVertexLocal

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_isParentVertexLocal

private

Definition at line 114 of file VertexMarker.h.

_numberOfAdjacentTrees

tarch::la::Vector<TwoPowerD,int> peano4::datamanagement::VertexMarker::_numberOfAdjacentTrees

private

Number of adjacent trees per vertex.

Obviously only relevant/valid if the vertex is local.

Definition at line 133 of file VertexMarker.h.

_relativePositionOfCellWithinFatherCell

tarch::la::Vector<Dimensions, int> peano4::datamanagement::VertexMarker::_relativePositionOfCellWithinFatherCell

private

Entries from (0,1,2).

(0,0) or (0,0,0) is the left, bottom cell.

Definition at line 127 of file VertexMarker.h.

_select

int peano4::datamanagement::VertexMarker::_select

private

Definition at line 108 of file VertexMarker.h.

_willBeRefined

std::bitset<TwoPowerD> peano4::datamanagement::VertexMarker::_willBeRefined

private

Definition at line 111 of file VertexMarker.h.

---

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

• src/peano4/datamanagement/VertexMarker.h