User functions are a simple way of extending a model with user defined relationships or with dynamic behavior. Any cell material property, node attribute, cell attribute, Gauss attribute or boundary condition value can be bound to a user function, implemented either in Lua or in C++ (for details about the later, check the GmUserfunction class documentation).

As an example of a user function, consider the simple case of calculating temperatures over a set of sedimentary layers. Each layer has a grain conductivity that depends on the lithology type but also on the layer porosity since rock pores are filled with water. A user function can be used to calculate the effective conductivity as a function of the grain conductivity and the layer porosity.

There are two kinds of user functions: node functions and cell functions. As their names imply, node functions can be used to provide values for node attributes or for node based boundary conditions. Cell functions, on the other hand, provide values for cell properties, cell attributes, Gauss attributes and boundary condition values tied to cell borders.

There can be several user function objects on the simulation file, created by the NodeFunction and CellFunction keywords.

Examples

-- A node user function for calculating the error between the analytical 
-- solution given by state var T and the numerical solution given by the 
-- node attribute Tana
NodeFunction { id = 'errf', 
               parameters = { {src = 'Tana'},
                              {src = 'T'},
                            },
               method = function(Tana, T) return Tana - T end
             }
-- Mixed fluid grain conductivity.  Geometric mean of the grain conductivity g_k
-- and the water conductivity kW using the porosity phi as the weight.
local kW = 0.596   -- Water conductivity in W/m.K @ 20 degC 
CellFunction { id = 'k_phi', 
               parameters = { {src = phi,   unit = 'V/V' },     -- Porosity
                              {src = 'g_k', unit = 'W/(m.K)' }  -- Grain conductivity
                           }, 
               method = function(phi, kG) return (kW ^ phi) * (kG ^ (1-phi)) end
}              

Fields

Field	Description	Type	Required
id	The user function name.	String	Yes
description	A description of the user function purpose.	String	No
parameters	A table describing the set of parameters that will be made available for the user function method. Each table entry is a sub-table with the parameter description as describe below in the "Parameters Fields" section.	Table	Yes

method	The Lua function called whenever this node or cell function is evaluated, receiving as parameters the data requested by the `parameters` table. Function arguments are matched to the requested parameters by their order. Scalar parameters are received as numbers, while vector and matrix parameters are received as Lua tables. Matrices are received in a linearized table in column major order (the same used in the FORTRAN language). The result returned by this function will be the value returned by the user function. It should have a dimension equal to the attribute to which this function is associated. Like the function arguments, vector or matrix results should be returned as a Lua table. If the function returns `nil`, the result will be equal to the associated attribute default value.	Function	Yes, for Lua functions

typeName	The name of the plugin providing the user function for plugin based C functions.	String	Yes, for C functions
methodName	The name of the user function for plugin based C functions.	String	Yes, for C functions

Parameters Fields

Field	Description	Type	Required
src (for node functions)	The name of the node attribute or state variable that will provide the parameter value. Pre-defined names are also available (1). When evaluating a user function parameter over an index, if the parameter value can not be evaluated at that index (due to different `affectedNodes` data options), a warning is emited (it can be disable through `disabledWarnings` simulation options) and the parameter assumes the value zero (or the zero vector for multi-dimensional parameters).	String	Yes
src (for cell functions)	The name of the cell property, cell attribute, gauss attribute, node attribute or state variable that will provide the parameter value. Pre-defined names are also available (2). For node attribute and state variable parameters, an aggregation procedure is needed to retrieve the desired value on the integration point where the cell function is being evaluated. Nodal values are automatically interpolated and the parameter receives the interpolated result. An automatic interpolation procedure is also performed if the parameter is a Gauss attribute that is being evaluated at a point whose natural coordinate is not one of the integration point coordinates. In that case, the Gauss point values will be used to interpolate the value at the evaluation coordinate.	String	Yes

unit	The expected unit for the parameter value. If the unit is different from the src unit, the value will be automatically converted. If empty, the original data unit will be used. See also the documentation on Working with units.	String	No
dim	This field can be used to transform vector or matrix values into scalar ones by selecting the data dimension that will be passed as parameter. In the following parameter definition `{src = "coordinate", dim = 2}`, the resulting value passed to the function will be a scalar value with the y node coordinate, instead of a vector.	Integer	No
history	When the source parameter has an associated history, this field enables the access to previously stored values. A value of 0 means the current value. A value of 1 the previous state and so on. Default = 0.	Integer	No

interpType	If an interpolation procedure is needed (this is a cell function and src is a node attribute or a state variable or src is a gauss attribute being evaluated at a non integration point coordinate), this field defines the type of interpolation that will be performed. See (3). If missing, the default interpolation type will be used.	String	No
interpParam	If interpType is given, this field stores a parameter used by the interpolation type. Possible values depend on the interpolation type. See (3). Default is empty.	String or Number	No

(1) Pre-defined src names for node user functions:

"coordinate": The parameter will receive a table with node coordinates;
"time": The parameter will receive the current simulation time;
"dt": The parameter will receive the elapsed time between the current time and the last simulation iteration;
"nodeid": The parameter will receive the node id;
"meshid": The parameter will receive the mesh name;

(2) Pre-defined src names for cell user functions:

"time": The parameter will receive the current simulation time;
"dt": The parameter will receive the elapsed time between the current time and the last simulation iteration;
"cellid": The parameter will receive the cell id;
"meshid": The parameter will receive the mesh name;
"ipoint": The parameter will receive a table with the current integration point Cartesian coordinates;
"nipoint": The parameter will receive a table with the current integration point natural coordinates;

(3) Available interpolation types and supported parameters for each one (see the Interpolation methods page for more details):

"default": The default interpolation method, equal to "shape" for element meshes and "idw" with parameter 2 for cell meshes;
"nn": Nearest neighbor interpolation. If an integer parameter 'k' is given, the 'k' closest points will be averaged to return the interpolated value. The default value for 'k' is 1.
"idw": Inverse distance weighted interpolation. The interpolated value is the average of the known values weighted by inverse distance from the interpolation point raised to a power 'p' provided as a real number parameter. If 'p' is absent, a power of 2 is used.
"mls": Moving least squares method. No supported parameters.
"shape": Interpolation using the element's shape function. No supported parameters.
"lshape": Interpolation using the element's equivalent linear shape function. Usefull when dealing with super-parameteric scenarios. No supported parameters.
"no": No interpolation. Instead of receiving the interpolated value, the function will receive a table with the attribute value on every node of the cell. Scalar attributes are transformed into a table and vector/matrix values are transformed into a table of tables.