Value info objects are responsible for storing a description (metadata) for the values stored on state variables, properties and attributes (for nodes, cells, Gauss points and boundary conditions), as well as node coordinates. Refer to the Data options page for an overview of the avilable information.

Value info objects are returned by several methods from mesh objects, property set objects and boundary condition objects. New value info objects can be created by calling the ValueInfo() function.

Example:

local m    = modelData:mesh('myMeshName')
local info = m:nodeCoordInfo()
local newInfo = ValueInfo('gauss attribute', {id = 'test', description = 'Test attribute', unit = 'm'})

Index:

Creating a value info object
- ValueInfo()
Global metadata methods
- info:id()
- info:description()
- info:kind()
- info:isNodeBased()
- info:affectedNodes()
Data description methods
- info:storageType()
- info:unit()
- info:dimType()
- info:isScalar()
- info:size()
- info:nlin()
- info:ncol()
- info:defValue()
- info:canStoreFunctions()
- info:allocMode()
- info:allocStrategy()
Other methods
- info:history()
- info:setHistory()
- info:ruleSet()
- info:setRuleSet()
- info:format()
- info:setFormat()
- info:constMap()
- info:print()

Creating a value info object

ValueInfo(valueKind, valueDefTable)
Description:	Creates a new value info object, suitable to be used in calls for adding new value sets to the mesh (like `mesh:`addNodeValueSet`()`).
Parameters:	valueKind	String with the desired value kind. Available otpions are: `"node coordinate"`, `"node attribute"`, `"node state variable"`, `"cell attribute"`, `"gauss attribute"`, `"property"`, `"b.c. node property"` and `"b.c. bound. property"`.
Parameters:	valueDefTable	A table with a description of the new value, defined with the same syntax used while defining data in the model definition. The available table fields are described on the Data options page.
Returns:	Returns a new value info object.

Example:

local newInfo = ValueInfo('node attribute', {id = 'test', description = 'Test attribute', 
                                             unit = 'kPa', defVal = 'Medium', format = '.4f',
                                             constMap = {High = 150,  Medium = 100, Low = 50}
                                            })

Global metadata methods

info:id()
Description:	Returns the value name (id).
Parameters:	None.
Returns:	Returns a string with the value name.

Example:

local id = info:id()

info:description()
Description:	Returns the value description.
Parameters:	None.
Returns:	Returns a string with the value description.

Example:

print(info:description())

info:kind()
Description:	Returns the value kind (type of value: state variable, node attribute, etc).
Parameters:	None.
Returns:	A string with the value kind. Availabe options are: `"node coordinate"`, `"node attribute"`, `"node state variable"`, `"cell attribute"`, `"gauss attribute"`, `"property"`, `"b.c. node property"` and `"b.c. bound. property"`.

Example:

print(info:kind())

info:isNodeBased()
Description:	Returns true if the set kind is a node based set (node coordinates, attributes or state variables), false otherwise.
Parameters:	None.
Returns:	Returns true if the value is node based, false otherwise.

Example:

if info:isNodeBased() then
  ...
end

info:affectedNodes()
Description:	Returns at which node types values are stored. A `"geometry"` return means that values are stored for geometry nodes only. A `"ghost"` return, for ghost nodes only, and a `"both"` return means that values are stored at every mesh node.
Parameters:	None.
Returns:	Returns a string with the type of affected nodes (`"geometry"`, `"ghost"` or `"both"`). Returns `"geometry"` if the type is not node based.

Example:

print(info:affectedNodes())

Data description methods

info:storageType()
Description:	Returns the desired data type in which data values are supposed to be stored. Might not be how the data is really stored.
Parameters:	None.
Returns:	Returns a string with the storage type (`"double"`, `"float"`, `"int32"`, `"int16"`, `"byte"`, `"uint32"`, `"uint16"` or `"ubyte"`).

Example:

print(info:storageType())

info:unit()
Description:	Returns the unit in which data values are stored. See also the Working with units page.
Parameters:	None.
Returns:	Returns a string with the value unit.

Example:

print(info:unit())

info:dimType()
Description:	Returns a string describing the value type. Possible values are `"scalar"`, `"vector"` and `"matrix"`.
Parameters:	None.
Returns:	Returns a string with the value type.

Example:

print(info:dimType())

info:isScalar()
Description:	Checks if the data type is a scalar or not. Equivalent to testing if `info:`dimType`()` returns `"scalar"`.
Parameters:	None.
Returns:	Returns true for scalar values, false otherwise.

Example:

if info:isScalar() then
  ...
end

info:size()
Description:	Returns the value size, i.e., the number of double values stored for each value entry. Equal to nlin`()` * ncol`()`.
Parameters:	None.
Returns:	Returns the value size.

Example:

local size = info:size()

info:nlin()
Description:	Returns the number of lines in each value entry. Will be equal to the number of lines for vector and matrix values and to 1 for scalar values.
Parameters:	None.
Returns:	Returns the number of lines in a value.

Example:

local nlin = info:nlin()

info:ncol()
Description:	Returns the number of columns in each value entry. Will be equal to the number of columns for matrix values and to 1 for vector or scalar values.
Parameters:	None.
Returns:	Returns the number of columns in a value.

Example:

local ncol = info:ncol()

info:defValue()
Description:	Returns the default value associated with this value set.
Parameters:	None.
Returns:	Returns either a string, a number or a Lua table. If the default value is a user function, returns the function name as a string. Otherwise, returns a number for scalar values or a Lua table with dimension equal to `info:`size`()` for vectors and matrices. Matrix values are organized in the Lua table by column major format (the same used in the FORTRAN language).

Example:

local defval = info:defValue()

info:canStoreFunctions()
Description:	Returns a boolean checking if values associated to this value set can be expressed as functions or not.
Parameters:	None.
Returns:	Returns true if the value set can store function values, false otherwise.

Example:

if info:canStoreFunctions() then
  ...
end

info:allocMode()
Description:	Returns the allocation mode for the value set.
Parameters:	None.
Returns:	Returns a string with the allocation mode (`"full"`, `"sparse"` or `"auto"`).

Example:

if info:allocMode() == 'sparse' then
  ...
end

info:allocStrategy()
Description:	Returns the allocation strategy used for sparse value sets.
Parameters:	None.
Returns:	Returns a string with the allocation strategy (`"auto"`).

Example:

print(info:allocStrategy())

Other methods

info:history()
Description:	Returns the type of history associated with this value set.
Parameters:	None.
Returns:	Returns false for no history, true for unlimited history and the number of saved states for a rolling history.

Example:

local historyType = info:history()

info:setHistory(mode)
Description:	Updates the history mode for this value set. Must be called only for new value info objects, created with ValueInfo`()`, and before the object is used to create a new value set.
Parameters:	mode - The desired history mode. Should be equal to false for no history, true for unlimited history and the number of desired states for a rolling history.
Returns:	Nothing.

Example:

local newInfo = ValueInfo('node attribute', {id = 'test', description = 'Test attribute', unit = 'kPa'})
newInfo:setHistory(2) -- Set a two states rolling history
mesh:addNodeValueSet(newInfo)

info:ruleSet()
Description:	Returns the integration rule set that this value set is bound to. For attributes attached to Gauss points only.
Parameters:	None.
Returns:	Returns the rule set number or `nil` if the value set kind is not a Gauss attribute.

Example:

local rule = info:ruleSet()

info:setRuleSet(ruleSet)
Description:	Updates the integration rule set for this value set. Valid for Gauss attributes only. Must be called only for new value info objects, created with ValueInfo`()`, and before the object is used to create a new value set.
Parameters:	ruleSet - The integration rule set that this Gauss attribute value set should be tied to. Must be a value between 1 and the number of integration rule sets tied to the mesh that will contain this Gauss attribute.
Returns:	Nothing.

Example:

local newInfo = ValueInfo('gauss attribute', {id = 'test', description = 'Test attribute', unit = 'kPa'})
newInfo:setRuleSet(2) -- Attach this Gauss attribute to rule set 2
mesh:addGaussAttributeSet(newInfo)

info:format()
Description:	Returns the format string used while printing values. The returned string follows the following format: `width.precision[fgeGE]` (`"8.3f"`, for example).
Parameters:	None.
Returns:	Returns the format string.

Example:

print(info:format())

info:setFormat(formatStr)
Description:	Updates the format string used while printing values belonging to this value set.
Parameters:	formatStr - String with the new desired format. Should be a string formated as `"width.precision[fgeGE]"` (`"8.3f"`, for example). Missing width or precision values are interpreted as zero. Missing format type is interpreted as `"f"`.
Returns:	Returns true on success, false if the format string is invalid.

Example:

local ok = info:setFormat('10.5g')

info:constMap()
Description:	Returns the constants map for this value info object.
Parameters:	None.
Returns:	Returns the mapping Lua table or `nil` if none is present.

Example:

-- Prints the constant map table tied to this value info object
local map = info:constMap()
for key, value in pairs(map) do 
  print(key, value)
end

info:print()
Description:	Prints the full set of value info characteristics.
Parameters:	None.
Returns:	Nothing.

Example:

info:print()