Discontinuity set objects are a Lua wrapper over a GeMA discontinuity set providing a rich set of methods for querying and updating its properties and storing a set of discontinuity objects. Discontinuity set objects can be obtained in the orchestration by calling the modelData:discontinuitySet() method.

Example:

local ds = modelData:discontinuitySet('dsName')

Index:

Metadata methods
- ds:id()
- ds:description()
- ds:type()
- ds:mesh()
- ds:spatialIndex()
- ds:autoAddElements()
- ds:extraDofsInAddedElements()
- ds:snapTolerance()
Discontinuity methods
- ds:numDiscontinuities()
- ds:discontinuityIndex()
- ds:discontinuity()
Attribute methods
- ds:attributeIds()
- ds:attributeInfo()
- ds:attributeAccessor()
- ds:numAttributeStates()
Property methods
- ds:numPropertySets()
- ds:propertySets()
- ds:propertySetIndex()
- ds:propertyInfo()
- ds:propertyAccessor()
Intersection methods
- ds:cellIntersections()
Other methods
- ds:print()

Metadata methods

ds:id()
Description:	Returns the discontinuity set name.
Parameters:	None.
Returns:	Returns a string with the discontinuity set name (the id attribute given during its model definition).

Example:

-- Print the discontinuity set name

print(ds:id())

ds:description()
Description:	Returns the discontinuity set description.
Parameters:	None.
Returns:	Returns a string with the discontinuity set description

Example:

-- Print the discontinuity set description

print(ds:description())

ds:type()
Description:	Returns the discontinuity set geometry type as a string. Available types are `"polyline"`, `"tri. surface"`, `"edge list"` and `"face list"`.
Parameters:	None.
Returns:	Returns a string with the discontinuity set geometry type.

Example:

-- Print the discontinuity set geometry type

print(ds:type())

ds:mesh()
Description:	Returns the cell mesh object owning the cells that are "cut" by the given discontinuities.
Parameters:	None.
Returns:	Returns the associated cell mesh object.

Example:

local mesh = ds:mesh()

ds:spatialIndex()
Description:	Returns the optional spatial index object used by the discontinuity set object to accelerate intersection operations.
Parameters:	None.
Returns:	Returns the associated spatial index object or `nil` if there is none.

Example:

local si = ds:spatialIndex()

ds:autoAddElements()
Description:	Returns `true` if the intersection between the discontinuity set discontinuities and the support mesh should be added to the mesh as new elements. The added elements type depend on the discontinuity geometric type. Polyline geometries are added as bars, edge lists are added as interface elments, triangle surfaces are added either as 3d triangles or quads and face lists are added as 3d interface elements.
Parameters:	None.
Returns:	Returns a boolean defining if the discontinuity is automatically added to the mesh as new elements.

Example:

local autoAdd = ds:autoAddElements()

ds:extraDofsInAddedElements()
Description:	Returns `true` if added interface elements should have extra dof nodes in its middle plane. This option only has effect if elements are added automatically to the mesh and the geometric discontinuity type is either edge list or face list.
Parameters:	None.
Returns:	Returns a boolean defining if added interface elemenst should have extra dof nodes or not.

Example:

local extraDofs = ds:extraDofsInAddedElements()

ds:snapTolerance()
Description:	Returns the percentual tolerance used to snap discontinuity-cell intersection points to cell nodes, edges or faces. See comments on the `snapTol` option field at the discontinuity set object documentation for an in-depth explanation of the tolerance role.
Parameters:	None.
Returns:	Returns the defined tolerance.

Example:

local tol = ds:snapTolerance()

Discontinuity methods

ds:numDiscontinuities()
Description:	Returns the number of discontinuities in this discontinuity set.
Parameters:	None.
Returns:	Returns the number of discontinuities.

Example:

local ndisc = ds:numDiscontinuities()

ds:discontinuityIndex(name)
Description:	Returns the index in the discontinuity set of the named discontinuity or `nil` if not found.
Parameters:	name - The discontinuity name (id).
Returns:	Returns the index of the given discontinuity in the set or `nil` if not found.

Example:

local index = ds:discontinuityIndex('discName') -- Returns the index in ds of the discontinuity named 'discName'

ds:discontinuity(index)
Description:	Returns the discontinuity object stored at the given index.
Parameters:	index - The discontinuity index, a value between 1 and `ds:`numDiscontinuities`()`.
Returns:	Returns the discontinuity object.

Example:

local d = ds:discontinuity(1) -- Returns the first discontinuity object in the set

Attribute methods

ds:attributeIds()
Description:	Returns a list with the name (id) of every attribute associated with the discontinuity set.
Parameters:	None.
Returns:	Returns a table with attribute ids (strings).

Example:

local attrIds = ds:attributeIds()

ds:attributeInfo(name)
Description:	Returns an object with metadata information about the named discontinuity set attribute.
Parameters:	name - The attribute name (id).
Returns:	Returns a value info object or `nil` if the requested name was not found in the discontinuity set.

Example:

local rhoInfo = ds:attributeInfo('rho')

ds:attributeAccessor(name, unit) ds:attributeAccessor(name, state, locked, unit)
Description:	Returns a Discontinuity accessor object that can be used to retrieve and update data for discontinuity attributes. Can be called with two different signatures. The first, receiving only the attribute name and an optional unit, always retrieves data from the current state and is the most used. The second, allows for defining the desired state from which data will be recovered / written. As a matter of fact, the first format is equivalent to calling the second one as `ds:attributeAccessor(name, 0, true, unit)`.
Parameters:	name	The name (id) of the discontinuity set attribute.
	state	An optional state number referencing the history state that the accessor will operate on. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested variable, which can be queried with a call to `ds:`numAttributeStates`()`. Remember that for a discontinuity accessor to support states, the history parameter must be set on its value info object.
	locked	The locked parameter controls the behaviour of the accessor once a new state is created for the value. The 'lock' refers to the state number, so if locked is false and a new state is created, the accessor doesn't change and continues to point to the same data. If locked is true, the accessor will be locked to that state number, so when a new state is created, the accessor changes the data its looking upon to reflect the new state. For example, an accessor locked on state 0 will always point to the current state, and one locked to state 1 will always point to the previous saved value.
	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 Discontinuity 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 rhoAc  = ds:attributeAccessor('rho')          -- Get an accessor to the 'rho' discontinuity set attribute
local rhoAc2 = ds:attributeAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' discontinuity set attribute with values converted to g/cm3
local rhoAc3 = ds:attributeAccessor('rho', 1, true) -- Get an accessor locked on the previous saved value of attribute 'rho'

ds:numAttributeStates(name)
Description:	Returns the number of existing history states for the given discontinuity attribute.
Parameters:	name - The name (id) of the discontinuity attribute.
Returns:	Returns the number of existing states or -1 for unknown names.

Example:

local nstates = ds:numAttributeStates('rho')

Property methods

ds:numPropertySets()
Description:	Returns the number of property sets attached to this discontinuity set.
Parameters:	None.
Returns:	Returns the number of property sets.

Example:

local npsets = ds:numPropertySets()

ds:propertySets()
Description:	Returns a list with the property set objects attached to this discontinuity set.
Parameters:	None.
Returns:	Returns a list of property set objects.

Example:

-- Prints the name of the property sets attached to this discontinuity set
local psets = ds:propertySets()
for i = 1, #psets do
  print(psets[i]:id())
end

ds:propertySetIndex(name)
Description:	Returns the index of the associated property set that includes the given property name.
Parameters:	name - The property name.
Returns:	Returns the index inside the list returned by `ds:`propertySets`()` of the property set object that contains 'name' among its properties. Returns `nil` for unknown names.

Example:

local psetIndex = ds:propertySetIndex('rho')

ds:propertyInfo(name)
Description:	Returns an object with metadata information about the named discontinuity property.
Parameters:	name - The property name (id).
Returns:	Returns a value info object or `nil` if the requested name was not found in the discontinuity set.

Example:

local rhoInfo = ds:propertyInfo('rho')

ds:propertyAccessor(name, unit)
Description:	Returns a Discontinuity accessor object that can be used to retrieve data for discontinuity properties. Unlike other accessor types, a property accessor always retrieves data from the current state.
Parameters:	name	The name (id) of the discontinuity property.
Parameters:	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 Discontinuity 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 rhoAc = ds:propertyAccessor('rho') -- Get an accessor to the 'rho' property

local rhoAc2 = ds:propertyAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' property with values converted to g/cm3

Intersection methods

ds:cellIntersections(cellId)
Description:	Returns intersection data for the intersections that where found between the given cell and the discontinuies from this set. Returns `nil` if there are none. The returned data is a table with one sub-table for each cell-discontinuity intersection. The fields in an intersection table depend on the discontinuity set type.
Parameters:	cellId - The cell id number (an index between 1 and `mesh:`numCells`()`) for the queried cell.
Returns:	Returns the discontinuity-cell intersection data or `nil` if there is none. For polyline-cell intersections, the following fields are present in each data sub-table: - `cellId`; - `discontinuityIndex`: The index of the discontinuity in the discontinuity set; - `segmentIndex`: The polyline segment index inside the discontiinuity; - `edge`: Set to the cell edge index if the intersection lies over an edge. Not present if the intersection just crosses an edge or a node. See the Element types page for the edge organization for each cell type; - `intersectionElement`: The id for the added intersection element when `autoAddElements` is enabled for this discontinuity set. Not presente otherwise; - `in`: A table storing coordinates and metadata for the first, or incoming, intersection between the segment and the cell. Its fields are: `kind`, a string specifying if the intersection was on an edge, a node or internal to the cell, `border`, an integer filled with the edge or node index for those kinds of intersection and absent for internal ones, `cartCoord`, a vector object filled with cartesian coordinates for the intersection and `natCoord`, a vector object filled with the intersection natural coordinates; - `out`: Similar to `in` but storing the data for the second, or outgoing, intersection between the segment and the cell.

Example:

-- Get intersection for the third cell
local d = ds:cellIntersections(3) 
if not d then
  print('No intersections')
else
  -- Print the index of the bar element that represents each intersection
  -- and also the cartesian coordinates of each intersection endpoint
  if ds:type() == 'polyline' then
    for i, v in ipairs(d) do
      print(v.intersectionElement)
      v.in.cartCoord:t():print()  -- Vector is transposed before printing for a better layout
      v.out.cartCoord:t():print() 
    end
  end
end

Other methods

ds:print()
Description:	Print discontinuity set parameters together with attribute values and geometry definition for each discontinuity in the set.
Parameters:	None.
Returns:	Nothing.

Example:

ds:print()