Groups utility routines for translating node and cell indices to / from our internal representation and the Lua model representation used by model files and when printing information (reports & error messages). More...

Enumerations
enum	TranslationSemantics { API , REPORT , IO }
	An enumeration to declare the semantics of the operation that made the index translation call. See the namespace documentation. More...

Functions
int	geomNodeToModel (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal geometry node number, converts that index to a Model index. If the internal node does NOT have a corresponding Model index (can only happen for nodes added at runtime in a partitioned setting), returns 0.

int	nodeToModel (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal node number that is either a geometry node, a ghost node WITH the high bit set or a ghost node in linear format, converts that index to a Model index, where ghost nodes are kept in the input format. If the internal node does NOT have a corresponding Model index (can only happen for nodes added at runtime in a partitioned setting), returns 0 (an otherwise invalid model number).

int	nodeToModel_Ghs_Gn (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal node number that is either a geometry node or a ghost node WITH the high bit set, converts that index to a Model index suitable for printing, where ghost nodes are printed as a negative value (first ghost node is -1, second -2 and so on). If the internal node does NOT have a corresponding Model index (can only happen for nodes added at runtime in a partitioned setting), returns 0 (an otherwise invalid model number).

int	nodeToModel_Gl_Gn (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal node number that is either a geometry node or a ghost node in linear representation, converts that index to a Model index suitable for printing, where ghost nodes are printed as a negative value (first ghost node is -1, second -2 and so on). If the internal node does NOT have a corresponding Model index (can only happen for nodes added at runtime in a partitioned setting), returns 0 (an otherwise invalid model number).

int	nodeToModel_Ghs_Ghs (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal node number that is either a geometry node or a ghost node WITH the high bit set, converts that index to a Model index where ghost nodes also have the high bit set. If the internal node does NOT have a corresponding Model index (can only happen for nodes added at runtime in a partitioned setting), returns 0.

int	cellToModel (int cellId, const GmPCR *pcr, TranslationSemantics semantic)
	Given an internal cell number, converts that index to a Model index. If the internal cell does NOT have a corresponding Model index (can only happen for cells added at runtime in a partitioned setting), returns 0 (an otherwise invalid model number).

int	cellToModel (const GmCell *c, TranslationSemantics semantic)
	Overload for cellToModel(int, ...) getting the PCR object from the mesh associated to the cell.

int	checkedNodeFromModel (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided node id that is either a geometry node, a ghost node WITH the high bit set or a ghost node in linear format, checks the input data and converts it to the internal ordered representation, returning ghost nodes in the input format. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedGeomNodeFromModel (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided geometry node id (no ghost nodes allowed), checks the input data and converts it to the internal ordered representation. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedGeomNodeFromModelSR (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)

int	checkedNodeFromModel_Gn_Ghs (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided node id where ghost nodes are represented as negative values, checks the input data and converts it to the internal ordered representation, returning ghost nodes with their high bit set. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedNodeFromModel_Gn_GhsSR (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)

int	checkedNodeFromModel_Gn_Gl (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided node id where ghost nodes are represented as negative values, checks the input data and converts it to the internal ordered representation, returning ghost nodes as linear values. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedNodeFromModel_Ghs_Ghs (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided node id where ghost nodes are represented with the high bit set, checks the input data and converts it to the internal ordered representation, returning ghost nodes with their high bit set. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedGhostNodeFromModel_Ghc_Ghc (int nodeId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided ghost node id (no geometry nodes allowed), with the high bit CLEARED (a value between 1 and num ghost nodes), checks the input data and converts it to the internal ordered representation. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

int	checkedCellFromModel (int cellId, const GmPCR *pcr, TranslationSemantics semantic)
	Given a user provided cell id, checks the input data and converts it to the internal cell representation. If the cell is invalid (does not belong to the mesh), returns -2. If partitioned, the cell is valid, but does not belong to the current partition, returns -1.

int	checkedCellFromModelSR (int cellId, const GmPCR *pcr, TranslationSemantics semantic)

Detailed Description

Groups utility routines for translating node and cell indices to / from our internal representation and the Lua model representation used by model files and when printing information (reports & error messages).

This conversion includes not only the "0-based" C nature of indices versus the "1-based" Lua nature, but also node and cell index reordering done by a PCR plugin, to enhance performance when running stand alone and to handle partitions when working with MPI.

This utility routines can also check node and cell data provided by the user to check if they really belong to the model.

Besides receiving an index and a PCR object as parameters, a third parameter is used to define the semantics of the operation that made the index translation call. At present, this parameter is ignored. At the future, we might want to use it to enable a version of the bindings API that works with local indices.

IMPORTANT TIP: Node function names are formed using the following syntax: what_ToModel_modifiers or checked_what_FromModel_modifiers_ where "_what_" defines if we are converting nodes or cells and the "_modifiers_" define ghost node behaviour.

A "ToModel" function converts from internal (local, ordered) numbering to a model (Lua) numbering. A "FromModel" function converts from model (Lua) numbering to the internal (local, ordered) numbering. Its "checked" prefix, before the "_what_", indicates that input indices are provided by the user and should be validated by the function. They can also have an SR suffix that stands for "Skip Remote". Those versions behave just like their un-suffixed brothers but returning -1 if the mesh was partitioned, the cell is a remote halo cell or the node is a remote node, and the PCR object was configured to skip those cells / nodes for cell groups, node sets, borders or boundary conditions. SR versions where added only when needed.

For node functions, if "_what_" is equal to "node", the function accepts as input both geometric nodes and ghost nodes. If it is "geomNode", the input is restricted to geometric nodes and if it is "ghostNode", the input is restricted to ghost nodes (with the ghost format defined by the modifiers).

Modifiers are always defined as pairs. The first defines the expected format for ghost node inputs. The second the format for ghost node outputs. Available modifiers are: Ghs - If the index is a ghost node, it should have its HIGH bit SET Ghc - If the index is a ghost node, it should have its HIGH bit CLEAR Gl - If the index is a ghost node, it should be in the LINEAR representation, (a value >= mesh->numNodes() and < mesh->totalNumNodes() in internal
representation and >= mesh->numGlobalNodes() and < mesh->totalNumGlobalNodes() in model representation) Gn - If the index is a ghost node, it should be represented as a negative number (first ghost node is -1, second -2 and so on)

Available methods: geomNodeToModel() --> Local geom node to Model. Does not accept ghost nodes. nodeToModel() --> Local geom or ghost node (either Ghs or Gl) to Model, ghost in the same format as the input. nodeToModel_Ghs_Gn() --> Local geom or ghost node (high bit set) to Model, ghost negative.
nodeToModel_Gl_Gn() --> Local geom or ghost node (linear) to Model, ghost negative. nodeToModel_Ghs_Ghs() --> Local geom or ghost node (high bit set) to Model, ghost with high bit set. cellToModel() --> Local cell to Model cell.

checkedGeomNodeFromModel() --> Model geom node to Local. Input is range checked. Does not accept ghost nodes. checkedNodeFromModel() --> Model geom or ghost node (either Ghs or Gl) to Local, ghost in the same format as the input. Input is range checked. checkedNodeFromModel_Gn_Ghs() --> Model geom or ghost node (negative) to Local, ghost with high bit set. Input is range checked. checkedNodeFromModel_Gn_Gl() --> Model geom or ghost node (negative) to Local, ghost linear. Input is range checked. checkedNodeFromModel_Ghs_Ghs() --> Model geom or ghost node (high bit set) to Local, ghost with high bit set. Input is range checked. checkedGhostNodeFromModel_Ghc_Ghc() --> Model ghost node (high bit clear) to local, also with high bit clear. Input is range checked. Does not accept geometry nodes. checkedCellFromModel() --> Model cell to Local cell. Input is range checked.

Enumeration Type Documentation

◆ TranslationSemantics

enum GmMeshUtils::TranslationSemantics

An enumeration to declare the semantics of the operation that made the index translation call. See the namespace documentation.

Enumerator
API	Method called from the Lua binding.
REPORT	Method called from a report function or an error message.
IO	Method called from a model loading / saving function.

Function Documentation

◆ checkedNodeFromModel()

int GmMeshUtils::checkedNodeFromModel	(	int	nodeId,
		const GmPCR *	pcr,
		TranslationSemantics	semantic )

inline

Given a user provided node id that is either a geometry node, a ghost node WITH the high bit set or a ghost node in linear format, checks the input data and converts it to the internal ordered representation, returning ghost nodes in the input format. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

Notice that the -1 and -2 error values will not overlap real ghost node numbers with the high bit set unless we have more than 2 billion ghost nodes in the mesh...

◆ checkedNodeFromModel_Ghs_Ghs()

int GmMeshUtils::checkedNodeFromModel_Ghs_Ghs	(	int	nodeId,
		const GmPCR *	pcr,
		TranslationSemantics	semantic )

inline

Given a user provided node id where ghost nodes are represented with the high bit set, checks the input data and converts it to the internal ordered representation, returning ghost nodes with their high bit set. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

Notice that the -1 and -2 error values will not overlap real ghost node numbers unless we have more than 2 billion ghost nodes in the mesh...

◆ checkedNodeFromModel_Gn_Ghs()

int GmMeshUtils::checkedNodeFromModel_Gn_Ghs	(	int	nodeId,
		const GmPCR *	pcr,
		TranslationSemantics	semantic )

inline

Given a user provided node id where ghost nodes are represented as negative values, checks the input data and converts it to the internal ordered representation, returning ghost nodes with their high bit set. If the node is invalid (does not belong to the mesh), returns -2. If partitioned, the node is valid, but does not belong to the current partition, returns -1.

Notice that the -1 and -2 error values will not overlap real ghost node numbers unless we have more than 2 billion ghost nodes in the mesh...

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ TranslationSemantics

Function Documentation

◆ checkedNodeFromModel()

◆ checkedNodeFromModel_Ghs_Ghs()

◆ checkedNodeFromModel_Gn_Ghs()