Implementation of the Declaration of the function used to prepare an environment with the core Lua functions. More...

#include "gmLuaEnv.h"
#include "gmLuaModelData.h"
#include "gmLuaMatrix.h"
#include "gmLuaValueInfo.h"
#include "gmLuaInterpolator.h"
#include "gmLuaCellGroupSet.h"
#include "gmLuaNodeSet.h"
#include "gmLuaValueAccessor.h"
#include "gmLuaMesh.h"
#include "gmLuaShape.h"
#include "gmLuaIntegrationRule.h"
#include "gmLuaCellGeometry.h"
#include "gmLuaSpatialIndex.h"
#include "gmLuaTask.h"
#include "gmLuaStateDump.h"
#include "gmLuaUtils.h"
#include <gmMesh.h>
#include <gmInterpolator.h>
#include <gmGaussToElementNodeInterpolator.h>
#include <gmPointCloudToPointInterpolator.h>
#include <gmNumSolver.h>
#include <gmSpatialIndex.h>
#include <gmTrace.h>
#include <gmLog.h>
#include <gmSimulationData.h>
#include <gmSolutionData.h>
#include <gmValueInfo.h>
#include <gmGaussAccessor.h>
#include <gmCellGroupSet.h>
#include <gmPath.h>
#include <gmShape.h>
#include <gmBorderIntegrationRule.h>
#include <gmShapeOrthogonalPol.h>
#include <gmTaskManager.h>
#include <gmStateDump.h>
#include <gmResultDataSrcInfo.h>
#include <gmPluginData.h>
#include <luaEnv.h>
#include <luaTable.h>
#include <luaTableTraverse.h>
#include <luaStackBalancer.h>
#include <unit.h>
#include <unitConverter.h>
#include <QDir>

Include dependency graph for gmLuaEnv.cpp:

Functions
static int	LuaCreateMatrix (lua_State *L)
	Function used to create a matrix inside Lua. More...

static int	LuaCreateVector (lua_State *L)
	Function used to create a vector (matrix with a single column) inside Lua. More...

static int	LuaCreateNodeToCellPointInterpolator (lua_State *L)
	Function used to create a "NodeToCellPointInterpolator" inside Lua. More...

static int	LuaCreateNodeToElementPointInterpolator (lua_State *L)
	Function used to create a "NodeToElementPointInterpolator" inside Lua. More...

static int	LuaCreateGaussToElementPointInterpolator (lua_State *L)
	Function used to create a "GaussToElementPointInterpolator" inside Lua. More...

static int	LuaCreateGaussToElementNodeInterpolator (lua_State *L)
	Function used to create a "GaussToNodeInterpolator" inside Lua. More...

static int	LuaCreateGaussNeighborsToNodeInterpolator (lua_State *L)
	Function used to create a "GaussNeighborsToNodeInterpolator" inside Lua. More...

static int	LuaCreateNodeCloudToPointInterpolator (lua_State *L)
	Function used to create a "NodeCloudToPointInterpolator" inside Lua. More...

static int	LuaCreateGaussCloudToPointInterpolator (lua_State *L)
	Function used to create a "GaussCloudToPointInterpolator" inside Lua. More...

static int	LuaNodeBasedMeshGaussToNodesInterpolation (lua_State *L)
	Function used to interpolate mesh node values from Gauss points with a node based approach. More...

static int	LuaElementBasedMeshGaussToNodesInterpolation (lua_State *L)
	Function used to interpolate mesh node values from Gauss points with an element based approach. More...

static int	LuaSplineMeshNodesToMeshNodesInterpolation (lua_State *L)
	Function used to transfer node values from a source mesh to node values of a destination mesh using the spline interpolation method. Each destination node value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaSplineMeshNodesToMeshGaussInterpolation (lua_State *L)
	Function used to transfer node values from a source mesh to Gauss values of a destination mesh using the spline interpolation method. Each destination Gauss value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaSplineMeshGaussToMeshNodesInterpolation (lua_State *L)
	Function used to transfer Gauss values from a source mesh to node values of a destination mesh using the spline interpolation method. Each destination node value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaSplineMeshGaussToMeshGaussInterpolation (lua_State *L)
	Function used to transfer Gauss values from a source mesh to Gauss values of a destination mesh using the spline interpolation method. Each destination Gauss value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaMeshNodesToMeshNodesInterpolation (lua_State *L)
	Function used to transfer node values from a source mesh to node values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaMeshNodesToMeshGaussInterpolation (lua_State *L)
	Function used to transfer node values from a source mesh to Gauss values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaMeshGaussToMeshNodesInterpolation (lua_State *L)
	Function used to transfer Gauss values from a source mesh to node values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaMeshGaussToMeshGaussInterpolation (lua_State *L)
	Function used to transfer Gauss values from a source mesh to Gauss values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes. More...

static int	LuaLogMsg (lua_State *L)
	Function used to print messages using the logger infrastructure. More...

static int	LuaLogMemory (lua_State *L)
	Function used to print used memory using the logger infrastructure. More...

static int	LuaCreateValueInfo (lua_State *L)
	Function used to create a new value info object. More...

static int	LuaCreateShapeFunction (lua_State *L)
	Function used to create a shape function object. More...

static int	LuaCreateCellGeometry (lua_State *L)
	Function used to create a cell geometry object. More...

static int	LuaCreateIntegrationRule (lua_State *L)
	Returns a new integration rule object suited for the given kind of element or nil if the rules are invalid.

static int	LuaCreateBorderIntegrationRule (lua_State *L)
	Returns a new border integration rule object suited for the given kind of element or nil if the rules are invalid.

static int	LuaCreateEdgeIntegrationRule (lua_State *L)
	Returns a new edge integration rule object suited for the given kind of element or nil if the rules are invalid.

static int	LuaCreateFaceIntegrationRule (lua_State *L)
	Returns a new face integration rule object suited for the given kind of element or nil if the rules are invalid.

static int	LuaConvert (lua_State *L)
	Function used to convert a value between two units. More...

static int	LuaCheckUnit (lua_State *L)
	Function used to check if a unit is a known unit or not. More...

static int	LuaStartTimer (lua_State *L)
	Function used to start a timer, returned by the function.

static int	LuaResetTimer (lua_State *L)
	Resets the given timer object.

static int	LuaElapsedTime (lua_State *L)
	Returns the elapsed time in seconds since startTimer() was called on the given timer object.

static int	LuaCurrentTime (lua_State *L)
	Returns the current simulation time + the simulation time unit. More...

static int	LuaPreviousTime (lua_State *L)
	Returns the previous simulation time + the simulation time unit. More...

static int	LuaSetCurrentTime (lua_State *L)
	Updates the current simulation time. A second boolean para,eter defines if the previous time will be updated or not. Default (when missing) = true.

static int	LuaSetPreviousTime (lua_State *L)
	Updates the previous simulation time.

static int	LuaSetCurrentTimeUnit (lua_State *L)
	Updates the unit for the current simulation time.

static int	LuaTranslatePath (lua_State *L)
	Given a path / file name, converts any macros and returns the expanded AND cleaned value.

static int	LuaCleanPath (lua_State *L)
	Given a path / file name, returns the cleaned value.

static int	LuaIsMeshGhostNode (lua_State *L)
	Returns true if the given index is a ghost index (has its highest bit set)

static int	LuaSetMeshGhostFlag (lua_State *L)
	Returns the given index with the ghost node bit set.

static int	LuaClearMeshGhostFlag (lua_State *L)
	Returns the given index with the ghost node bit cleared.

static int	LuaCreateCellGroupSet (lua_State *L)
	Returns a new cell group set. Parameters are the mesh, an optional table with cell group names and a boolean stating if the groups are disjoint or not.

static int	LuaCellTypeList (lua_State *L)
	Returns a table filled with the set of cell type names.

static int	LuaCreateStateDump (lua_State *L)
	Function used to create a new state dump object. More...

static int	LuaEvalResults (lua_State *L)
	Function used to force the evaluation of result rules. More...

static int	LuaRegisterResultAttribute (lua_State *L)
	Registers a new result attribute. Gets as parameters the attribute name, an optional description, the value unit, number of lines an columns and the value format string. More...

static int	LuaResultAttributeId (lua_State *L)
	Given an attribute name, returns the attribute id, or nil if no attribute with that name was registered. Works for attributes registered in Lua or in C++.

static int	LuaSetResultAttribute (lua_State *L)
	Given an attribute id, sets its value. The given value must be of the correct dimension and expressed in the attribute's unit. Multidimensional values should be provided either as a Lua table or a matrix object. Can also be used to set the value of string attributes.

static int	LuaResultAttribute (lua_State *L)
	Given an attribute id, returns its value. Returns a number for scalar values, a matrix object for vectors / matrices or a string for string attributes.

static int	LuaParallelCall (lua_State *L)
	Executes the named function in a parallel environment. More...

static int	LuaNodeParallelCall (lua_State *L)
	Executes a parallel node loop, calling the given function in each thread with a partition of the mesh nodes. More...

static int	LuaCellParallelCall (lua_State *L)
	Executes a parallel cell loop, calling the given function in each thread with a partition of the mesh cells. More...

static int	LuaLastParallelCallAffinity (lua_State *L)
	Returns a table with task affinity for the last parallel call.

static int	LuaCheckForCancelation (lua_State *L)
	Checks for a pending cancelation request. If there is one, aborts the script processing by raising a Lua error. More...

static int	LuaThreadGlobal (lua_State *L)
	Queries the value of the named global variable in the given thread environment. More...

static int	LuaSetThreadGlobal (lua_State *L)
	Sets the value of the named global variable in the given thread environment. More...

static int	LuaUndocCallPluginDataFunction (lua_State *L)
	Undocumented function used by regression tests to call a plugin data function. Important to enable regression tests for calling functions from different threads. NOT part of the official orchestration API. More...

static int	LuaUndocGetPluginDataValue (lua_State *L)
	Undocumented function used by regression tests to retriev a plugin data field value. Important to enable regression tests testing plugin data parsing. Get as parameters the plugin data id, alias and field name.

void	GmLuaRegisterSimulationFunctions (LuaEnv env, GmSimulationData simData, const GmLogCategory &logger)
	Registers simulation functions in the Lua Environment. More...

void	GmLuaRegisterResultFunctions (LuaEnv env, GmSimulationData simData, const GmLogCategory &logger)
	Registers result related functions in the Lua Environment. More...

void	GmLuaRegisterMatrixFunctions (LuaEnv *env, const GmLogCategory &logger)
	Registers matrix handling functions in the Lua Environment. More...

void	GmLuaRegisterInterpolatorFunctions (LuaEnv env, GmSimulationData simData, const GmLogCategory &logger)
	Registers interpolation handling functions in the Lua Environment. More...

GML_API_EXPORT void	GmLuaRegisterPathFunctions (LuaEnv env, GmSimulationData simData)
	Registers path handling functions in the Lua Environment. More...

void	GmLuaRegisterLoggerFunctions (LuaEnv *env, const GmLogCategory &logger)
	Registers logger handling functions in the Lua Environment. More...

void	GmLuaRegisterConvFunctions (LuaEnv *env)
	Registers unit handling functions in the Lua Environment. More...

void	GmLuaRegisterTimeFunctions (LuaEnv *env)
	Registers time measuring functions in the Lua Environment. More...

void	GmLuaRegisterCancelationFunctions (LuaEnv env, GmSimulationData simData)
	Registers the script cancelation check funtion. If simData is NULL, the registered function can only be called from the main thread. More...

void	GmLuaRegisterThreadFunctions (LuaEnv env, GmSimulationData simData, const GmLogCategory &logger)
	Registers parallel execution and thread handling functions in the Lua Environment. More...

void	GmLuaPrepareEnvironment (LuaEnv env, GmSimulationData simData, const GmLogCategory &logger, bool mainEnv)
	Adds to the environment env the set of global definitions that allows us to use Gema core objects in the Lua environment during a call to ProcessScript(). More...

void	GmLuaPrepareMathEnvironment (LuaEnv *env, const GmLogCategory &logger)
	Adds to the environment env the set of global definitions that allows us to use Gema core Matrix and conversion objects in the Lua environment. More...

Detailed Description

Implementation of the Declaration of the function used to prepare an environment with the core Lua functions.

Author: Carlos Augusto Teixeira Mendes

Date: september, 2015

Function Documentation

◆ GmLuaPrepareEnvironment()

void GmLuaPrepareEnvironment	(	LuaEnv *	env,
		GmSimulationData *	simData,
		const GmLogCategory &	logger,
		bool	mainEnv
	)

Adds to the environment env the set of global definitions that allows us to use Gema core objects in the Lua environment during a call to ProcessScript().

Creates the following global variables:

modelData with type GmLuaModelData
Matrix(), a function to create matrices
Vector(), a function to create matrices with a single column
NodeToCellPointInterpolator(), NodeToElementPointInterpolator(), GaussToElementPointInterpolator(), GaussToElementNodeInterpolator(), GaussNeighborsToNodeInterpolator(), NodeCloudToPointInterpolator() and GaussCloudToPointInterpolator() functions to create several kinds of interpolators
nodeBasedMeshGaussToNodes() and elementBasedMeshGaussToNodes() functions to interpolate mesh node values from Gauss point values
splineMeshNodesToMeshNodes(), splineMeshNodesToMeshGauss(), splineMeshGaussToMeshNodes() and splineMeshGaussToMeshGauss() functions to interpolate mesh values based on a global spline interpolation of the values in another mesh
meshNodesToMeshNodes(), meshNodesToMeshGauss(), meshGaussToMeshNodes() and meshGaussToMeshGauss() functions to interpolate mesh values based on a global interpolation with CDR of the values in another mesh
ValueInfo(), a function to create a new valueInfo object
ShapeFunction(), a function to retrieve a shape function object;
CellGeometry(), a function to retrieve a cell geometry object;
convert(), a function to convert values between units
checkUnit(), a function to verify if an unit is known or not
startTimer(), a function that inits & returns a timer object
resetTimer(), a function to reset a timer object
elapsedTime(), a function to return the amount of elapsed time for the given timer
logMsg(), a function to log messages using the logger infrastructure
logMemory(), a function to log memory usage
currentTime(), previousTime(), setCurrentTime(), setPreviousTime() and setCurrentTimeUnit()
translatePath(), cleanPath()
isMeshGhostNode(), setMeshGhostFlag() and clearMeshGhostFlag() to work with mesh ghost nodes;
CellGroupSet(), a function to create new cell group sets
StateDump(), a function to create a new state dump object;
evalResults() a function to force the evaluation of results;
registerResultAttribute() a function ta add a new result attribute
resultAttributeId() a function to retrieve a result id from the attribute name
setResultAttribute() a function to set the value of a result attribute
resultAttribute() a function to retrieve the value of a result attribute
checkForCancelation(), a function to abort on pending cancelation requests If called for the main Lua environment, also registers:
maxWorkerThreads, the maximum configured number of threads for parallel execution
maxProcThreads, the maximum number of threads supported by the processor for parallel execution
numProcCores, the number of processor cores in the current machine
parallelCall(), a function to parallel execute a function
nodeParallelCall() and cellParallelCall() to parallel execute a function over sets of nodes / cells
lastParallelCallAffinity(), a function to recover the task affinity for the last call to parallelCall(), nodeParallelCall() or cellParallelCall()
threadGlobal() and setThreadGlobal() to set / get global variable names in each thread

It also overloads some Lua functions to extend their funcionality by the way of the basicDefinitions.lua resource script, which also defines the following functions:

Double compare functions: equal(), nequal(), lt(), lte(), gt() and gte()

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaPrepareMathEnvironment()

void GmLuaPrepareMathEnvironment	(	LuaEnv *	env,
		const GmLogCategory &	logger
	)

Adds to the environment env the set of global definitions that allows us to use Gema core Matrix and conversion objects in the Lua environment.

Creates the following global variables:

Matrix(), a function to create matrices
Vector(), a function to create matrices with a single column
convert() a function to convert values between units
checkUnit() a function to verify if an unit is known or not

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterCancelationFunctions()

void GmLuaRegisterCancelationFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData
	)

Registers the script cancelation check funtion. If simData is NULL, the registered function can only be called from the main thread.

Creates the following global variables:

checkForCancelation(), a function to abort on pending cancelation requests

◆ GmLuaRegisterConvFunctions()

void GmLuaRegisterConvFunctions ( LuaEnv * env )

Registers unit handling functions in the Lua Environment.

Creates the following global variables:

convert() a function to convert values between units
checkUnit() a function to verify if an unit is known or not

◆ GmLuaRegisterInterpolatorFunctions()

void GmLuaRegisterInterpolatorFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData,
		const GmLogCategory &	logger
	)

Registers interpolation handling functions in the Lua Environment.

Creates the following global variables:

NodeToCellPointInterpolator(), a function to create interpolators to calc cell point data from node data
NodeToElementPointInterpolator(), a function to create interpolators to calc element point data from node data
GaussToElementPointInterpolator(), a function to create interpolators to calc element point data from Gauss data
GaussToElementNodeInterpolator(), a function to create interpolators to calc element node data from Gauss data
GaussNeighborsToNodeInterpolator(), a function to create interpolators to calc element node data from Gauss data from neighbor elements
NodeCloudToPointInterpolator(), a function to create interpolators to calc an arbitrary point data from a cloud of node data
GaussCloudToPointInterpolator(), a function to create interpolators to calc an arbitrary point data from a cloud of Gauss point data
nodeBasedMeshGaussToNodes() and elementBasedMeshGaussToNodes(), functions to interpolate mesh node values from Gauss point values
splineMeshNodesToMeshNodes(), a function to interpolate mesh node values based on a global spline interpolation over another mesh set of node values
splineMeshNodesToMeshGauss(), a function to interpolate mesh Gauss point values based on a global spline interpolation over another mesh set of node values
splineMeshGaussToMeshNodes(), a function to interpolate mesh node values based on a global spline interpolation over another mesh set of Gauss values
splineMeshGaussToMeshGauss(), a function to interpolate mesh Gauss point values based on a global spline interpolation over another mesh set of Gauss point values
meshNodesToMeshNodes(), a function to interpolate mesh node values based on a global interpolation with CDR over another mesh set of node values
meshNodesToMeshGauss(), a function to interpolate mesh Gauss point values based on a global interpolation with CDR over another mesh set of node values
meshGaussToMeshNodes(), a function to interpolate mesh node values based on a global interpolation with CDR over another mesh set of Gauss values
meshGaussToMeshGauss(), a function to interpolate mesh Gauss point values based on a global interpolation with CDR over another mesh set of Gauss point values

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterLoggerFunctions()

void GmLuaRegisterLoggerFunctions	(	LuaEnv *	env,
		const GmLogCategory &	logger
	)

Registers logger handling functions in the Lua Environment.

Creates the following global variables:

logMsg() a function to log messages using the logger infrastructure
logMemory() a function to log memory usage

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterMatrixFunctions()

void GmLuaRegisterMatrixFunctions	(	LuaEnv *	env,
		const GmLogCategory &	logger
	)

Registers matrix handling functions in the Lua Environment.

Creates the following global variables:

Matrix(), a function to create matrices
Vector(), a function to create matrices with a single column

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterPathFunctions()

GML_API_EXPORT void GmLuaRegisterPathFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData
	)

Registers path handling functions in the Lua Environment.

Creates the following global variables:

translatePath(), cleanPath();

◆ GmLuaRegisterResultFunctions()

void GmLuaRegisterResultFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData,
		const GmLogCategory &	logger
	)

Registers result related functions in the Lua Environment.

Creates the following global variables:

evalResults() a function to force the evaluation of results;
registerResultAttribute() a function ta add a new result attribute
resultAttributeId() a function to retrieve a result id from the attribute name
setResultAttribute() a function to set the value of a result attribute
resultAttribute() a function to retrieve the value of a result attribute

◆ GmLuaRegisterSimulationFunctions()

void GmLuaRegisterSimulationFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData,
		const GmLogCategory &	logger
	)

Registers simulation functions in the Lua Environment.

Creates the following global variables:

ValueInfo() a function to create a new valueInfo object;
ShapeFunction() a function to retrieve a shape function object;
CellGeometry() a function to retrieve a cell geometry object;
IntegrationRule(), BorderIntegrationRule(), EdgeIntegrationRule() and FaceIntegrationRule(), functions to create new integration rule objects
currentTime(), previousTime(), setCurrentTime(), setPreviousTime() and setCurrentTimeUnit();
isMeshGhostNode(), setMeshGhostFlag() and clearMeshGhostFlag() to work with mesh ghost nodes;
CellGroupSet(), a function to create new cell group sets;
StateDump(), a function to create a new state dump object;

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterThreadFunctions()

void GmLuaRegisterThreadFunctions	(	LuaEnv *	env,
		GmSimulationData *	simData,
		const GmLogCategory &	logger
	)

Registers parallel execution and thread handling functions in the Lua Environment.

IMPORTANT: This functions should NOT be made avilable for worker thread environments, only for the main thread.

Creates the following global variables:

maxWorkerThreads, the maximum configured number of threads for parallel execution
maxProcThreads, the maximum number of threads supported by the processor for parallel execution
numProcCores, the number of processor cores in the current machine
parallelCall(), a function to parallel execute a function
nodeParallelCall() and cellParallelCall() to parallel execute a function over sets of nodes / cells
lastParallelCallAffinity(), a function to recover the task affinity for the last call to parallelCall(), nodeParallelCall() or cellParallelCall()
threadGlobal() and setThreadGlobal() to set / get global variable names in each thread

IMPORTANT: This function REQUIRES that the supplied logger MUST exist during the whole lifetime of the lua environment.

◆ GmLuaRegisterTimeFunctions()

void GmLuaRegisterTimeFunctions ( LuaEnv * env )

Registers time measuring functions in the Lua Environment.

Creates the following global variables:

startTimer() a function that inits & returns a timer object
resetTimer() a function to reset a timer object
elapsedTime() a function to return the amount of elapsed time for the given timer

◆ LuaCellParallelCall()

static int LuaCellParallelCall ( lua_State * L )

static

Executes a parallel cell loop, calling the given function in each thread with a partition of the mesh cells.

Parameters are the mesh, a flag defining if only active cells should be returned, the name of the function to execute and an optional table with execution parameters. It can also receive additional parameters that are forwarded to the called function.

MUST be called from the main thread only.

The mesh parameter can be either the mesh name or a mesh object
The function name must reference a global function included in a shared block section. When called, this function will receive as parameters an iterator object, followed by any aditional parameters.
If aditional parameters are given, the options table must appear in the call (but can be replaced by a nil value or by an empty table). Keep in mind that any parameter MUST be a value that can be transfered to another Lua environment, which rules out Lua functions. See the documentation for parallelCall() for a description of the allowed values and their behaviour.
The iterator object should be used to traverse the set of cells that the function should work on. If taskCells is the parameter name, it should be used in a for clause as 'for cell in taskCells() do'.
The worker function does not returns results. It can report errors by calling error(). Pending cancelation requests are handled by API calls, but if those are not being made frequently enough, explicit calls for checkForCancelation() can be made. Keep in mind that each call to the iterator object by the loop will also check for a cancelation.
The optional options table accepts three named fields: 'ntasks', 'nworkers' and 'strategy' and their behaviour is documented by the GmTaskManager::parallelCellLoop() function.
The optional options table accepts four named fields: 'ntasks', 'nworkers' and 'strategy', whose behaviour is documented by the GmTaskManager::parallelNodeLoop() function, and a fourth field 'affinity' which, when present, should be a table with the same size as the effective number of tasks, storing the thread id that should be used to execute each task.

The call to cellParallelCall() will itself return true if the worker executions ended ok, and false if any thread aborted. Notice that this function will not return at all (raising a "script canceled" error) if there is a pending cancelation request, as is common to all other API functions.

◆ LuaCheckForCancelation()

static int LuaCheckForCancelation ( lua_State * L )

static

Checks for a pending cancelation request. If there is one, aborts the script processing by raising a Lua error.

Can be called either in the main thread or in worker threads. In the later case, will also raise an error if any other thread has aborted.

◆ LuaCheckUnit()

static int LuaCheckUnit ( lua_State * L )

static

Function used to check if a unit is a known unit or not.

Parameters: The unit string

Returns true if the unit is known, false otherwise

◆ LuaConvert()

static int LuaConvert ( lua_State * L )

static

Function used to convert a value between two units.

Parameters: The value to be converted + the source unit string and the destination unit string

Returns the converted value or nil if the conversion is not possible

◆ LuaCreateCellGeometry()

static int LuaCreateCellGeometry ( lua_State * L )

static

Function used to create a cell geometry object.

Parameters: A string describing the element type

Returns the cell geometry object

◆ LuaCreateGaussCloudToPointInterpolator()

static int LuaCreateGaussCloudToPointInterpolator ( lua_State * L )

static

Function used to create a "GaussCloudToPointInterpolator" inside Lua.

Please check the documentation for GmLuaGaussCloudToPointInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateGaussNeighborsToNodeInterpolator()

static int LuaCreateGaussNeighborsToNodeInterpolator ( lua_State * L )

static

Function used to create a "GaussNeighborsToNodeInterpolator" inside Lua.

Please check the documentation for GmLuaGaussNeighborsToNodeInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateGaussToElementNodeInterpolator()

static int LuaCreateGaussToElementNodeInterpolator ( lua_State * L )

static

Function used to create a "GaussToNodeInterpolator" inside Lua.

Please check the documentation for GmLuaGaussToNodeInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateGaussToElementPointInterpolator()

static int LuaCreateGaussToElementPointInterpolator ( lua_State * L )

static

Function used to create a "GaussToElementPointInterpolator" inside Lua.

Please check the documentation for GmLuaGaussToPointInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateMatrix()

static int LuaCreateMatrix ( lua_State * L )

static

Function used to create a matrix inside Lua.

Parameters: Either of two options: 1) The number of lines + the number of columns. The matrix will be initialized with zeros 2) A single table with matrix data. The table can be a table of tables or a simple linear table. In the second case, the matrix will have a single column.

◆ LuaCreateNodeCloudToPointInterpolator()

static int LuaCreateNodeCloudToPointInterpolator ( lua_State * L )

static

Function used to create a "NodeCloudToPointInterpolator" inside Lua.

Please check the documentation for GmLuaNodeCloudToPointInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateNodeToCellPointInterpolator()

static int LuaCreateNodeToCellPointInterpolator ( lua_State * L )

static

Function used to create a "NodeToCellPointInterpolator" inside Lua.

Please check the documentation for GmLuaNodeToPointInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateNodeToElementPointInterpolator()

static int LuaCreateNodeToElementPointInterpolator ( lua_State * L )

static

Function used to create a "NodeToElementPointInterpolator" inside Lua.

Please check the documentation for GmLuaNodeToPointInterpolator::createInterpolator() for a detailed list of the possible parameter layouts.

◆ LuaCreateShapeFunction()

static int LuaCreateShapeFunction ( lua_State * L )

static

Function used to create a shape function object.

Parameters: A string describing the element type + an optional flag for requesting a linear shape function (default = false) or a string describing the element type + P and Q parameters + optional flag for linear shape function.

Returns the shape function object

◆ LuaCreateStateDump()

static int LuaCreateStateDump ( lua_State * L )

static

Function used to create a new state dump object.

Parameters: A table with the state options Returns the created object

◆ LuaCreateValueInfo()

static int LuaCreateValueInfo ( lua_State * L )

static

Function used to create a new value info object.

Parameters: A string describing the value kind + a table with the value description with the same syntax as used in the model definition.

Returns the created object

◆ LuaCreateVector()

static int LuaCreateVector ( lua_State * L )

static

Function used to create a vector (matrix with a single column) inside Lua.

Parameters: Either of two options: 1) The number of lines. The vector will be initialized with zeros 2) A single table with vector data

◆ LuaCurrentTime()

static int LuaCurrentTime ( lua_State * L )

static

Returns the current simulation time + the simulation time unit.

Can receive as a parameter a desired time unit (the current time will be converted to the requested unit – if no conversion is possible, returns nil)

◆ LuaElementBasedMeshGaussToNodesInterpolation()

static int LuaElementBasedMeshGaussToNodesInterpolation ( lua_State * L )

static

Function used to interpolate mesh node values from Gauss points with an element based approach.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) A string with the desired averaging method (options are: 'mean' and 'area') 4) A single Gauss value accessor proxy or a table with multiple accessors 5) A single node attribute accessor proxy or a table with multiple accessors 6) An accessor for coordinate values 7) An element mesh object or a CellGroupSet object

Returns true on success or false if the interpolation type is not supported.

◆ LuaEvalResults()

static int LuaEvalResults ( lua_State * L )

static

Function used to force the evaluation of result rules.

Parameters: An optional result set name. If missing, all result sets will be evaluated.

◆ LuaLogMemory()

static int LuaLogMemory ( lua_State * L )

static

Function used to print used memory using the logger infrastructure.

Parameters: The log message passed to GmLogMemoryUsage()

◆ LuaLogMsg()

static int LuaLogMsg ( lua_State * L )

static

Function used to print messages using the logger infrastructure.

Parameters: the logger level (a string) + the log message

◆ LuaMeshGaussToMeshGaussInterpolation()

static int LuaMeshGaussToMeshGaussInterpolation ( lua_State * L )

static

Function used to transfer Gauss values from a source mesh to Gauss values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) The search domain, specified by either the search radius or the number of closest nodes 4) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 5) The spatial index object used to find the nearest mesh nodes 6) A single source Gauss attribute accessor proxy (or a table with multiple accessors) 7) The destination mesh or the destination group of cells 8) A flag stating whether only active cells of the mesh should receive interpolated values 9) A single destination Gauss attribute accessor proxy (or a table with multiple accessors)

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaMeshGaussToMeshNodesInterpolation()

static int LuaMeshGaussToMeshNodesInterpolation ( lua_State * L )

static

Function used to transfer Gauss values from a source mesh to node values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) The search domain, specified by either the search radius or the number of closest nodes 4) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 5) The spatial index object used to find the nearest mesh nodes 6) A single source Gauss attribute accessor proxy (or a table with multiple accessors) 7) The destination mesh or the destination node set 8) A single destination node attribute accessor proxy (or a table with multiple accessors)

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaMeshNodesToMeshGaussInterpolation()

static int LuaMeshNodesToMeshGaussInterpolation ( lua_State * L )

static

Function used to transfer node values from a source mesh to Gauss values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) The search domain, specified by either the search radius or the number of closest nodes 4) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 5) The spatial index object used to find the nearest mesh nodes 6) A single source node attribute accessor proxy (or a table with multiple accessors) 7) The destination mesh or the destination group of cells 8) A flag stating whether only active cells of the mesh should receive interpolated values 9) A single destination Gauss attribute accessor proxy (or a table with multiple accessors)

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaMeshNodesToMeshNodesInterpolation()

static int LuaMeshNodesToMeshNodesInterpolation ( lua_State * L )

static

Function used to transfer node values from a source mesh to node values of a destination mesh using the given interpolation method. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) The search domain, specified by either the search radius or the number of closest nodes 4) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 5) The spatial index object used to find the nearest mesh nodes 6) A single source node attribute accessor proxy (or a table with multiple accessors) 7) The destination mesh or the destination node set 8) A single destination node attribute accessor proxy (or a table with multiple accessors)

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaNodeBasedMeshGaussToNodesInterpolation()

static int LuaNodeBasedMeshGaussToNodesInterpolation ( lua_State * L )

static

Function used to interpolate mesh node values from Gauss points with a node based approach.

Expected parameters on the Lua stack are: 1) A string with the desired interpolator type. 2) A type parameter whose value depends on the chosen interpolator. Can be nil but must be explicitly provided. 3) A boolean parameter specifying if only closests Gauss points should be used or not 4) A single Gauss value accessor proxy or a table with multiple accessors 5) A single node attribute accessor proxy or a table with multiple accessors 6) An accessor for coordinate values 7) An element mesh object or a CellGroupSet object

Returns true on success or false if the interpolation type is not supported.

◆ LuaNodeParallelCall()

static int LuaNodeParallelCall ( lua_State * L )

static

Executes a parallel node loop, calling the given function in each thread with a partition of the mesh nodes.

Parameters are the mesh, the type of nodes that should be traversed, the name of the function to execute and an optional table with execution parameters. It can also receive additional parameters that are forwarded to the called function.

MUST be called from the main thread only.

The mesh parameter can be either the mesh name or a mesh object
The type of nodes should be equal to 'geometry', 'ghost' or 'both', and defines which types of nodes will be included in the node partitions.
The function name must reference a global function included in a shared block section. When called, this function will receive as parameters an iterator object, followed by any aditional parameters.
If aditional parameters are given, the options table must appear in the call (but can be replaced by a nil value or by an empty table). Keep in mind that any parameter MUST be a value that can be transfered to another Lua environment, which rules out Lua functions. See the documentation for parallelCall() for a description of the allowed values and their behaviour.
The iterator object should be used to traverse the set of nodes that the function should work on. If taskNodes is the parameter name, it should be used in a for clause as 'for node in taskNodes() do'.
If the type of nodes is 'ghost', node indices returned by the iterator will be the ghost nodes "local" (zero based) indices. If equal to 'both', node indices will be their "linear" indices.
The worker function does not returns results. It can report errors by calling error(). Pending cancelation requests are handled by API calls, but if those are not being made frequently enough, explicit calls for checkForCancelation() can be made. Keep in mind that each call to the iterator object by the loop will also check for a cancelation.
The optional options table accepts four named fields: 'ntasks', 'nworkers' and 'strategy', whose behaviour is documented by the GmTaskManager::parallelNodeLoop() function, and a fourth field 'affinity' which, when present, should be a table with the same size as the effective number of tasks, storing the thread id that should be used to execute each task.

The call to nodeParallelCall() will itself return true if the worker executions ended ok, and false if any thread aborted. Notice that this function will not return at all (raising a "script canceled" error) if there is a pending cancelation request, as is common to all other API functions.

◆ LuaParallelCall()

static int LuaParallelCall ( lua_State * L )

static

Executes the named function in a parallel environment.

Parameters are the name of the function to be executed, the number of worker threads, a table with per task parameters and an optional table with task affinity info. It can also receive additional parameters that are forwarded to the called function, besides the per task parameters.

MUST be called from the main thread only.

The function name must reference a global function included in a shared block section. When called, this function will receive as parameters its correspondent task parameter from the task parameters table, followed by any aditional parameters.
The worker function does not returns results. It can report errors by calling error(). Pending cancelation requests are handled by API calls, but if those are not being made frequently enough, explicit calls for checkForCancelation() can be made.
The number of worker threads defines how many parallel threads willl be launched. A value of -1 means that the number of threads will be equal to the maximum allowed number of threads.
The per task parameter table should be a list with a number of entries equal to the number of parallel tasks to be executed. Each entry will be passed to one function invocation. Alternativelly, the table can be replaced by the number of tasks. In that case, each task will receive a task id as its task parameter (a number between 1 and the number of tasks).
The optional task affinity table, when present, should be a table with the same size as the effective number of tasks, storing the thread id that should be used to execute each task. When not given, a task can be executed by any thread. When supplying the call with extra parameters to be forwarded to the worker function, this parameter MUST be present (it should be nil if no affinity is desired).

Keep in mind that any parameter forwarded to the function MUST be a value that can be transfered to another Lua environment, which rules out Lua functions, for example. Allowed values are:

Basic types: numbers, strings, boolean and nil
Tables with number and string keys whose values are accepted. Can not have cycles. IMPORTANT: Tables are NOT shared among environments. Each one has its own table copy.
User data objects inheriting from GmLuaObject. Those objects are reference counted and released when garbage collected from the last Lua env. This objects ARE shared between environments! Other types of user data objects / light user data objects are NOT supported.

The call to parallelCall() will itself return true if the worker executions ended ok, and false if any thread aborted. Notice that this function will not return at all (raising a "script canceled" error) if there is a pending cancelation request, as is common to all other API functions.

◆ LuaPreviousTime()

static int LuaPreviousTime ( lua_State * L )

static

Returns the previous simulation time + the simulation time unit.

Can receive as a parameter a desired time unit (the previous time will be converted to the requested unit)

◆ LuaRegisterResultAttribute()

static int LuaRegisterResultAttribute ( lua_State * L )

static

Registers a new result attribute. Gets as parameters the attribute name, an optional description, the value unit, number of lines an columns and the value format string.

Returns the attribute id or nil if the attribute could not be registered.

◆ LuaSetThreadGlobal()

static int LuaSetThreadGlobal ( lua_State * L )

static

Sets the value of the named global variable in the given thread environment.

Parameters are the thread id (a value between 0 and maxWorkerThreads), the name of the global variable to be set and its new value. If the thread id parameter is missing, the same value will be used to initialize the global variable in every thread (including the main one, represented by thread id 0).

Keep in mind that the value being set MUST be a value that can be transfered to another Lua environment, which rules out Lua functions. See the documentation for parallelCall() for a description of the allowed values and their behaviour.

MUST be called from the main thread only.

◆ LuaSplineMeshGaussToMeshGaussInterpolation()

static int LuaSplineMeshGaussToMeshGaussInterpolation ( lua_State * L )

static

Function used to transfer Gauss values from a source mesh to Gauss values of a destination mesh using the spline interpolation method. Each destination Gauss value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) The search domain, specified by either the search radius or the number of closest nodes 2) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 3) The spatial index object used to find the nearest mesh nodes 4) A single source Gauss attribute accessor proxy (or a table with multiple accessors) 5) The destination mesh or the destination group of cells 6) A flag stating whether only active cells of the mesh should receive interpolated values 7) A single destination Gauss attribute accessor proxy (or a table with multiple accessors) 8) A string with the name of the desired solver used to compute the spline radial coefficients

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaSplineMeshGaussToMeshNodesInterpolation()

static int LuaSplineMeshGaussToMeshNodesInterpolation ( lua_State * L )

static

Function used to transfer Gauss values from a source mesh to node values of a destination mesh using the spline interpolation method. Each destination node value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) The search domain, specified by either the search radius or the number of closest nodes 2) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 3) The spatial index object used to find the nearest mesh nodes 4) A single source Gauss attribute accessor proxy (or a table with multiple accessors) 5) The destination mesh or the destination node set 6) A single destination node attribute accessor proxy (or a table with multiple accessors) 7) A string with the name of the desired solver used to compute the spline radial coefficients

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaSplineMeshNodesToMeshGaussInterpolation()

static int LuaSplineMeshNodesToMeshGaussInterpolation ( lua_State * L )

static

Function used to transfer node values from a source mesh to Gauss values of a destination mesh using the spline interpolation method. Each destination Gauss value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) The search domain, specified by either the search radius or the number of closest nodes 2) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 3) The spatial index object used to find the nearest mesh nodes 4) A single source node attribute accessor proxy (or a table with multiple accessors) 5) The destination mesh or the destination group of cells 6) A flag stating whether only active cells of the mesh should receive interpolated values 7) A single destination Gauss attribute accessor proxy (or a table with multiple accessors) 8) A string with the name of the desired solver used to compute the spline radial coefficients

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaSplineMeshNodesToMeshNodesInterpolation()

static int LuaSplineMeshNodesToMeshNodesInterpolation ( lua_State * L )

static

Function used to transfer node values from a source mesh to node values of a destination mesh using the spline interpolation method. Each destination node value is calculated via a spline interpolation. The CDR (compact domain radius) of the method can be both constant or defined using a constant number of closest nodes.

Expected parameters on the Lua stack are: 1) The search domain, specified by either the search radius or the number of closest nodes 2) A string defining the type of the previous parameter. Can be 'radius' or 'closest'. 3) The spatial index object used to find the nearest mesh nodes 4) A single source node attribute accessor proxy (or a table with multiple accessors) 5) The destination mesh or the destination node set 6) A single destination node attribute accessor proxy (or a table with multiple accessors) 7) A string with the name of the desired solver used to compute the spline radial coefficients

Returns false if the interpolation could not be performed (solver error, for example).

◆ LuaThreadGlobal()

static int LuaThreadGlobal ( lua_State * L )

static

Queries the value of the named global variable in the given thread environment.

Parameters are the thread id (a value between 0 and maxWorkerThreads) and the name of the global variable to be queried. If the thread id parameter is missing, all threads will be queried and the results packed in a table indexed by thread id (including the main one, represented by thread id 0).

MUST be called from the main thread only.

◆ LuaUndocCallPluginDataFunction()

static int LuaUndocCallPluginDataFunction ( lua_State * L )

static

Undocumented function used by regression tests to call a plugin data function. Important to enable regression tests for calling functions from different threads. NOT part of the official orchestration API.

Get as parameters the plugin data id, alias and function field name. Passes no parameters to the function and returns no results.