Restraint Case

Overview

This class manages degree of freedom constraints in the form of single point constraints (SPCs) defined at nodes or element constraints defined at elements. A single point constraint may consist of a simple fixity, a constraint to a specified value or an equivalence to another node. An element constraint may consist of a simple fixity or a constraint to a specified value. The specified constraint value may be applied to the primary degree of freedom or a time derivative. The constraint value may be a general function of time or frequency. Note that complex valued single point applied constraints may be specified. This is used for example in steady state structural dynamics.

The functions associated with a RestraintCase object are the following:

Complex valued constraints may be specified. The real and imaginary parts of a complex valued constraint may be specified one at a time or together depending upon the state of the complex mode. The user sets the complex mode using setComplexMode().

Define single point constraints at a node using setSPC(). Generate a node group of all nodes at which single point constraints have been defined using getSPCNodeGroup(). Query for the number and type of degrees of freedom at a node which have single point constraints using getSPCDofsAtNode(). Return the single point constraint value and/or equivalencing information at a node using getSPC(). Return the maximum node index for which single point constraints have been defined using getSPCMaxNodeIndex().

Similar functions exist for setting and querying constraints at elements: setConstraintOnElementDof(), getConstraintInfoFromElementDof(), etc. Note that the MASTER option does not exist for element constraints.

Each applied constraint value component may be assigned a separate table identifier using the function setSPCTableIdentifiers(). These tables are represented by TableFunction objects and are normally used to specify time or frequency dependent variation of the individual components of applied constraint.

For dynamics applications the applied constraint may be a time derivative of the primary degree of freedom value. This is done using the function setSPCTimeDerivativeType(). For example, applied velocities and/or accelerations may be specified.

Class Members Descriptions

The currently available RestraintCase enumerations and functions are described in detail in this section.

class RestraintCase

Restraint Case object for managing single point constraints and element constraints.

Public Types

enum class ConstraintType

Single point constraint type.

Values:

enumerator FREE

Free (no constraint)

enumerator FIXED

Simple fixity.

enumerator APPLIED

Constraint to applied value.

enumerator MASTER

Equivalence to another master node.

enum class TimeDerivative

Time derivative type for applied constraint value.

Values:

enumerator ZERO

Degree of freedom.

enumerator FIRST

First time derivative.

enumerator SECOND

Second time derivative.

Public Functions

ErrorCode getErrorCode()

Return the current ErrorCode of the RestraintCase object.

Returns: ErrorCode - The current error code, or NONE if no error.
Status setComplexMode(ComplexMode mode)

Set complex mode. By default the complex mode is REAL . Use getComplexMode() to query the complex mode.

Parameters:mode – ComplexMode
Returns:Status
Status getComplexMode(ComplexMode *mode)

Get complex mode.

Parameters:mode – [out] Complex mode
Returns:Status
Status hasComplexData(int *flag)

Query for complex data existence. The flag will be returned as one if the complex mode set by setComplexMode() is ever IMAGINARY or REAL_IMAGINARY , otherwise it is returned as zero.

Parameters:flag – [out] Complex data existence flag
Returns:Status
Status setSPC(int nodeIndex, DofType dof, ConstraintType type, double value[], int masterNodeIndex)

Set a single point constraint at a degree of freedom, dof at a node nodeIndex. Depending upon the type of single point constraint, the applied value or master node must be supplied. A type of FREE will remove any previously defined single point constraint. Use getSPCDofsAtNode() to return the number and type of single point constraints defined at a node. Use getSPC() to return the applied value and/or master node of a single point constraint. Note that the applied value is an array in case the applied value is a complex number in which real and imaginary values must be supplied.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number, nodeIndex >= 1
  • dof – Degree of freedom type
  • type – ConstraintType
  • value – Applied value
  • masterNodeIndex – Master node
Returns:

Status
Status setSPCTableIdentifiers(int index, DofType dof, int ids[])

Set a single point constraint table identifiers. The applied constraint value must have been previously defined using setSPC() .

Errors
VALUE is generated if an improper index is specified. OPERATION is generated if an applied constraint value has not been previously specified.

Parameters:
  • index – Node number, index >= 1
  • dof – Degree of freedom type
  • ids – Table identifiers
Returns:

Status
Status setSPCTimeDerivativeType(int nodeIndex, DofType dof, TimeDerivative derivativeType)

Set a single point applied constraint value time derivative. The applied constraint value must have been previously defined using setSPC() .

Errors
VALUE is generated if an improper index is specified. OPERATION is generated if an applied constraint value has not been previously specified.

Parameters:
  • index – Node number, index >= 1
  • dof – Degree of freedom type
  • derivativeType – Derivative TimeDerivative
Returns:

Status
Status getSPCcount(int *indexCount, int *appliedCount, int *masterCount)

Return the count of single point constraint indices, applied constraints, and master constraints.

Parameters:
  • indexCount – [out] Number of nodes with single point constraints
  • appliedCount – [out] Number of applied constraint values
  • masterCount – [out] Number of master constraints
Returns:

Status

Status getSPCMaxNodeIndex(int *maxNodeIndex)

Return the maximum node number for which single point constraints have been defined. If no single point constraints have been defined then maxNodeIndex is returned as zero.

Parameters:maxNodeIndex – [out] Maximum node number
Returns:Status
Status initializeSPCIterator()

Initialize iteration through nodes with single point constraints. Use nextSPCItem() to iterate through the nodes.

Returns:Status
Status nextSPCItem(int *index)

Get the next node index with single point constraints in the iteration. Call initializeSPCIterator() before using this function.

Parameters:index – [out] Node number
Returns:Status
Status getSPCUsedDofs(int *dofCount, DofType dofs[])

Return the number, dofCount, and types, dofs, of all the degrees of freedom used at nodes to define single point constraints.

Parameters:
  • dofCount – [out] Number of degrees of freedom types used at nodes
  • dofs – [out] Vector of degree of freedom types
Returns:

Status

Status getSPCDofsAtNode(int nodeIndex, int *dofCount, DofType dofs[])

Return number of degrees of freedom, dofCount, and types, dofs, of all degrees of freedom at node nodeIndex at which single point constraints have been defined.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number, nodeIndex >= 1
  • dofCount – [out] Number of degrees of freedom with single point constraints
  • dofs – [out] Array of degree of freedom types
Returns:

Status
Status getSPC(int nodeIndex, DofType dof, ConstraintType *type, double value[], int *masterNodeIndex)

Query for single point constraint type, applied value and master node for a specified degree of freedom type, dof at a node nodeIndex. If a single point constraint has not been defined for a node nodeIndex and/or dof the type is returned as FREE and value and masterNodeIndex are undefined.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number, nodeIndex >= 1
  • dof – Degree of freedom type
  • type – [out] Single point constraint ConstraintType
  • value – [out] Applied value
  • masterNodeIndex – [out] Master node
Returns:

Status
Status getSPCTableIdentifiers(int nodeIndex, DofType dof, int ids[])

Query for single point constraint applied value table identifiers for a specified degree of freedom type, dof at a node nodeIndex. If a single point applied constraint has not been defined for a node nodeIndex and/or dof, ids entries are returned as 0.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number, nodeIndex >= 1
  • dof – Degree of freedom type
  • ids – [out] Table identifiers
Returns:

Status
Status getSPCTimeDerivativeType(int nodeIndex, DofType dof, TimeDerivative *derivativeType)

Query for single point constraint applied value time derivative for a specified degree of freedom type, dof at a node nodeIndex. If a single point applied constraint has not been defined for a node nodeIndex and/or dof, derivativeType is returned as 0.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number, nodeIndex >= 1
  • dof – Degree of freedom type
  • derivativeType – [out] Derivative TimeDerivative
Returns:

Status
Status getSPCNodeGroup(Group *inputNodeGroup, Group *outputNodeGroup)

Derive a group of nodes from an input group of nodes which have single point constraints defined.

The output outputNodeGroup must have been previously created and defined as a node group. Note that outputNodeGroup is not cleared by this function, the derived node entities are added to any existing nodes in the output outputNodeGroup.

Errors
VALUE is generated if inputNodeGroup is not a node group.

Parameters:
  • inputNodeGroup – Pointer to Group object of nodes. If NULL, then all nodes are assumed.
  • outputNodeGroup – [out] Pointer to derived Group object of nodes.
Returns:

Status
Status setConstraintOnElementDof(int elementIndex, DofType dof, ConstraintType type, double value[])

Set a constraint at a degree of freedom, dof at an element elementIndex. Depending upon the type of constraint, the applied value must be supplied. A type of FREE will remove any previously defined constraint. Use getConstraintDofsFromElement() to return the number and type of constraints defined at an element. Use getConstraintInfoFromElementDof() to return the applied value of a constraint.

Errors
VALUE is generated if an improper elementIndex is specified.

Parameters:
  • elementIndex – Element number, elementIndex >= 1
  • dof – Degree of freedom type
  • type – Constraint ConstraintType
  • value – Applied value
Returns:

Status
Status getElementConstraintMaxIndex(int *maxElementIndex)

Return the maximum element number for which constraints have been defined. If no element constraints have been defined then maxElementIndex is returned as zero.

Parameters:maxElementIndex – [out] Maximum element number
Returns:Status
Status initializeElementConstraintIterator()

Initialize iteration through elements with constraints. Use nextElementConstraintItem() to iterate through the elements.

Returns:Status
Status nextElementConstraintItem(int *elementIndex)

Get the next element index with constraints in the iteration. Call initializeElementConstraintIterator() before using this function.

Parameters:elementIndex – [out] Element number
Returns:Status
Status getUsedConstraintDofsFromElements(int *dofCount, DofType dofs[])

Return the number, dofCount, and types, dofs, of all the degrees of freedom used at elements to define constraints.

Parameters:
  • dofCount – [out] Number of degrees of freedom types used at elements
  • dofs – [out] Vector of degree of freedom types
Returns:

Status

Status getConstraintDofsFromElement(int elementIndex, int *dofCount, DofType dofs[])

Return number of degrees of freedom, dofCount, and types, dofs, of all degrees of freedom at element elementIndex at which constraints have been defined.

Errors
VALUE is generated if an improper elementIndex is specified.

Parameters:
  • elementIndex – Element number, elementIndex >= 1
  • dofCount – [out] Number of degrees of freedom with constraints
  • dofs – [out] Vector of degree of freedom types
Returns:

Status
Status getConstraintInfoFromElementDof(int elementIndex, DofType dof, ConstraintType *type, double *value)

Query for element constraint type and applied value for a specified degree of freedom type, dof at an element elementIndex.

Errors
VALUE is generated if an improper elementIndex is specified.

Parameters:
  • elementIndex – Element number, elementIndex >= 1
  • dof – Degree of freedom type
  • type – [out] Constraint ConstraintType
  • value – [out] Applied value
Returns:

Status
Status getConstraintElementGroup(Group *inputElementGroup, Group *outputElementGroup)

Derive a group of elements from an input group of elements which have element constraints defined.

The output outputElementGroup must have been previously created and defined as a element group. Note that outputElementGroup is not cleared by this function, the derived element entities are added to any existing element in the output outputElementGroup.

Errors
VALUE is generated if inputElementGroup is not an element group.

Parameters:
  • inputElementGroup – Pointer to Group object of elements. If NULL, then all elements are assumed.
  • outputElementGroup – [out] Pointer to derived Group object of elements.
Returns:

Status
Status clear()

Clear all defined constraints.

Returns:Status
Status hasRestraintSpecified(int *flag)

Query if any restraint specifications of any type have been made. The return value, flag, will be zero only if no restraints have been specified of any type.

Parameters:flag – [out] Flag indicating if any restraints set
Returns:Status
Status add(RestraintCase *add)

Add the restraint case add to this RestraintCase. If the restraint case add contains restraints at the same entity and degree of freedom as this object then the restraint definition in add takes precedence.

Errors
OPERATION is generated if add is the same object as this

Parameters:add – Pointer to RestraintCase object to add
Returns:Status
Status setId(int id)

Set the identifier for the RestraintCase object.

Parameters:id – Identifier value
Returns:Status
Status getId(int *id)

Get the identifier of the RestraintCase object.

Parameters:id – [out] Identifier value
Returns:Status
Status setName(const char *name)

Set a name string for the RestraintCase object. The name string can contain up to 81 characters including the terminating NULL. If the name is not specified it is returned as a single NULL character using getName() .

Parameters:name – Name string
Returns:Status
Status getName(char name[])

Get the name of the RestraintCase object.

Parameters:name – [out] Name string buffer
Returns:Status
Status print()

Print information about the RestraintCase object to standard output.

Returns:Status
Status copy(RestraintCase *from)

Copy all restraint data from another RestraintCase object. This function will clear all existing restraints in this object before copying.

Parameters:from – Pointer to RestraintCase object to copy from
Returns:Status