Integration rule objects are the abstraction used by GeMA for defining the integration schema that will be used by physics objects when integrating values over an element domain or over an element border domain.

Although more complicated scenarios are supported, where integration rules can be defined by element (as in the XFEM plugin), in general rules are defined by element type. Each rule stores the number of integration points that will be used for that element, along with the natural coordinates and the weight for each integration point. The available schemas per element type are documented in the Element types page.

The set of integration rule objects associated with a mesh can be retrieved with the mesh:elementIntegrationRule() and mesh:borderIntegrationRule() methods. Tis is the preferred way for obtaining an integration rule object. Alternatively, new integration rule objects can be created by calls to IntegrationRule(), BorderIntegrationRule(), EdgeIntegrationRule() or FaceIntegrationRule().

Example:

local m = modelData:mesh('myMeshName')
local ir  = m:elementIntegrationRule('quad4', 1)
local bir = m:borderIntegrationRule('quad4', 1)
local ir = IntegrationRule('quad4', 'auto')       -- Default integration rule for a quad4
local ir = IntegrationRule('quad4', 'auto', 3, 3) -- A 3 x 3 integration rule for a quad4

Index:

Creating an integration rule object
- IntegrationRule()
- BorderIntegrationRule()
- EdgeIntegrationRule()
- FaceIntegrationRule()
Integration rule metadata methods
- ir:ruleName()
- ir:numNaturalCoord()
- ir:degree()
Integration point methods
- ir:numPoints()
- ir:integrationPoint()
Border rule methods
- ir:numBorderCoord()
- ir:translatePoint()

Creating an integration rule object

IntegrationRule(elemType, ruleType, rule1, rule2, rule3) IntegrationRule(elemType, P, Q, ruleType, rule1, rule2, rule3)
Description:	Returns an integration rule object configured with the given rule parameters. Rule parameters are particular to each element type. Check the Element types page for a list of available parameters for each type and their default settings.
Parameters:	elemType	The element type.
	P, Q	The P and Q parameters. Should be provided only for hierarchical element types.
	ruleType	The type of integration rule that will be used. Accepted values are: - "auto" The type of integration rule will be the default type for the shape element type; - "gauss" The integration rule will be a Gauss integration rule; - "lobatto" The integration rule will be a Lobatto integration rule; - "newton" or "closed newton" The integration rule will be a closed Newton-Cotes integration rule; - "open newton" The integration rule will be an open Newton-Cotes integration rule;
	rule1, rule2, rule3	Optional rule order parameters. The meaning, accepted number of parameters, their possible values and defaults depends on the underlying element type. Compound rules, such as those used by `quad` or `hex` type elements, will accept one parameter per dimension, while `tri` and `tet` elements take just one parameter. Check the Element types page for details.
Returns:	Returns the integration rule object or `nil` if the given parameters do not specify a valid rule.

Example:

local ir
ir = IntegrationRule('quad4', 'auto')          -- A 2 x 2 Gauss rule for quad4 elements (default)
ir = IntegrationRule('quad4', 'gauss', 3)      -- A 3 x 3 Gauss rule for quad4 elements (missing parameter replaced by a copy of the first)
ir = IntegrationRule('quad4', 'lobatto', 3, 2) -- A 3 x 2 Lobatto rule for quad4 elements
ir = IntegrationRule('tri3', 'auto')           -- A 3 point Gauss rule for tri3 elements (default)
ir = IntegrationRule('tri3', 'auto', 6)        -- A 6 point Gauss rule for tri3 elements 
ir = IntegrationRule('tri3', 'gauss', 6)       -- Also a 6 point Gauss rule for tri3 elements 
ir = IntegrationRule('tri3', 'auto', 2)        -- Returns nil. 2 is not a valid rule for tri3 elements
ir = IntegrationRule('tri3', 'lobatto', 6)     -- Returns nil. No support for Lobatto rules for tri3 elements
ir = IntegrationRule('hhexp', 2, 3, 'auto')    -- A Lobatto rule for an hierarchical hhexp element with P = 2, Q = 3

BorderIntegrationRule(elemType, faceType, ruleType, rule1, rule2) BorderIntegrationRule(elemType, P, Q, faceType, ruleType, rule1, rule2)
Description:	Returns a border integration rule object configured with the given border rule parameters. Border rule parameters are particular to each element type and are undefined for 1D (bar) elements. For 2D elements it is equivalent to calling `shape:`edgeIntegrationRule`()` and for 3D elements to calling `shape:`faceIntegrationRule`()`. It can be used for building generic code that works for both 2D and 3D elements. Check the Element types page for a list of available parameters for each type and their default settings.
Parameters:	elemType	The element type.
	P, Q	The P and Q parameters. Should be provided only for hierarchical element types.
	faceType	The face type parameter is required only when integrating over a face of a 3D element that has multiple face types (like a wedge, whose faces can be either triangles or quadrilaterals). In that case, it should be a string defining the type of the face (accepted values are `"quad"` and `"tri"`). Otherwise it can be `nil`, but if given, it should match the element's face type;
	ruleType	The type of integration rule that will be used. Accepted values are: - "auto" The type of integration rule will be the default type for the shape element type; - "gauss" The integration rule will be a Gauss integration rule; - "lobatto" The integration rule will be a Lobatto integration rule; - "newton" or "closed newton" The integration rule will be a closed Newton-Cotes integration rule; - "open newton" The integration rule will be an open Newton-Cotes integration rule;
	rule1, rule2	Optional rule order parameters. The meaning, accepted number of parameters, their possible values and defaults depends on the underlying border element type. Borders for 2D elements are analogue to bar elements, while borders to 3D elements are analogue to their corresponding face geometries (`quad` or `tri` elements). Check the Element types page for defatails.
Returns:	Returns the border integration rule object or `nil` if the given parameters do not specify a valid rule.

Example:

local ir
ir = BorderIntegrationRule('hex8', nil, 'auto')        -- A 2 x 2 point Gauss rule for hex8 element borders (default)
ir = BorderIntegrationRule('hex8', nil, 'lobatto', 3)  -- A 3 x 3 point Lobatto rule for hex8 element borders
ir = BorderIntegrationRule('tri3', nil, 'auto')        -- A 2 point Gauss rule for tri3 element borders (default)
ir = BorderIntegrationRule('tri3', nil, 'auto', 6)     -- Returns nil. 6 is not a valid rule for tri3 borders
ir = BorderIntegrationRule('tri3', nil, 'lobatto')     -- Returns nil. No support for Lobatto rules for tri3 elements
ir = BorderIntegrationRule('wedge6', 'quad', 'auto', 2) -- A 2 x 2 point Gauss rule for a wedge quadrilateral face
ir = BorderIntegrationRule('wedge6', 'tri', 'auto', 3)  -- A 3 points Gauss rule for a wedge triangular face

EdgeIntegrationRule(elemType, ruleType, rule1) EdgeIntegrationRule(elemType, P, Q, ruleType, rule1)
Description:	Returns a border integration rule object configured with the given edge rule parameters. Edge rule parameters are particular to each element type and are undefined for 1D elements. Check the Element types page for a list of available parameters for each type and their default settings.
Parameters:	elemType	The element type.
	P, Q	The P and Q parameters. Should be provided only for hierarchical element types.
	ruleType	The type of integration rule that will be used. Accepted values are: - "auto" The type of integration rule will be the default type for the shape element type; - "gauss" The integration rule will be a Gauss integration rule; - "lobatto" The integration rule will be a Lobatto integration rule; - "newton" or "closed newton" The integration rule will be a closed Newton-Cotes integration rule; - "open newton" The integration rule will be an open Newton-Cotes integration rule;
	rule1	Optional rule order parameter. The meaning, possible values and defaults depends on the underlying edge element type. Edge borders are analogue to their corresponding bar elements. Check the Element types page for defatails.
Returns:	Returns the border integration rule object or `nil` if the given parameters do not specify a valid rule.

Example:

local ir
ir = EdgeIntegrationRule('hex8', 'auto')       -- A 2 point Gauss rule for hex8 element edges (default)
ir = EdgeIntegrationRule('hex8', 'lobatto', 3) -- A 3 point Lobatto rule for hex8 element edges
ir = EdgeIntegrationRule('tri3', 'auto')       -- A 2 point Gauss rule for tri3 element borders (default)

FaceIntegrationRule(elemType, faceType, ruleType, rule1, rule2) FaceIntegrationRule(elemType, P, Q, faceType, ruleType, rule1, rule2)
Description:	Returns a border integration rule object configured with the given face rule parameters. Face rule parameters are particular to each element type and are undefined for 1D and 2D elements. Check the Element types page for a list of available parameters for each type and their default settings.
Parameters:	elemType	The element type.
	P, Q	The P and Q parameters. Should be provided only for hierarchical element types.
	faceType	The face type parameter is required only when integrating over a face of a 3D element that has multiple face types (like a wedge, whose faces can be either triangles or quadrilaterals). In that case, it should be a string defining the type of the face (accepted values are `"quad"` and `"tri"`). Otherwise it can be `nil`, but if given, it should match the element's face type;
	ruleType	The type of integration rule that will be used. Accepted values are: - "auto" The type of integration rule will be the default type for the shape element type; - "gauss" The integration rule will be a Gauss integration rule; - "lobatto" The integration rule will be a Lobatto integration rule; - "newton" or "closed newton" The integration rule will be a closed Newton-Cotes integration rule; - "open newton" The integration rule will be an open Newton-Cotes integration rule;
	rule1, rule2	Optional rule order parameters. The meaning, accepted number of parameters, their possible values and defaults depends on the underlying face element type. Face borders for 3D elements are analogue to their corresponding face geometries (`quad` or `tri` elements). Check the Element types page for defatails.
Returns:	Returns the border integration rule object or `nil` if the given parameters do not specify a valid rule.

Example:

local hex8shape   = ShapeFunction('hex8')
local tri3shape   = ShapeFunction('tri3')
local wedge6shape = ShapeFunction('wedge6')
local ir
ir = FaceIntegrationRule('hex8', 'auto')       -- A 2 x 2 point Gauss rule for hex8 element faces (default)
ir = FaceIntegrationRule('hex8', 'lobatto', 3) -- A 3 x 3 point Lobatto rule for hex8 element faces
ir = FaceIntegrationRule('tri3', 'auto')       -- Returns nil since tri3 elements don't have faces
ir = FaceIntegrationRule('wedge6', 'quad', 'auto', 2) -- A 2 x 2 point Gauss rule for a wedge quadrilateral face
ir = FaceIntegrationRule('wedge6', 'tri', 'auto', 3)  -- A 3 points Gauss rule for a wedge triangular face

Integration rule metadata methods

ir:ruleName()
Description:	Returns the integration rule name, describing the adopted integration schema.
Parameters:	None.
Returns:	Returns a string with the rule name.

Example:

print(ir:ruleName())

ir:numNaturalCoord()
Description:	Returns the number of natural coordinates for each integration point. This value is always equal to the number of natural coordinates used by the element's shape function, as returned by `shape:`numNaturalCoord`()`, and not necessarily equal to the problem dimension.
Parameters:	None.
Returns:	Returns the number of natural coordinates.

Example:

local coordDim = ir:numNaturalCoord()

ir:degree()
Description:	Returns the integration degree for this rule. The returned number is the maximum polynomial degree for which this integration rule is exact.
Parameters:	None.
Returns:	Returns the rule degree.

Example:

local degree = ir:degree()

Integration point methods

ir:numPoints()
Description:	Returns the number of points in the adopted integration schema.
Parameters:	None.
Returns:	Returns the number of integration points in this rule.

Example:

local npoints = ir:numPoints()

ir:integrationPoint(pointIndex)
Description:	Returns the given integration point natural coordinates and weight.
Parameters:	pointIndex - The desired point index (between 1 and `ir:`numPoints`()`).
Returns:	Returns two values: a vector object with the point natural coordinates and the point weight.

Example:

for i=1, ir:numPoints() do
  local ip, w = ir:integrationPoint(i)
  
  ip:t():print()       -- Prints ip coordinates as a line matrix instead of a column matrix 
  print('weight:', w)
end

Border rule methods

ir:numBorderCoord()
Description:	Returns the number of natural coordinates for each border integration point. Available only for border integration rules. As an example, the integration rule for a `"quad4"` element, returns points with two natural coordinates while a border integration rule for the same element type returns points with a single natural coordinate (the quad border is a line).
Parameters:	None.
Returns:	Returns the number of natural coordinates for border integration points.

Example:

local coordDim = bir:numBorderCoord()

ir:translatePoint(border, borderCoord)
Description:	Given an integration point retrieved with a border integration rule, whose returned coordinate uses the border reference (edge or face), and so has less coordinates than the element coordinate system, returns a new point in the element reference system, filling the original set of coordinates with the missing, fixed, values assciated with the border.
Parameters:	border	The border index (between 1 and the number of edges/faces in the element - see the Element types documentationt and also the `geometry:`numEdges`()` and `geometry:`numFaces`()` methods).
Parameters:	borderCoord	The border coordinate vector, as returned by `ir:`integrationPoint`()`.
Returns:	Returns a vector object with the element natural coordinates equivalent to the border coordinates or `nil` if `border` references an element border that can not be used for numerical integration (like the 0-length edges for an interface element).

Example:

local m   = modelData:mesh('myMeshName')
local bir = m:borderIntegrationRule('quad4', 1)
--
--  (-1,1)           (1,1) -> Natural coordinates
--     x---------------x
--     |               |
--     |               |
--     |               |
--     |               |
--     |               |
--     |               |
--     |      (0.5,-1) |
--     x----------o----x
--  (-1,-1)          (1,-1) 
--
-- Translates the point marked as 'o', whose border coordinate is 0.5,
-- to the quad element reference frame.
local ecoord = bir:translatePoint(1, Vector{0.5})
assert(ecoord == Vector{0.5, -1.0})  