Contact boundary condition object methods

Contact boundary condition objects are a Lua wrapper over a GeMA contact boundary condition providing a rich set of methods for querying and updating its properties. Those include querying and updating contact boundary condition property values, as well as their application points. Contact boundary condition objects can be obtained in the orchestration by calling the modelData:contactBoundaryCondition() method.

Since most of the methods of a contact boundary condition object are the same as those from a boundary condition object, this page documents only the different ones. On the index below, shared methods are marked as "inherited from b.c." and their links refer to that documentation.

Example:

local cbc = modelData:contactBoundaryCondition('cbcName')

Index:

• Metadata methods
  • bc:id() - Inherited from b.c.
  • bc:description() - Inherited from b.c.
  • bc:type() - Inherited from b.c.
  • bc:mesh() - Inherited from b.c.
  • bc:bcType() - Inherited from b.c.
  • cbc:isGlobal()
• Property (column) querying and updating methods
  • bc:numProperties() - Inherited from b.c.
  • bc:propertyIds() - Inherited from b.c.
  • bc:propertyInfo() - Inherited from b.c.
  • cbc:propertyAccessor()
  • cbc:numPropertyValues()
  • cbc:contactIndex()
  • cbc:addPropertyLines()
  • cbc:setPropertyMaterialId()
• Value (line) querying methods
  • bc:numValues() - Inherited from b.c.
  • bc:numNodes() - Inherited from b.c.
  • bc:node() - Inherited from b.c.
  • bc:cell() - Inherited from b.c.
  • bc:numBoundaryCells() - Inherited from b.c.
  • bc:boundaryCell() - Inherited from b.c.
  • bc:boundary() - Inherited from b.c.
  • bc:nodeSet() - Inherited from b.c.
• Value (line) updating methods
  • bc:setNode() - Inherited from b.c.
  • bc:setCell() - Inherited from b.c.
  • bc:setBoundary() - Inherited from b.c.
  • bc:reloadNodeBoundaryData() - Inherited from b.c.
  • bc:addLines() - Inherited from b.c.
  • bc:removeLines() - Inherited from b.c.
  • bc:addNodeLine() - Inherited from b.c.
  • bc:addCellLine() - Inherited from b.c.
  • bc:addBoundaryLine() - Inherited from b.c.
• Material querying and updating methods
  • cbc:materialAccessor()
  • cbc:materialList()
  • cbc:setMaterialList()
  • cbc:rebuildMaterialMapping()
• Other methods
  • bc:print() - Inherited from b.c.

Metadata methods

• Inherited Metadata methods

cbc:isGlobal()
Description:	Returns whether this contact condition is global or local.
Parameters:	None.
Returns:	Returns true for global conditions and false for local ones.

Example:

print(cbc:isGlobal())

Property (column) querying and updating methods

• Inherited Property (column) querying methods

cbc:propertyAccessor(name, unit)
Description:	Returns a Contact Bc accessor object that can be used to retrieve and update property values for contact boundary conditions. Unlike other accessor types, a contact boundary condition property accessor always retrieves data from the current state. See also the documentation on contactIndex() for retrieving the appropriate index for querying property values for a given contact pair.
Parameters:	name	The name (id) of the property.
	unit	An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns:	A Contact Bc accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local fAc  = cbc:propertyAccessor('f')         -- An accessor to the 'f' contact b.c. property
local fAc2 = cbc:propertyAccessor('f', 'lbf')  -- An accessor to the 'f' contact b.c. property with values converted to 'lbf'

cbc:numPropertyValues()
Description:	Returns the number of property values (contact material pairs) stored in this contact boundary condition object.
Parameters:	None.
Returns:	Returns the number of property values.

Example:

-- Print the number of property values (contact material pairs) configured for a contact boundary condition
print(cbc:numPropertyValues())

cbc:contactIndex(bcIndex1, bcIndex2)
Description:	Given a pair of contact boundary condition line indices, returns the index in the user property values (contact material pairs) table that contains the properties for the given material pair (implied by the material associated with each application point line) or nil if no such pair exists. The returned index is suitable for being used with the accessor returned by propertAccessor().
Parameters:	bcIndex1	The boundary condition index for the first "in contact" border (between 1 and bc:numValues()).
	bcIndex2	The boundary condition index for the second "in contact" border (between 1 and bc:numValues()).
Returns:	Returns the index for the material pair in the property values table.

Example:

-- Print the value of the scalar property 'f' for the material pair associated with contact surfaces 4 and 5
-- The value is evaluated on the contex of the first node of surface 5 (used only if the value is a function)
local fAc   = cbc:propertyAccessor('f')
local index = cbc:contactIndex(4, 5)

print(fAc:value(index, 5, 1))

cbc:addPropertyLines(nlines)
Description:	Adds the given number of lines to the property values table. The material pair must be filled by calls to cbc:setPropertyMaterialId(). Properties are initialized with their default values and can be updated through accessors returned by cbc:propertyAccessor().
Parameters:	nlines - Optional number of lines (material pairs) to add to the object. If this parameter is missing, only one line will be added.
Returns:	Returns the index of the first newly added line.

Example:

-- Adds a new line and initializes its material pair to "concrete:steel"
local nextIndex = bc:addPropertyLines(1)

cbc:setPropertyMaterialId(nextIndex,  "concrete:steel")

cbc:setPropertyMaterialId(propertyIndex, materialId)
Description:	Updates the property material pair for the given property value line. IMPORTANT: After a property material id change, a call to cbc:rebuildMaterialMapping() must be made before any subsequent calls to cbc:contactIndex().
Parameters:	propertyIndex	The property value index (between 1 and bc:numPropertyValues()).
	materialId	The new material pair. Material pairs are identified by a name formated as "x:y", where both x and y are material names present in the materialList. That means that, for example, the property values tied to the "a:b" entry should be used when a surface with material a is in touch with a surface with material b (or if a surface with material b is in touch with a surface with material a).
Returns:	Returns true on success and false on error (unknown material, for example).

Example:

-- Adds a new line and initializes its material pair to "concrete:steel"
local nextIndex = bc:addPropertyLines(1)

cbc:setPropertyMaterialId(nextIndex,  "concrete:steel")

Material querying and updating methods

cbc:materialAccessor()
Description:	Returns a Value accessor object that can be used to retrieve and update the material associated with each application point (line) for a contact boundary condition. The returned accessor has an associated constant map so, when updating materials, a string can be used instead of the index of the material on the material list.
Parameters:	None.
Returns:	Returns the Value accessor object or nil on errors.

Example:

local matAc = cbc:materialAccessor()

cbc:materialList()
Description:	Returns a table filled with the materials associated with this contact boundary condition.
Parameters:	None.
Returns:	Returns the table filled with material names.

Example:

-- Prints the list of materials associated with a contact condition
local matList = cbc:materialList()

for i, v in ipairs(matList) do 
  print(i, v)
end

cbc:setMaterialList(list)
Description:	Replaces the material list with the contents of the given table. Keep in mind that the new list contents must be compatible with property material ids and with material values tied to application points. IMPORTANT: After a property material id change, a call to cbc:rebuildMaterialMapping() must be made before any subsequent calls to cbc:contactIndex().
Parameters:	list - A Lua table with the new material list.
Returns:	Nothing.

Example:

cbc:setMaterialList({'concrete', 'steel', 'sand'})

-- See also the rebuildMaterialMapping() example

cbc:rebuildMaterialMapping()
Description:	Rebuilds the internal mapping used by cbc:contactIndex(). Must be called after calls to cbc:setMaterialList() and/or cbc:setPropertyMaterialId() and before any subsequent call to cbc:contactIndex().
Parameters:	None.
Returns:	Returns true on success and false on error.

Example:

-- Adds a new material 'shale' to the material list
local matList = cbc:materialList()
matList[#matList+1] = 'shale'
cbc:setMaterialList()

-- Adds a new property value line for a 'concrete - shale' contact, filling the 'f' property with the value 10.0
local fAc   = cbc:propertyAccessor('f')
local index = cbc:addPropertyLines()

cbc:setPropertyMaterialId(index, 'concrete:shale')
fAc:setValue(index, 10.0)

-- Updates the material mapping to enable future calls to contactIndex()
cbc:rebuildMaterialMapping()