Element mesh object methods

Most used:

• mesh:gaussAttributeAccessor()
• mesh:elementIntegrationRule()

Index:

• Element data methods
  • mesh:gaussAttributeIds()
  • mesh:gaussAttributeInfo()
  • mesh:gaussAttributeAccessor()
  • mesh:addGaussAttributeSet()
  • mesh:removeGaussAttributeSet()
  • mesh:clearGaussAttributeSets()
• Element integration rule methods
  • mesh:elementIntegrationRule()
  • mesh:borderIntegrationRule()
  • mesh:faceIntegrationRule()
  • mesh:edgeIntegrationRule()
  • mesh:numIntegrationRuleSets()
• History methods
  • mesh:saveGaussAttributeState()
  • mesh:numGaussAttributeStates()
  • mesh:gaussAttributeStateTag()
  • mesh:gaussAttributeStateTime()
  • mesh:setGaussAttributeStateTag()
  • mesh:setGaussAttributeStateTime()
• Hierarchical element methods
  • mesh:hPOrder()
  • mesh:hQOrder()
• Inherited methods
  • Node mesh object methods
  • Cell mesh object methods

Element data methods

mesh:gaussAttributeIds()
Description:	Returns a list with the name (id) of every Gauss attribute associated with the mesh.
Parameters:	None.
Returns:	Returns a table with Gauss attribute ids (strings).

Example:

local gaussAttrIds = m:gaussAttributeIds()

mesh:gaussAttributeInfo(name)
Description:	Returns an object with metadata information about the named mesh Gauss attribute.
Parameters:	name - The Gauss attribute name (id).
Returns:	Returns a value info object or nil if the requested name was not found in the mesh.

Example:

local sInfo = m:gaussAttributeInfo('S')

mesh:gaussAttributeAccessor(name, unit) mesh:gaussAttributeAccessor(name, state, locked, unit)
Description:	Returns a Gauss accessor object that can be used to retrieve and update data for Gauss attributes. Can be called with two different signatures. The first, receiving only the attribute name and an optional unit, always retrieves data from the current state and is the most used. The second, allows for defining the desired state from which data will be recovered / written. As a matter of fact, the first format is equivalent to calling the second one as mesh:gaussAttributeAccessor(name, 0, true, unit).
Parameters:	name	The name (id) of the Gauss attribute.
	state	An optional state number referencing the history state that the accessor will operate on. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested variable, which can be queried with a call to mesh:numGaussAttributeStates(). Remember that for a Gauss accessor to support states, the history parameter must be set on its value info object.
	locked	The locked parameter controls the behaviour of the accessor once a new state is created for the value. The 'lock' refers to the state number, so if locked is false and a new state is created, the accessor doesn't change and continues to point to the same data. If locked is true, the accessor will be locked to that state number, so when a new state is created, the accessor changes the data its looking upon to reflect the new state. For example, an accessor locked on state 0 will always point to the current state, and one locked to state 1 will always point to the previous saved value.
	unit	An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns:	A Gauss accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local sAc  = m:gaussAttributeAccessor('S')          -- Get an accessor to the 'S' Gauss attribute
local sAc2 = m:gaussAttributeAccessor('S', 'psi')   -- Get an accessor to the 'S' Gauss attribute with values converted to psi
local sAc3 = m:gaussAttributeAccessor('S', 1, true) -- Get an accessor locked on the previous saved value of attribute 'S'

mesh:addGaussAttributeSet(valInfo)
Description:	Creates a new value set for storing data for a new Gauss attribute and associates this new attribute with the mesh.
Parameters:	valInfo - A new value info object created by a call to ValueInfo(), with valueKind equal to "gauss attribute".
Returns:	Returns true on success, false on error.

Example:

local newInfo = ValueInfo('gauss attribute', {id = 'new1', unit = 's'})
assert(m:addGaussAttributeSet(newInfo) == true)

mesh:removeGaussAttributeSet(name)
Description:	Removes the named Gauss attribute from the mesh. Use carefully.
Parameters:	name - The name (id) of the Gauss attribute.
Returns:	Nothing.

Example:

m:removeGaussAttributeSet('S')

mesh:clearGaussAttributeSets()
Description:	Removes all Gauss attributes from the mesh. Use carefully.
Parameters:	None.
Returns:	Nothing.

Example:

m:clearGaussAttributeSets()

Element integration rule methods

mesh:elementIntegrationRule(typeName, ruleSetNumber)
Description:	Returns the configured integration rule for the given element type, according to the given rule set. Each mesh can store several rule sets. Each rule set defines the integration schema that should be used for each mesh element type.
Parameters:	typeName	A string with the element type. See the Element types page for a list of available cell types.
	ruleSetNumber	The desired rule set number (from 1 to mesh:numIntegrationRuleSets())
Returns:	Returns the integration rule object.

Example:

local ir = m:elementIntegrationRule('quad4', 1)

mesh:borderIntegrationRule(typeName, ruleSetNumber, borderIndex)
Description:	Returns the configured border integration rule for the given element type, according to the given rule set. Each mesh can store several rule sets. Each rule set defines the border integration schema that should be used for each mesh element type. For 2D elements it is equivalent to calling mesh:edgeIntegrationRule() and for 3D elements to calling mesh:faceIntegrationRule(), beeing undefined for line elements. It can be used for building generic code that works for both 2D and 3D elements.
Parameters:	typeName	A string with the element type. See the Element types page for a list of available cell types.
	ruleSetNumber	The desired rule set number (from 1 to mesh:numIntegrationRuleSets())
	borderIndex
	borderIndex	The element's border (edge or face) index over which the integration will be done. This parameter is necessary only if the element is a 3D element that has faces with different types (like a wedge element, whose faces can be either quadrilaterals or triangles). For other elements, it is optional. When given, it must be a valid edge or face number (between 1 and geometry:numEdges() or geometry:numFaces()). See the Element types page for the face organization for each cell type.
Returns:	Returns the border integration rule object or nil if the type does not allow border rules (1D types, for example).

Example:

local bir1 = m:borderIntegrationRule('quad4', 1)      -- Integrates over a quad4 edge
local bir2 = m:borderIntegrationRule('hex8', 1)       -- Integrates over an hex8 face
local bir3 = m:borderIntegrationRule('wedge6', 1, 4)  -- Integrates over the fourth face of a wedge6 element 

mesh:faceIntegrationRule(typeName, ruleSetNumber, faceIndex)
Description:	Returns the configured face integration rule for the given element type, according to the given rule set. Each mesh can store several rule sets. Each rule set defines the border integration schema that should be used for each mesh element type.
Parameters:	typeName	A string with the element type. See the Element types page for a list of available cell types.
	ruleSetNumber	The desired rule set number (from 1 to mesh:numIntegrationRuleSets())
	faceIndex	The element's face index over which the integration will be done. This parameter is necessary only if the element has faces with different types (like a wedge element, whose faces can be either quadrilaterals or triangles). For elements with a single face type (like a tetrahedron or a hexahedron) it is optional. When given, it must be a face number (between 1 and geometry:numFaces()). See the Element types page for the face organization for each cell type.
Returns:	Returns the border integration rule object or nil if the type does not allow face rules (1D/2D types, for example).

Example:

local bir1 = m:faceIntegrationRule('hex8', 1)       -- Integrates over an hex8 face
local bir2 = m:faceIntegrationRule('wedge6', 1, 4)  -- Integrates over the fourth face of a wedge6 element 

mesh:edgeIntegrationRule(typeName, ruleSetNumber)
Description:	Returns the configured edge integration rule for the given element type, according to the given rule set. Each mesh can store several rule sets. Each rule set defines the border integration schema that should be used for each mesh element type.
Parameters:	typeName	A string with the element type. See the Element types page for a list of available cell types.
	ruleSetNumber	The desired rule set number (from 1 to mesh:numIntegrationRuleSets())
Returns:	Returns the border integration rule object or nil if the type does not allow edge rules (1D types, for example).

Example:

local bir1 = m:edgeIntegrationRule('quad4', 1)  -- Integrates over a quad4 edge
local bir2 = m:edgeIntegrationRule('hex8', 1)   -- Integrates over an hex8 edge (not face)

mesh:numIntegrationRuleSets()
Description:	Returns the number of integration rule sets associated with this mesh. Each rule set defines the integration schema that should be used for integrating values over an element's domain and border, per mesh element type.
Parameters:	None.
Returns:	Returns the number of available integration rules for this mesh.

Example:

local nrules = m:numIntegrationRuleSets()

History methods

mesh:saveGaussAttributeState(name, mode)
Description:	Saves the current state for the given Gauss attribute, creating a new current state. The time associated with the new current state is initialized to the value of the current simulation time (set either explicitly by a call to setCurrentTime() or implicitly by some process functions). This can later be changed by a call to mesh:setGaussAttributeStateTime().
Parameters:	name	The name (id) of the Gauss attribute.
	mode	The requested save mode, defining how the new state will be initialized. Can be one of the following strings: "init" (new state is initialized with the data default value), "noinit" (new state is not initialized at all) or "copy" (new state is initialized with a copy of the current state).
Returns:	Returns true if successful, false otherwise. In particular, this function returns false if the given attribute does not have history values enabled.

Example:

m:saveGaussAttributeState('S', 'noinit')

mesh:numGaussAttributeStates(name)
Description:	Returns the number of existing history states for the given Gauss attribute.
Parameters:	name - The name (id) of the Gauss attribute.
Returns:	Returns the number of existing states or -1 for unknown names.

Example:

local nstates = m:numGaussAttributeStates('S')

mesh:gaussAttributeStateTag(name, state)
Description:	Returns the tag attached to the requested state, for the given Gauss attribute.
Parameters:	name	The name (id) of the Gauss attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numGaussAttributeStates().
Returns:	The state tag attached to the requested state or "" if the name doesn't exists.

Example:

local tag    = n:gaussAttributeStateTag('S', 0)  -- Tag from the current state
local oldTag = n:gaussAttributeStateTag('S', 1)  -- Tag from the previous state

mesh:gaussAttributeStateTime(name, state)
Description:	Returns the time attached to the requested state, for the given Gauss attribute.
Parameters:	name	The name (id) of the Gauss attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numGaussAttributeStates().
Returns:	The time attached to the requested state or -1 if the name doesn't exists.

Example:

local t    = n:gaussAttributeStateTime('S', 0)  -- Time from the current state
local oldt = n:gaussAttributeStateTime('S', 1)  -- Time from the previous state

mesh:setGaussAttributeStateTag(name, state, tag)
Description:	Updates the tag attached to the requested state, for the given Gauss attribute.
Parameters:	name	The name (id) of the Gauss attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numGaussAttributeStates().
	tag	The new state tag.
Returns:	Nothing.

Example:

m:setGaussAttributeStateTag('S', 1, 'myTag') -- Updates the tag from the previous state for Gauss attribute 'S'

mesh:setGaussAttributeStateTime(name, state, time)
Description:	Updates the time attached to the requested state, for the given Gauss attribute.
Parameters:	name	The name (id) of the Gauss attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested attribute, which can be obtained with a call to mesh:numGaussAttributeStates().
	time	The new state time, expressed in the same unit as the current simulation time unit.
Returns:	Nothing.

Example:

m:setGaussAttributeStateTime('S', 1, 12.5) -- Updates the time from the previous state for Gauss attribute 'S'

Hierarchical element methods

mesh:hPOrder()
Description:	Returns the polynomial interpolation order for scalar fields associated with this mesh hierarchical elements. Returns zero if the mesh does not have hierarchical elements.
Parameters:	None.
Returns:	Returns the polynomial interpolation order for scalar fields.

Example:

local P = m:hPOrder()

mesh:hQOrder()
Description:	Returns the polynomial interpolation order for vector fields associated with this mesh hierarchical elements. Returns zero if the mesh does not have hierarchical elements.
Parameters:	None.
Returns:	Returns the polynomial interpolation order for vector fields.

Example:

local Q = m:hQOrder()