Global variables

A few global variables are published on the Lua global environment by GeMA itself, and are available for being used during the orchestration and/or during the model loading.

Index:

• User parameters
  • userParams
  • userParamsStr
• Options and Constants
  • options
  • constants
• Model Data
  • modelData
• Thread management
  • threadId
  • numProcCores
  • maxProcThreads
  • maxWorkerThreads
• Dump script library control
  • userRestoreParameters
  • userNoDumpRequested

User parameters

userParams
Description:	A global variable filled with the value provided by the user through the -u command line option. Can be of any Lua type, depending on the syntax used when passing the parameter. In particular, Lua tables can be used to provide the script with several run-time values. See the comments on Executing a simulation.

Example:

-- Assuming that gema was called with gema -u "{a = 10, b = 20}"
local a = userParams.a
local b = userParams.b

userParamsStr
Description:	Similar to userParams , this variable contains the string with the -u parameter value, before it was parsed by the Lua environment.

Example:

-- Assuming that gema was called with gema -u "{a = 10, b = 20}"
print(type(userParams))    -- Will print table
print(type(userParamsStr)) -- Will print string
print(userParams)          -- Will print a table address
print(userParamsStr)       -- Will print {a = 10, b = 20}

Options and Constants

options
Description:	A global table, available during both model loading and orchestration, storing the set of user defined values for global simulation options. Includes options defined through the simulation object and through the configuration file (with preference for the previous if a field is defined in both). The table is keyed by option names.

Example:

local maxt = options.maxThreads

constants

Description:

A global table, available during both model loading and orchestration, storing the set of user defined values for global simulation constants. Includes options defined through the simulation object and through the configuration file (with preference for the previous if a field is defined in both). The table is keyed by constant names. This table can also have entries for constants defined by plugins. Each plugin can define its own set of constants in the subtable constants.pluginName, where pluginName is the same name used for referencing the plugin. Most physics plugins use this option to publish maps associating material types with their codes. This maps are commonly referenced in property set definitions through constMap entries, such as in constMap = constants.HydroFemPhysics.materialModels.

Example:

PropertySet
{
  id          = 'HydroProp',
  typeName    = 'GemaPropertySet',
  description = 'Hydraulic properties',
  properties  = {  
    {id = 'K',  description = 'Hydraulic permeability',  unit = 'm/s'},
    {id = 'Kww',  description = 'Bulk modulus of water',  unit = 'kPa'},
    {id = 'gw',  description = 'Specific weight of water', unit = 'kN/m3'},
    {id = 'Pht', description = 'Porosity', unit = ''},
    {id = 'Bp', description = 'Pore compressibility', unit = '1/kPa'},  
    {id = 'material', description = 'Hydraulic material type', constMap = constants.HydroFemPhysics.materialModels} 
  },
  values = {
    {K = 3.38e-06, Kww = 1.0e40, gw = 10, Pht = 0.25, Bp = 0.0, material = 'saturated'},
  }
}

Model Data

modelData
Description:	The global variable giving access to the global model data object, which stores information about top-level model objects such as meshes, property sets and boundary conditions. Available only in the orchestration script.

Example:

local m = modelData:mesh('myMeshName')

Thread management

threadId
Description:	A global variable, available during the orchestration script, storing the current thread id. This value will be 0 for the main thread and a unique number between 1 and maxWorkerThreads for worker threads. It is usefull for collecting "per-thread" results.

Example:

SharedCodeBegin{}  

--
-- A task function to be called from nodeParallelCall()
--
function nodef(nodeTask, ...)
  print('Hello from thread ', threadId)
end

SharedCodeEnd{}

numProcCores
Description:	A global variable, defined only in the main thread, during the orchestration script, storing the number of processor cores available in the current hardware. Can be used to fine tune the number of desired worker threads in a parallel call.

Example:

-- Parallel call will use all available cores minus 1
local callOptions = { nworkers = numProcCores - 1 }

nodeParallelCall('meshName', 'geometry', 'nodef', callOptions)

maxProcThreads
Description:	A global variable, defined only in the main thread, during the orchestration script, storing the maximum number of concurrent threads supported by the current hardware. This can be different from numProcCores if the hardware supports Hyper-threading or similar technologies. Can be used to fine tune the number of desired worker threads in a parallel call.

Example:

-- Parallel call will use all available concurrent threads minus 1
local callOptions = { nworkers = maxProcThreads - 1 }

nodeParallelCall('meshName', 'geometry', 'nodef', callOptions)

maxWorkerThreads
Description:	A global variable, defined only in the main thread, during the orchestration script, storing the maximum number of worker threads that can be used in a parallel call. This value will be the same as options.maxThreads if that option was set at the simulation object or at the configuration file. Otherwise, it will be equal to maxProcThreads (the default if the maxThreads option is missing).

Example:

local results = threadGlobal('threadResults') -- Tasks stored results in the global var 'threadResults'

for i = 0, maxWorkerThreads do
  print(string.format('Thread %d returned %s', i, tostring(results[i])))
end

Dump script library control

userRestoreParameters
Description:	A global variable different from nil if the user provided either one of the following command line options: -restore, -restoretag or -restorelist. In that case, its value will be a Lua table with the fields described below. See the comments on Executing a simulation. Usually interpreted by the dump script library. When this library is loaded, this variable is set to nil to prevent global namespace polution and its previous contents can be queried through the dump library itself.
Fields:	state	The state number provided to the -restore command line option (either a positive number defining the simulation step where the state was saved or a negative number giving the state's backward position on the dump series, where -1 refers to the last saved state, -2 to the previous and so on). If the simulation was started with the -restoretag or -restorelist command options, this field will be filled with 0 (which is not a valid state).
	tag	The state tag provided to the -restoretag command line option. Otherwise, filled with the empty string.
	list	A boolean value filled with true if the -restorelist option was present at the command line.
	file	The file name provided to the -restorefile command line option. Otherwise, filled with the empty string.
	noParRestore	A boolean value filled with true if the -noparrestore option was present at the command line.

userNoDumpRequested
Description:	A boolean global variable filled with true if the user provided the -nodump command line option. See the comments on Executing a simulation. Usually interpreted by the dump script library. When this library is loaded, this variable is set to nil to prevent global namespace polution and its previous contents can be queried through the dump library itself.