 |
GemaCoreLib
The GeMA Core library
|
|
GemaCoreLib
The GeMA Core library
|
Class used to store the definition of a user function and its parameters. More...
#include <gmUserFunction.h>
Classes | |
| struct | GmUserFunctionParameter |
| Auxiliar structure for storing function parameter information. More... | |
Public Member Functions | |
| GmUserFunction (QString id, GmUserFunctionType type) | |
| Constructor. | |
| ~GmUserFunction () | |
| Destructor. Releases the Lua function reference, if any. | |
| QString | id () const |
| Returns the object id. | |
| GmUserFunctionType | type () const |
| Returns the type of function stored inside ths object. | |
| const QList< GmUserFunctionParameter > & | parameterList () const |
| Returns the list of parameters passed to the function. | |
| bool | isCFunction () const |
| Returns true if the stored function is a C function. | |
| LuaFunction * | luaFunction () const |
| Returns the stored Lua function (associated with the current thread) or NULL for C functions. | |
| QString | cFunctionName () const |
| Returns the name of the stored C function or an empty string for Lua functions. | |
| QString | cFunctionPlugin () const |
| Returns the name of the stored C function plugin or an empty string for Lua functions. | |
| GmPluginObjectFactory * | cFunctionFactory () const |
| Returns the stored C function factory (that can be used to instance a new GmPhysicsUserFunctions object if needed by the evaluator) or NULL for Lua functions. | |
| void | addParameter (QString src, Unit unit, int dim=-1, int history=-1, GmInterpolatorType interpType=GM_NO_INTERPOLATOR, QVariant interpParam=QVariant()) |
| Adds a new parameter to the function parameter list. More... | |
| void | setLuaMethod (int tid, LuaFunction *func) |
| Sets the Lua method receiving a pointer to a HEAP ALLOCATED LuaFunction object for the given thread id. The UserFunction takes "ownership" of the function object, releasing it when destructed. More... | |
| void | setCMethod (QString pluginName, QString methodName, GmPluginObjectFactory *factory) |
| Sets the C method receiving both the plugin and function names needed to locate the function and an object factory that can be used to instance the Physics object that will contain the called function. | |
Private Attributes | |
| QString | _id |
| Unique id for this value function. | |
| GmUserFunctionType | _type |
| The type of function stored. | |
| QList< GmUserFunctionParameter > | _parameters |
| The list of function parameters. | |
| GmTLS< LuaFunction * > * | _luaFunction |
| The lua function to be called or NULL for C functions. Has a per thread value with a function per Lua environment. | |
| QString | _cFuncName |
| The name of the C function to be called (or empty for Lua functions) | |
| QString | _cFuncPlugin |
| The name of the plugin that contains _cFuncName (or empty for Lua functions) | |
| GmPluginObjectFactory * | _cFuncFactory |
| The factory used to instance a GmPhysicsUserFunctions if needed (or NULL for Lua functions) | |
Class used to store the definition of a user function and its parameters.
| void GmUserFunction::addParameter | ( | QString | src, |
| Unit | unit, | ||
| int | dim = -1, |
||
| int | history = -1, |
||
| GmInterpolatorType | interpType = GM_NO_INTERPOLATOR, |
||
| QVariant | interpParam = QVariant() |
||
| ) |
Adds a new parameter to the function parameter list.
It is important to notice that parameters are sent to the Lua function or to the C function in the same order as they are included in this list.
Parameters are matched to an existing value by the 'src' argument. Possible values depend on the function type. For functions applied to nodes (for calculating an attribute value or a node based boundary condition), they can be:
For functions applied to cells (for calculating cell attributes, cell Gauss attributes, cell properties or boundary based boundary conditions), they can be:
If there is a name clash (a cell attribute with the same name as a cell property, for example), the name will be linked to the first source found in the order above.
The history parameter allows a parameter to access a value stored in a previous state for parameter types that support history. A value of 0 means the current state, a value of 1 the previous state, 2 the one before that and so on. Currently, the referenced state MUST exist at the moment that the function is prepared. In practice that means that it's usefull for rolling histories only.
When a function attached to an element uses as parameters node attributes or node state variable, we need to use an aggregation criteria for transforming node attributes / state vars into a single value. This is usually done by an interpolation function evaluated over the cell point that is beeing worked upon (an integration point, for example). The interpType parameter allows the user to specify the desired method.
When specifying interpType, bear in mind that not all types are valid for every cell type. The special value GM_NO_INTERPOLATOR means that no aggregation attempt will be done by the library and the user function will receive as a parameter a complete set of node values instead of a single one to decide what to do. To acomplish that, in Lua, a scalar value will be received as a table of values and vectors and matrices as tables of tables. In C++ all values will have to be accessed by the non scalar parameter access method GmUserFunctionContext::par() that will concatenate values for all nodes in a single vector (ordered by node for vector and matrix attributes).
The special value GM_DEFAULT_INTERPOLATOR means that the user does not want to specify the interpolaion mode himself and a default will be used based on cell type (cells = IDW and elements = SHAPE)
If the parameter specifies a Gauss attribute, and the call provides an ip number matching the evaluation coordinate, the Gauss attribute will be evaluated at the said integration point. This will work ONLY if the Gauss attribute has the SAME integration rule as the one being used while evaluating the function. Currently, no check is done when the user has given us an ip index in the accessor call.
If the call does NOT provide an ip number (ip = -1), the Gauss attribute will be interpolated at the given coordinate with a Gauss to Point rule, using the provided interpType / interpParam pair (or the default if they where not given). For this kind of interpolation, the GM_NO_INTERPOLATOR is currently NOT supported.
| src | The src object id of the parameter. |
| unit | The unit in which the values should be passed to the function. This should be a compatible unit with the src unit, but this check can be made only when the function is associated with a mesh. |
| dim | This parameter is ignored for scalar data srcs. For vector or matrix srcs, if this value is -1, the entire vector/matrix will be passed as prameter in the form of a linear table in Lua, vector in C (matrices are linearized in COLUMN MAJOR ORDER). If this value is different from -1, it should identify an index in the vector/matrix that will be recovered and passed as a scalar object to the function. Again, the allowed range for dim values can only be checked when the function is associated with a mesh. |
| history | This parameter allows a parameter to access a value stored in a previous state for parameter types that support history. A value of 0 means the current state, a value of 1 the previous state and so on. |
| interpType | This parameter defines if and how node values are interpolated for cell based functions as explained above. Use GM_DEFAULT_INTERPOLATOR for parameters that do not need aggregation. |
| interpParam | Aditional parameter used for configuring the interpolator type defined by interpType. Follows the interpolator convention defined in the appropriate interpolator class. |
| void GmUserFunction::setLuaMethod | ( | int | tid, |
| LuaFunction * | func | ||
| ) |
Sets the Lua method receiving a pointer to a HEAP ALLOCATED LuaFunction object for the given thread id. The UserFunction takes "ownership" of the function object, releasing it when destructed.
When using with multiple worker threads, each one must have its own Lua environment with its own copy of the original function. A value of zero for tid indicates that this is the main Lua environment.
1.8.15