Simulation options

Simulation options are global configuration parameters that can be used to control certain aspects of the GeMA framework and some of its plugins. They can be defined on the GeMA configuration file or through the simulation object, the later having precedence over the first if both are present.

Available options:

Field	Description	Type	Default
maxThreads	An option that defines the maximum number of worker threads that will be used. If this option is missing, or is equal to -1, the processor's maximum number of concurrent threads will be used. A value of zero disables threading, meaning that tasks will be executed by the main thread. A negative value is interpreted as a multiple of the maximum number of concurrent threads (so a value of -2 means that the number of threads should be equal to twice the number of allowed concurrent threads by the processor / OS). A value of 1, although weird, can be used for testing: all tasks are executed by a single thread, different from the main one.	Integer	nil
	Example: maxThreads = 4
defNumTasks	An option that defines the default number of tasks in which a parallel job will be broken if unspecified in the parallel call. If this option is missing or is equal to 0, the number of tasks will default to the number of worker threads that will be used for the said job. A value greater than 0 specifies a fixed number of tasks while a value less than 0 specifies a multiple of the number of worker threads, so a value of 5 means exactly 5 tasks, while a value of -2 means that the number of tasks should be equal to twice the number of worker threads.	Integer	nil
	Example: defNumTasks = -10
defNodePartitionStrategy	An option that defines the default strategy that will be used to partition mesh nodes into tasks if unspecified in the parallel call. If this option is missing, the default will be to use a sequential strategy. Accepted values are "default" and "sequential".	String	nil
	Example: defNodePartitionStrategy = "sequential"
defCellPartitionStrategy	An option that defines the default strategy that will be used to partition mesh cells into tasks if unspecified in the parallel call. If this option is missing, the default will be to use a sequential strategy. Accepted values are "default" and "sequential".	String	nil
	Example: defCellPartitionStrategy = "sequential"
defMatrixBuildMode	The default strategy used for building global sparse matrices from element based local matrices. This value is used only if the field "matrixBuildMode" is not defined in the numeric solver definition. If this option is missing, the default mode for the numeric solver plugin will be used. Possible values are "armadilloMatrix", "tripletList", "hashLayout" and "vectorLayout".	String	nil
	Example: defMatrixBuildMode = "hashLayout"
defMatrixResizefactor	The resize factor used by some of the matrix building modes when needing to resize the auxiliar storage used to build the matrix. Should be a value greater than 1.0. This value is used only if the field "matrixResizeFactor" is not defined in the numeric solver definition. If this option is missing, the default is 2.0. Use a smaller value if you have confidence in the initial guess used to reserve initial space. Currently used by the "armadilloMatrix" and "tripletList" modes when favouring low memory strategies (see the "defMatrixLowMemory" parameter description).	Number > 1.0	nil
	Example: defMatrixResizefactor = 1.20
defMatrixLowMemory	An option that, when set to true, favours low memory strategies for building sparse matrices. If this option is missing, it will be adjusted automatically depending on the current memory usage. This value is used only if the field "matrixLowMemory" is not defined in the numeric solver definition.	Boolean	nil
	Example: defMatrixLowMemory = true
defMatrixSortStrategy	An option used together with the "armadilloMatrix" and "tripletList" modes to define how the triplet list will be merged (when using multiple buffers) and sorted. Possible values are "concat_pCopySort" (buffers are concatenated in parallel and then parallel sorted with a copy radix sort) and "inplaceSort_merge" (buffers are parallel sorted inplace with a serial radix sort and then merged). If this option is missing, the default depends on the low memory setting (see the "defMatrixLowMemory" parameter description): if true, "inplaceSort_merge" is used. Otherwise, "concat_pCopySort" is used (faster if there is enough memory). This value is used only if the field "matrixSortStrategy" is not defined in the numeric solver definition.	String	nil
	Example: defMatrixSortStrategy = "inplaceSort_merge"
defBCMerge	The default merge mode used when parsing boundary conditions. This value is used only if the field "merge" is not defined in the boundary condition. Possible values are 0 (no merging will be tried), or an integer number that limits merging to occur only if the boundary condition table has a maximum number of different line values (not number of lines) less than the given value, bounding the time needed for merging (merging will not be done if the boundary condition table has more than the given number of distinct property values). If you want to do a merge even if the table has a large number of distinct boundary condition property values, just use a big number in here, but be warned that the merge can be slow on those cases.	Integer	10
	Example: defBCMerge = 15
defBCSummaryPrint	The maximum number of lines that will be printed for boundary condition values when the model summary is printed. A value of 0 will ensure that all values are printed.	Integer	20
	Example: defBCSummaryPrint = 10
defBCTagValues	A table with default tag values used when exporting a representation of boundary condition application points to a file through the io process's saveNodeBcTags export option. This table is used to replace tag = true entries found in B.C. properties (see Data options). The table is indexed by boundary condition type name and then by property, and its values are the associated tags that will be used as the tag value, replacing true. Accepted values are the same values accepted by any B.C. property tag, including the possibility of being tables with ignoreDef and/or ignoreZero flags. A value of nil means that that property is not needed in the B.C. representation mask. For properties that have dimension equal to the mesh dimension, and whose tags should be individualised by dimension, like "f" for mechanical node concentrated forces, the tag table should be filled as if the mesh was 3D. For 2D and 1D cases, the extra tags will be automatically removed. If two physics share a B.C type name, their properties should be placed in the same sub-table. We don't expect two physics with the same B.C. type names and same property names to represent different concepts, so their tags should be the same anyway.	Table	{}
	Example: defBCTagValues = {["node displacements"] = {ux = 1, uy = 2, uz = 3}, ["node concentrated forces"] = {f = {4, 5, 6}}}
disabledWarnings	A table that can be used to selectively disable some of the warning messages that can be emmited by GeMA and its plugins. Each warning message that can be disabled in this way is represented by a string. Adding this string to the table disables that warning. Available options: - PrescribedForceForInvalidDof: Warning emited by the FEM assembler if a prescribed force boundary condition was added in a node to an invalid degree of freedom for the associated physics. - PrescribedForceForFixedDof: Warning emited by the FEM assembler if a prescribed force boundary condition was added to a degree of freedom that was already fixed by another boundary condition. - FixedBcForInvalidDof: Warning emited by the FEM assembler if a fixed degree of freedom boundary condition was added in a node to an invalid degree of freedom for the associated physics. - ConflictingFixedBcValue: Warning emited by the FEM assembler if two fixed degree of freedom boundary conditions, with different prescribed values, are applied to the same degree of freedom. - InvalidFunctionParameterIndex: Warning emited by GeMA when evaluating a user function parameter if the parameter value can not be evaluated at the given index. That can happend, for example, if the function is evaluated over a ghost node and the expected parameter has values for geometry nodes only. In that case, the parameter assumes a zero value.	Table	{}
	Example: disabledWarnings = {"PrescribedForceForInvalidDof", "ConflictingFixedBcValue"}
defDumpStateMode	The default mode when creating a state dump. This value is used only if the mode field is not explicitely given when creating the state. Possible values are "memory" (dump state is created in memory), "file" (dump state is created on disk) or "auto" (state is saved either on memory or on file depending on memory availablity). If this option is missing, the default will be "auto".	String	nil
	Example: defDumpStateMode = "file"
defDumpStateFile	The path + name of the dump file when the state dump mode is equal to "file" or "auto". This value is used only if the file field is not explicitely given when creating the state. If this option is missing, the default will be "$SIMULATIONDIR/$SIMULATIONNAME.dmp".	String	nil
	Example: defDumpStateFile = "$SIMULATIONDIR/myDumpFile.dmp"
defDumpStateSaveAndRestore	When working with a 'file' state dump this flag defines if the file should enable the possibility of a dump file written in a GeMA session being loaded in another one. This value is used only if the saveAndRestore field is not explicitely given when creating the state. If this option is missing, the default will be false.	Boolean	nil
	Example: defDumpStateSaveAndRestore = true
defDumpStateCompression	Defines if the state dump should be compressed (using zlib) or not. This value is used only if the compression field is not explicitely given when creating the state. Valid values are integer numbers between 0 (no compression) and 9 (maximum compression) or -1 (default zlib compression). If this option is missing, the default will be 0.	Integer	nil
	Example: defDumpStateCompression = -1
defDumpStateCompressionMinSize	When state dump compression is enabled, defines the minimum size (in bytes) that a saved data item must have to be compressed. Data items smaller than this value will not be compressed at all. This value is used only if the compressionMinSize field is not explicitely given when creating the state. If this option is missing, the default will be 4k. Must be a value greater than 0.	Integer	nil
	Example: defDumpStateCompressionMinSize = 16*1024
defDumpStateGrowFactorA	When saving state dumps to file, and dump items can grow in size over time, it might be more efficient to pre-store space for the item growing. This is done by applying a linear expansion to the data item size: filesize = A * datasize + B. This parameter gives the A factor, which should be >= 1.0. This value is used only if the growFactorA field is not explicitely given when creating the state. If this option is missing, the default will be 1.2 (20% extra space reserved for growing).	Number >= 1.0	nil
	Example: defDumpStateGrowFactorA = 1.2
defDumpStateGrowFactorB	When saving state dumps to file, and dump items can grow in size over time, it might be more efficient to pre-store space for the item growing. This is done by applying a linear expansion to the data item size: filesize = A * datasize + B. This parameter gives the B factor. This value is used only if the growFactorB field is not explicitely given when creating the state. If this option is missing, the default will be 0.	Integer	nil
	Example: defDumpStateGrowFactorB = 1024
defCtoNPreferGeometric	An option defining the default algorithm used by calls to shape:cartesianToNatural(), both in the orchestration or inside the GeMA core / plugins. When set to true, calls to the shape function method for converting cartesian to natural coordinates will prefer (if available) geometric methods over gradient based methods. If this option is missing, the default will be false.	Boolean	nil
	Example: defCtoNPreferGeometric = true
defCtoNGradTol	An option defining the default convergence tolerance for gradient based methods used by calls to shape:cartesianToNatural(), both in the orchestration or inside the GeMA core / plugins. Ignored if using geometric based methods. If this option is missing, the default will be 1e-6.	Number	nil
	Example: defCtoNGradTol = 1e-10
defCtoNMaxGradIter	An option defining the naximum number of iterations for gradient based methods used by calls to shape:cartesianToNatural(), both in the orchestration or inside the GeMA core / plugins. Ignored if using geometric based methods. If this option is missing, the default will be 15.	Integer	nil
	Example: defCtoNMaxGradIter = 25
defCtoNOutsideNatTol	An option defining the behaviour used by calls to shape:cartesianToNatural(), both in the orchestration or inside the GeMA core / plugins, when treating coordinates outside, but very close to the element border. When greater than 0.0, this value gives a "snap" tolerance within which cartesian coordinates slightly outside the element will be snapped to the element border when converting cartesian to natural coordinates. For example, if the tolerance is 1e-3 and the conversion yields a natural coordinate of 1.0002, the coordinate will be changed to 1.0 and the point considered internal to the element. If this option is missing, the default will be 0.0 (no snap).	Number	nil
	Example: defCtoNOutsideNatTol = 1e-3
defDiscSnapTol	An option defining the default snap tolerance used when calculating intersections between discontinuities and mesh cells to snap intersection points to nodes, edges or faces. The value is given as a percentage and a value of 0.05 means a 5% tolerance. See comments on the snapTol option field at the discontinuity set object documentation for an in-depth explanation of the tolerance role. If this option is missing, the default will be 0.0 (no snap).	Number	0.05
	Example: defDiscSnapTol = 0.01