Several functions are published on the Lua global environment by GeMA itself, and are available for being used during the orchestration and/or model loading. Functions used to create objects are documented together with the object type documentation and are not included here. This is also the case with functions for data interpolation and parallel calls, which are documented in their specific pages (and are available only during the orchestration step).

Index:

Number comparisson functions
- equal()
- nequal()
- lt()
- lte()
- gt()
- gte()
Unit conversion functions
- convert()
- checkUnit()
Time related functions
- currentTime()
- previousTime()
- setCurrentTime()
- setPreviousTime()
- setCurrentTimeUnit()
Time measuring functions
- startTimer()
- elapsedTime()
- resetTimer()
Ghost node handling functions
- isMeshGhostNode()
- setMeshGhostFlag()
- clearMeshGhostFlag()
String translation and formatting functions
- tr()
- string:arg()
- string:int()
- string:num()
- string:str()
- string:strs()
Other functions
- checkForCancelation()
- translatePath()
- cleanPath()
- logMsg()
- logMemory()
- warn()
- cellTypeList()

Number comparisson functions

equal(a, b, relTol, absTol) nequal(a, b, relTol, absTol) lt(a, b, relTol, absTol) lte(a, b, relTol, absTol) gt(a, b, relTol, absTol) gte(a, b, relTol, absTol)
Description:	Double comparisson functions (`nequal` stands for not equal, `lt` for less than, `lte` for less than or equal, `gt` for greater than and `gte` for greater than or equal). Available during both model loading and orchestration. Comparissons are done using both a relative tolerance and an absolute tolerance to treat numbers close to zero. Tip: When comparing for equality, and one of the factors is a zero value, consider adding 1.0 to both sides of the comparisson, i.e. use `equal(a + 1.0, 1.0)` instead of `equal(a, 0.0)` in order for the relative tolerance to be meaningfull.
Parameters:	a, b	The values to be compared.
	relTol	The relative tolerance used for comparisson. Two numbers are considered equal if their absolute difference is smaller or equal to `relTol * max(a, b)`. Default = 1e-8 (0.000001%).
	absTol	Absolute tolerance used for comparisson between values close to zero. Default = 1e-12.
Returns:	Returns true or false, according to the given values and on the chosen comparisson function.

Example:

assert(equal(1.0, 0.999999999) == true)
assert(lt (1.0, 2.0        )  == true)
assert(lt (1.0, 0.999999999)  == false)
assert(lte(1.0, 0.999999999)  == true)
assert(gte(1.0, 1.000000001)  == true)
assert(gte(1.0, 1.0001)       == false)
assert(gte(1.0, 1.0001, 1e-3) == true)

Unit conversion functions

convert(value, srcUnit, dstUnit)
Description:	Converts the given value from the source unit to the destination unit. Available during both model loading and orchestration. See tips on the Working with units page.
Parameters:	value	The value to be converted, expressed in the source unit.
	srcUnit	The source unit string.
	dstUnit	The destination unit string.
Returns:	Returns the converted value or `nil` if the conversion is not possible (unknown or incompatible units).

Example:

local convertedDistance = convert(10, 'm', 'cm') -- Returns 1000

local convertedTime = convert(1, 'yr', 's') -- Returns 3.15569e7

checkUnit(unit)
Description:	Check if an unit is a known unit or not. Available during both model loading and orchestration. See tips on the Working with units page.
Parameters:	unit - The unit string.
Returns:	Returns true if the unit is a known unit, false otherwise.

Example:

checkUnit('deg') -- Returns false

checkUnit('degree') -- Returns true

Time related functions

currentTime(unit)
Description:	Returns the current simulation time, optionally converted to a requested unit. Also returns the time unit. Available during the orchestration.
Parameters:	unit - An optional unit to which the current time should be converted.
Returns:	Returns the current time, or `nil` if the requested unit is invalid, + the unit of the returned time.

Example:

local time       = currentTime()     -- Get the current time, ignoring the unit.
local time, unit = currentTime()     -- Get the current time and its unit.
local timems     = currentTime('ms') -- Returns the current time converted to mili seconds. Ignores the unit.

previousTime(unit)
Description:	Returns the previous simulation time (the time of the previous time-step), optionally converted to a requested unit. Also returns the time unit. Available during the orchestration.
Parameters:	unit - An optional unit to which the previous time should be converted.
Returns:	Returns the previous time, or `nil` if the requested unit is invalid, + the unit of the returned time.

Example:

local time       = previousTime()     -- Get the previous time, ignoring the unit.
local time, unit = previousTime()     -- Get the previous time and its unit.
local timems     = previousTime('ms') -- Returns the previous time converted to mili seconds. Ignores the unit.

setCurrentTime(time, updatePrev)
Description:	Updates the current simulation time. Expects the time value to be expressed in the unit set with setCurrentTimeUnit`()` (or in seconds if this function was never called). Available during the orchestration.
Parameters:	time	The new current simulation time, expressed in the current simulation time unit.
Parameters:	updatePrev	An optional parameter. If absent or set to `true`, the previous time will be updated to the current time (before the current time update), unless `time` is equal to 0.0 when the previous time will also be set to 0.0. When set to `false`, the previous time is not changed.
Returns:	Nothing.

Example:

setCurrentTime(0.0) -- Resets the simulation time to zero

setPreviousTime(time)
Description:	Updates the previous simulation time. Expects the time value to be expressed in the unit set with setCurrentTimeUnit`()` (or in seconds if this function was never called). Available during the orchestration.
Parameters:	time - The new previous simulation time, expressed in the current simulation time unit.
Returns:	Nothing.

Example:

setPreviousTime(0.0) -- Resets the previous simulation time to zero

setCurrentTimeUnit(unit)
Description:	Sets the current simulation time unit. Values passed to setCurrentTime`()` should be expressed on this unit. If this function is never called, by default, the simulation time will be expressed in seconds. Available during the orchestration.
Parameters:	unit - The desired time unit.
Returns:	Nothing.

Example:

setCurrentTimeUnit('Myr') -- Work with a simulation time in millions of years.

Time measuring functions

startTimer()
Description:	Starts a timer that can be used to measure the elapsed time between this moment and a subsequent call to elapsedTime`()`. Available during the orchestration.
Parameters:	None.
Returns:	Returns the timer object that should be passed as a parameter in calls to elapsedTime`()`.

Example:

local t = startTimer()
  -- Do some lengthy computation
local dt = elapsedTime(t)
print(tr('Operation finished in %1 seconds'):num(dt, nil, 2))   

elapsedTime(timer)
Description:	Returns the elapsed time in seconds between this call and the the last call to either startTimer`()` or resetTimer`()`. Available during the orchestration.
Parameters:	timer - The timer object returned by the call to startTimer`()`.
Returns:	Returns the elapsed time in seconds.

Example:

local t = startTimer()
  -- Do some lengthy computation
local dt = elapsedTime(t)
print(tr('Operation finished in %1 seconds'):num(dt, nil, 2))   

resetTimer(timer)
Description:	Restarts a timer created by startTimer`()`. The next call to elapsedTime`()` will measure the time elapsed from this moment on. Available during the orchestration.
Parameters:	timer - The timer object returned by the call to startTimer`()`.
Returns:	Nothing.

Example:

local t = startTimer()
  -- Do some lengthy computation
local dt = elapsedTime(t)
print(tr('First operation finished in %1 seconds'):num(dt, nil, 2))   
resetTimer(t)
  -- Do another lengthy computation
dt = elapsedTime(t)
print(tr('Second operation finished in %1 seconds'):num(dt, nil, 2))   

Ghost node handling functions

isMeshGhostNode(index)
Description:	Check if an index is a ghost node index (has its high bit set). Ghost node indices are values that vary from 1 to `mesh:`numGhostNodes`()`, with their high bit set in order to make a distinction between common indices, sometimes also called geometry indices, and ghost node indices. That means that, for example, the first two ghost nodes have, respectively, an index equal to 0x80000001 and 0x80000002 if node indexes are stored as 32 bit integers. Available during the orchestration.
Parameters:	index - The index to be checked.
Returns:	Returns true if the index is a ghost index, false if not.

Example:

assert(isMeshGhostNode(1) == false)

assert(isMeshGhostNode(setMeshGhostFlag(1)) == true)

setMeshGhostFlag(index)
Description:	Returns a copy of the given index with its high bit set, turning it into a ghost index. Available during the orchestration.
Parameters:	index - The index that will have its high bit set.
Returns:	Returns the given index with its high bit set to 1.

Example:

local gn = setMeshGhostFlag(1)

assert(isMeshGhostNode(gn))

clearMeshGhostFlag(index)
Description:	Returns a copy of the given index with its high bit cleared, turning it into a normal node index. Available during the orchestration.
Parameters:	index - The index that will have its high bit cleared.
Returns:	Returns the given index with its high bit set to 0.

Example:

local gn = setMeshGhostFlag(1)
assert(isMeshGhostNode(gn))
local node = clearMeshGhostFlag(gn)
assert(not isMeshGhostNode(node))

String translation and formatting functions

tr(str)
Description:	Translates the given string according to the configured language translator and the translation database. If there is no configured target language or `str` is not present in the translation database for that language, returns `str` itself. When creating translatable strings, with dynamic contents, use the positional argument replacement functions given by `string:`arg`()` and friends so that parameter order can be changed on the translated string. Although this function can be used in simulation model files, it was created to be used in general scripts from the scripts library who really can benefit from string translations while presenting error messages. Available during both model loading and orchestration. At present, there are no configured language translators available for GeMA.
Parameters:	str - The string to be translated.
Returns:	Returns the translated string or `str` itself if there is no installed translator or if the given string does not have a configured translation.

Example:

print(tr('A translatable string'))

print(tr('A string with %1 argument%2'):int(2):str('s')) -- Prints "A string with 2 arguments", possibly translated...

string:arg(formater, ...)
Description:	String method that replaces on the string the lowest numbered placeholder (%1, %2, %3, ...) by the given value, formated according to `formater`, through the use of `string.format()`. Placeholders don't need to be in order on the string. Available during both model loading and orchestration.
Parameters:	formater	The formater string using the syntax recognized by the standard Lua `string.format()` function.
Parameters:	...	Formater values required by the given formater string.
Returns:	Returns the string with one format parameter replaced or the string itself if no placeholders where found.

Example:

print(tr('A string with %1 argument%2'):arg('%d', 2):arg('%s', 's')) -- Prints "A string with 2 arguments", possibly translated

print(('A string with %1 argument%2'):arg('%03d', 2):arg('%s', 's')) -- Prints "A string with 002 arguments"

string:int(value, width)
Description:	String method for replacing the next placeholder by a formated integer value. Equivalent to calling `string:`arg`("%wd", value)` with `w` replaced by the `width` parameter or removed if `width` is `nil`. Available during both model loading and orchestration.
Parameters:	value	The integer value to be formated.
Parameters:	width	An optional field width.
Returns:	Returns the string with one format parameter replaced or the string itself if no placeholders where found.

Example:

print(tr('A string with %1 argument%2'):int(2):str('s')) -- Prints "A string with 2 arguments", possibly translated...

print(('A string with [%1] argument%2'):int(2, 5):str('s')) -- Prints "A string with [ 2] arguments"

string:num(value, width, prec, fmt)
Description:	String method for replacing the next placeholder by a formated number. Equivalent to calling `string:`arg`("%w.pf", value)` with `w` replaced by the `width` parameter, `p` by `prec` and `f` by `fmt`. All of them are optional. If `width` or `prec` are `nil`, they will be removed from the format string. If `fmt` is `nil`, an "f" value will be used. Available during both model loading and orchestration.
Parameters:	value	The numeric value to be formated.
	width	An optional field width.
	prec	An optional field precision.
	fmt	The format type ('f', 'g', 'd, 'x', ...).
Returns:	Returns the string with one format parameter replaced or the string itself if no placeholders where found.

Example:

print(tr('A number: %1'):num(3.14, 6, 4))

print(('A number: %1'):num(3.14, 6, 4))

string:str(value, width)
Description:	String method for replacing the next placeholder by a string value. Equivalent to calling `string:`arg`("%ws", value)` with `w` replaced by the `width` parameter or removed if `width` is `nil`. Available during both model loading and orchestration.
Parameters:	value	The string to be formated.
Parameters:	width	An optional field width.
Returns:	Returns the string with one format parameter replaced or the string itself if no placeholders where found.

Example:

print(tr('A string: [%1]'):str('hello', 7)) -- Prints "A string: [ hello]", possibly translated...

print(('A string: [%1]'):str('hello', 7)) -- Prints "A string: [ hello]"

string:strs(...)
Description:	String method for replacing several placeholders by the given string values. Equivalent to calling `string:`arg`("%s", arg)` several times, one for each function argument. Available during both model loading and orchestration.
Parameters:	... - The list of strings to be formated.
Returns:	Returns the string with as many format placeholders replaced as strings on `...` or the string itself if no placeholders where found.

Example:

print(tr('3 strings: %1, %2, %3'):strs('first', 'second', 'third'))

print(('3 strings: %1, %2, %3'):strs('first', 'second', 'third'))

Other functions

checkForCancelation()
Description:	Checks for a pending cancelation request. If there is one, aborts the script processing by raising a Lua error. Cancelation requests can be received when the monitor server is active and cancelation requests are enabled. Available during both model loading and orchestration. Keep in mind that cancelation checks are done automatically in every process or API call during the orchestration and so calling this function is needed only if your code includes a Lua loop that takes a long time and only includes standard Lua calls. Also, when writing functions for using with node and cell parallel calls, the iterator object already does a cancelation check per loop iteration.
Parameters:	None.
Returns:	Returns nothing. If there is a pending cancelation request, this function does not return at all (calls `error()`).

Example:

for i = 1, 1e9 do -- big loop
  -- End script if the user asked to cancel the simulation through the simulation monitor
  checkForCancelation()  
  -- Do your computation that does not calls API methods or processes
  ...
end

translatePath(path)
Description:	Translates path macros in `path`, expanding them to the correct path. Allows the usage of GeMA macros when opening or creating files directly with Lua file manipulation functions. Not needed when calling `dofile()` since the actual function is overriden by GeMA to already translate paths. This function also cleans the path, converting path separators to `/`, removing `.` and `..` references. It also removes path separators from the end of the path. Available during both model loading and orchestration.
Parameters:	path - The path to be translated.
Returns:	Returns the translated path.

Example:

local path = translatePath('$SIMULATIONDIR/myfile.txt')

local file = io.open(path, 'w+') -- Creates a new ouput file on the same path as the simulation file

cleanPath(path)
Description:	Returns a cleaned version of the given path, converting path separators to `/`, removing `.` and `..` references. It also removes path separators from the end of the path. Similar to calling translatePath`()` but without macro conversions. Available during both model loading and orchestration.
Parameters:	path - The path to be cleaned.
Returns:	Returns the cleaned path.

Example:

local path = cleanPath('.\\teste\\xxx\\..\\$SIMULATIONDIR/myfile.txt')

print(path) -- Will print teste/$SIMULATIONDIR/myfile.txt

logMsg(level, msg)
Description:	Writes a message using the logger infrastructure. The message will be printed on the console and / or in the log file, depending on the current configuration options. The standard Lua `print()` function also writes to the logger, but it always uses the `info` level, while `logMsg` allows the user to define the intended level. Available during both model loading and orchestration.
Parameters:	level	The logger level with which the message should be printed. Available options are: `"trace"`, `"extinfo"`, `"info"`, `"warning"`, `"error"`, `"fatal"`, `"time"` and `"memory"`. See the configuration options page for an explanation of each level intended purpose.
Parameters:	msg	The message to be printed (a single string).
Returns:	Nothing.

Example:

logMsg('extinfo', 'A message')

logMsg('error', 'An error message')

logMemory(msg)
Description:	Writes a `"memory"` message using the logger infrastructure. The message will include the given user string, being formated like `"Memory usage " + msg + " in Mb [phys, virtual]:"`, followed by the actual memory usage numbers. The message will be printed on the console and / or in the log file, depending on the current configuration options. Available during both model loading and orchestration.
Parameters:	msg - The user string that will be inserted in the logged message, together with the current memory usage.
Returns:	Nothing.

Example:

-- The line bellow will print a message stating:
-- "Memory usage before FEM solving in Mb ....."
logMemory('before FEM solving')

warn(...)
Description:	Writes a warning message using the logger infrastructure. The message will be printed on the console and / or in the log file, depending on the current configuration options. Works like the standard Lua `print()` function, only using the `warning` level instead of the `info` level. Available during both model loading and orchestration.
Parameters:	... - The set of messages to print. Each one is converted to a string with the `tostring()` Lua function.
Returns:	Nothing.

Example:

warn('A warning message')

warn('Another', 'one', 'splitted in several parameters')

cellTypeList()
Description:	Returns a Lua table filled with known cell type names, in the internal GeMA type order.
Parameters:	None.
Returns:	Returns the cell type list.

Example:

local typeList = cellTypeList()