Load Case

Overview

This class manages concentrated nodal loads such as forces and moments and element distributed loads such as pressures, tractions, etc. It also manages nodal parameters such as temperature which may be used for thermal loading or temperature dependent material properties. Distributed loads over an element face or edge may vary over the face or edge nodes. Body forces over an element may vary over each element node. In addition, overall accelerations due to gravity or rotational effects may be stored and queried. The load values may be a general function of time or frequency. Note that complex valued concentrated node loads, distributed loads and element body loads may be specified. This is used for example in steady state structural dynamics.

The functions associated with a LoadCase object are the following:

Complex valued concentrated, distributed and element body loads may be specified. The real and imaginary parts of a complex valued load 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().

Set concentrated loads at a node using setConcentratedLoad() or add a load using addConcentratedLoad(). Generate a node group of all nodes at which concentrated loads have been defined using getConcentratedLoadNodeGroup(). Query for the number and type of concentrated loads at a node using getConcentratedLoadType(). The function hasConcentratedLoad() may be used to test for concentrated loads set at a node. Return the concentrated load value at a node using getConcentratedLoad(). Return the maximum node index for which concentrated loads have been defined using getConcentratedLoadMaxNodeIndex().

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

The force and moment vectors are assumed to be in the global coordinate system. Set distributed loads on element faces or edges using setDistributedLoad() or add distributed loads using addDistributedLoad(). At this point a MeshInterface object must be set using setMeshInterface() so that the LoadCase object can access finite element model information. Generate an edge or face group of all element edges or faces at which distributed loads have been defined using getDistributedLoadEdgeGroup() and getDistributedLoadFaceGroup(). Query for the number and type of distributed loads at an element edge or face using getDistributedLoadType(). The function hasDistributedLoad() may be used to test for distributed loads set at an element. Return the distributed load values at an element edge or face using getDistributedLoad(). Return the maximum element index for which distributed loads have been defined using getDistributedLoadMaxElementIndex(). Each distributed load on an element face or edge may be assigned a separate table identifier using the function setDistributedLoadTableIdentifier().

Define element body loads on element nodes using setElementLoad() or add element body loads using addElementLoad(). At this point a MeshInterface object must be set using setMeshInterface() so that the LoadCase object can access finite element model information. Generate an element group of all elements at which element loads have been defined using getElementLoadElementGroup(). Query for the number and type of element loads using getElementLoadTypes(). The function hasElementLoad() may be used to test for element loads set on an element. Return the element load values using getElementLoad(). Return the maximum element index for which element loads have been defined using getElementLoadMaxIndex(). Each element load may be assigned a separate table identifier using the function setElemTableIdentifier().

Define accelerations due to gravity, spin, etc. using setAccelerations(). Query for the definition of accelerations using hasAccelerations(). Return accelerations using getAccelerations().

Class Members Descriptions

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

class LoadCase

Load Case object for managing concentrated nodal loads, distributed element loads, element loads and overall accelerations.

Public Types

enum class ConcentratedLoadType

Concentrated load type.

Values:

enumerator FORCE

Vector of applied force.

enumerator MOMENT

Vector of applied moment.

enumerator HEAT

Scalar applied heat.

enumerator TEMP

Scalar temperature.

enumerator SCALAR

Generic scalar.

enumerator VECTOR

Generic vector.

enum class DistributedLoadType

Distributed load type.

Values:

enumerator TRACTION

Traction load.

enumerator PRESSURE

Pressure load.

enumerator TANGENTIALFORCE

Tangential force.

enumerator TANGENTIALMOMENT

Tangential moment.

enumerator HEATFLUX

Heat flux.

enumerator HEATCONVECTION

Heat convection.

enumerator HEATRADIATION

Heat radiation.

enumerator MOMENT

Distributed moment.

enumerator SCALAR

Generic scalar.

enumerator VECTOR

Generic vector.

enum class ElementLoadType

Element load type.

Values:

enumerator BODYFORCE

Body force/acceleration load.

enumerator HEATGENERATION

Volumetric heat generation load.

Public Functions

ErrorCode getErrorCode()

Return the current ErrorCode of the LoadCase object.

Returns: ErrorCode - The current error code, or NONE if no error.
Status setMeshInterface(MeshInterface *functions)

Associate a MeshInterface object with the LoadCase. The MeshInterface attribute object is required before any definition or query of element distributed loads.

Parameters:functions – Pointer to MeshInterface object
Returns:Status
Status getMeshInterface(MeshInterfacePtr &functions)

Get the associated MeshInterface object.

Parameters:functions – [out] Pointer to MeshInterface object
Returns:Status
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 setConcentratedLoad(int nodeIndex, ConcentratedLoadType type, double values[])

Set a single concentrated load at node nodeIndex, replacing any previously existing concentrated load at node nodeIndex. Use getConcentratedLoadType() to return the number and type of loads defined at a node. Use getConcentratedLoad() to return the applied values of a given type of concentrated load at a node.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
Returns:

Status
Status setConcentratedLoadTableIdentifier(int nodeIndex, ConcentratedLoadType type, int id[])

Set table identifiers for concentrated load components at node nodeIndex. The concentrated load must have been previously defined using setConcentratedLoad() . A table identifier is set for each component of the concentrated load.

Errors
VALUE is generated if an improper nodeIndex is specified. OPERATION is generated if the load has not been previously specified.

Parameters:
  • nodeIndex – Node number
  • type – Concentrated load ConcentratedLoadType
  • id – Table identifiers
Returns:

Status
Status getConcentratedLoadTableIdentifiersCount(ConcentratedLoadType type, int *count)

Return the number of table identifiers assigned to concentrated loads of a given type.

Parameters:
Returns:

Status

Status addConcentratedLoad(int nodeIndex, ConcentratedLoadType type, double values[])

Add a single concentrated load to node nodeIndex. Use setConcentratedLoad() to set a concentrated load.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
Returns:

Status
Status getConcentratedLoadMaxNodeIndex(ConcentratedLoadType type, int *maxNodeIndex)

Return the maximum node number for which concentrated loads of a given type have been defined. If no concentrated loads of the given type have been defined then maxNodeIndex is returned as zero.

Parameters:
Returns:

Status

Status initializeConcentratedLoadIterator(ConcentratedLoadType type)

Initialize iteration through nodes with concentrated loads of a given type. Use nextConcentratedLoadItem() to iterate through the nodes.

Parameters:type – Concentrated load ConcentratedLoadType
Returns:Status
Status nextConcentratedLoadItem(ConcentratedLoadType type, int *nodeIndex)

Get the next node index with concentrated loads of a given type in the iteration. Call initializeConcentratedLoadIterator() before using this function.

Parameters:
Returns:

Status

Status hasConcentratedLoad(int nodeIndex, ConcentratedLoadType type, int *flag)

Query if a concentrated load of a given type exists at a node.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number
  • type – Concentrated load ConcentratedLoadType
  • flag – [out] Flag indicating if load exists (1=yes, 0=no)
Returns:

Status
Status getConcentratedLoadType(int nodeIndex, int *typeCount, ConcentratedLoadType types[])

Return number and types of all concentrated loads defined at node nodeIndex.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number
  • typeCount – [out] Number of concentrated load types
  • types – [out] Array of concentrated load ConcentratedLoadType
Returns:

Status
Status getConcentratedLoad(int nodeIndex, ConcentratedLoadType type, double values[])

Query for concentrated load values of a given type at a node nodeIndex.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number
  • type – Concentrated load ConcentratedLoadType
  • values – [out] Load values
Returns:

Status
Status getConcentratedLoadTableIdentifier(int nodeIndex, ConcentratedLoadType type, int id[])

Query for concentrated load table identifiers of a given type at a node nodeIndex.

Errors
VALUE is generated if an improper nodeIndex is specified.

Parameters:
  • nodeIndex – Node number
  • type – Concentrated load ConcentratedLoadType
  • id – [out] Table identifiers
Returns:

Status
Status setDistributedLoad(EntityType entityType, int elementIndex, int entityNumber, DistributedLoadType type, double values[])

Set a distributed load on an element entity (face or edge) of element index. Traction, tangent force and moment, and heat flux, heat radiation and heat convection may be specified on element edges. Distributed loads applied to edges are per unit length for 3D elements and per unit area for 2D elements (such as 2D axisymmetric solid elements). Traction, pressure and heat flux, heat radiation and heat convection may be specified on element faces. Distributed loads applied to faces are per unit area. Use getDistributedLoadType() to return the number and type of loads defined on an element entity. Use getDistributedLoad() to return the applied values of a distributed load.

Errors
VALUE is generated if improper elementIndex or entityNumber is specified. NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • type – Distributed load DistributedLoadType
  • values – Load values
Returns:

Status
Status setDistributedLoadTableIdentifier(EntityType entityType, int elementIndex, int entityNumber, DistributedLoadType type, int id[])

Set a distributed load table identifiers at an edge or face, no, of element index. A distributed load value must have been previously set using setDistributedLoad() .

Errors
VALUE is generated if improper elementIndex or entityNumber is specified. NULLOBJECT is generated if a MeshInterface object is not set. OPERATION is generated if the load has not been previously specified.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • type – Distributed load DistributedLoadType
  • id – Table identifiers
Returns:

Status
Status addDistributedLoad(EntityType entityType, int elementIndex, int entityNumber, DistributedLoadType type, double values[])

Add a distributed load to an element entity. Traction, tangent force and moment, and heat flux, heat convection and heat radiation may be specified on element edges. See Also setDistributedLoad() .

Errors
VALUE is generated if improper elementIndex or entityNumber is specified. NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • type – Distributed load DistributedLoadType
  • values – Load values
Returns:

Status
Status getDistributedLoadMaxElementIndex(EntityType entityType, DistributedLoadType type, int *maxElementIndex)

Return the maximum element number for which distributed loads of a given type have been defined on a given entity type. If no distributed loads have been defined then maxElementIndex is returned as zero.

Parameters:
Returns:

Status

Status initializeDistributedLoadIterator(EntityType entityType, DistributedLoadType type)

Initialize iteration through elements with distributed loads of a given type and entity type.

Parameters:
Returns:

Status

Status nextDistributedLoadItem(EntityType entityType, DistributedLoadType type, int *elementIndex)

Get the next element index with distributed loads in the iteration.

Parameters:
Returns:

Status

Status hasDistributedLoad(EntityType entityType, int elementIndex, DistributedLoadType type, int *flags)

Query if a distributed load of a given type exists on an element. Get bit flags, encoded in flag, for element index indicating which element entities have had distributed loads of type set. The flags for element faces are returned encoded in the low order 6 bits. The flags for element edges are returned encoded in the low order 12 bits.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • type – Distributed load DistributedLoadType
  • flags – [out] Bit flags indicating which entities have loads
Returns:

Status

int hasDistributedLoadOnEntity(EntityType entityType, int elementIndex, DistributedLoadType type, int entityNumber)

Query if a distributed load exists on a specific entity of an element.

Parameters:
Returns:

int - 1 if load exists, 0 otherwise

Status getDistributedLoadType(EntityType entityType, int elementIndex, int entityNumber, int *typeCount, DistributedLoadType types[])

Return number and types of all distributed loads defined on an element entity.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • typeCount – [out] Number of distributed load types
  • types – [out] Array of distributed load DistributedLoadType
Returns:

Status

Status getDistributedLoad(EntityType entityType, int elementIndex, int entityNumber, DistributedLoadType type, int elementNodeflag, double values[])

Query for distributed load values on an element entity. Query for distributed load values for a specified load type at an edge or face, no, of element index. If the element node flag, enflag, is set then the distributed load values will be returned at element nodes rather than element edge or face nodes.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • type – Distributed load DistributedLoadType
  • elementNodeflag – Flag indicating how values are stored
  • values – [out] Load values
Returns:

Status
Status getDistributedLoadTableIdentifier(EntityType entityType, int elementIndex, int entityNumber, DistributedLoadType type, int id[])

Query for distributed load table identifiers on an element entity.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • entityType – Entity EntityType
  • elementIndex – Element number
  • entityNumber – Face or edge number on the element
  • type – Distributed load DistributedLoadType
  • id – [out] Table identifiers
Returns:

Status
Status setElementLoad(int elementIndex, ElementLoadType type, double values[])

Set an element load at element elementIndex. Set an element load on element index. Accelerations and volumetric heat generation may be specified on element nodes. Use getElementLoadTypes() to return the number and type of loads defined at an element. Use getElementLoad() to return the applied values of a given type of load at an element.

Errors
VALUE is generated if an improper elementIndex is specified. NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • values – Load values
Returns:

Status
Status setElemTableIdentifier(int elementIndex, ElementLoadType type, int id[])

Set table identifiers for element load components. Set an element load table identifier on element index. An element load value must have been previously set using setElementLoad() .

Errors
VALUE is generated if improper elementIndex or entityNumber is specified. NULLOBJECT is generated if a MeshInterface object is not set. OPERATION is generated if the load has not been previously specified.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • id – Table identifiers
Returns:

Status
Status addElementLoad(int elementIndex, ElementLoadType type, double values[])

Add an element load to element elementIndex. If a load of the same type already exists, the new load values are added to the existing values.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • values – Load values
Returns:

Status

Status getElementLoadMaxIndex(ElementLoadType type, int *maxElementIndex)

Return the maximum element number for which element loads of a given type have been defined. If no element loads have been defined then maxElementIndex is returned as zero.

Parameters:
  • type – Element load ElementLoadType
  • maxElementIndex – [out] Maximum element number
Returns:

Status

Status initializeElementLoadIterator(ElementLoadType type)

Initialize iteration through elements with element loads of a given type.

Parameters:type – Element load ElementLoadType
Returns:Status
Status nextElementLoadItem(ElementLoadType type, int *elementIndex)

Get the next element index with element loads in the iteration.

Parameters:
  • type – Element load ElementLoadType
  • elementIndex – [out] Element number
Returns:

Status

Status hasElementLoad(int elementIndex, ElementLoadType type, int *flag)

Query if an element load of a given type exists at an element. Query for an element load having been set for a specified load type at an element index. If an element load has been defined at the element then flag is set to 1 otherwise it is set to 0.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • flag – [out] Flag indicating if load exists (1=yes, 0=no)
Returns:

Status
Status getElementLoadTypes(int elementIndex, int *typeCount, ElementLoadType types[])

Return number and types of all element loads defined at element elementIndex. Return number of element load types, typeCount, and types of all defined element load types on element index.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • elementIndex – Element number
  • typeCount – [out] Number of element load types
  • types – [out] Array of element load ElementLoadType
Returns:

Status
Status getElementLoad(int elementIndex, ElementLoadType type, double values[])

Query for applied values for a specified load type on element index.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • values – [out] Load values
Returns:

Status
Status getElementLoadTableIdentifier(int elementIndex, ElementLoadType type, int id[])

Query for element load table identifiers for a specified load type on element index.

Errors
NULLOBJECT is generated if a MeshInterface object is not set.

Parameters:
  • elementIndex – Element number
  • type – Element load ElementLoadType
  • id – [out] Table identifiers
Returns:

Status
Status setAccelerations(double gravity[3], double centerOfRotation[3], double angularVelocity[3], double angularAcceleration[3])

Set overall accelerations including gravity, rotation center, angular velocity and angular acceleration. Translational accelerations are input as a “gravity” field defined as a vector, grav. Accelerations due to rotations are input as an angular velocity vector (radians/second), w, and acceleration vector (radians/second \(^2\)), wdot, passing through a point, cent. Use hasAccelerations() to query whether accelerations have been defined and query for the defined accelerations using getAccelerations()

Parameters:
  • gravity – Gravity vector [3]
  • centerOfRotation – Center of rotation [3]
  • angularVelocity – Angular velocity vector [3]
  • angularAcceleration – Angular acceleration vector [3]
Returns:

Status

Status hasAccelerations(int *flag)

Query if overall accelerations have been specified. See Also setAccelerations() and getAccelerations() .

Parameters:flag – [out] Flag indicating if accelerations are set (1=yes, 0=no)
Returns:Status
Status getAccelerations(double gravity[3], double centerOfRotation[3], double angularVelocity[3], double angularAcceleration[3])

Get overall accelerations including gravity, rotation center, angular velocity and angular acceleration.

Parameters:
  • gravity – [out] Gravity vector [3]
  • centerOfRotation – [out] Center of rotation [3]
  • angularVelocity – [out] Angular velocity vector [3]
  • angularAcceleration – [out] Angular acceleration vector [3]
Returns:

Status

Status getConcentratedLoadNodeGroup(Group *inputNodeGroup, Group *outputNodeGroup)

Derive a group of nodes from an input group with concentrated loads 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 group 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 getElementLoadElementGroup(Group *inputElementGroup, Group *outputElementGroup)

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

Errors
VALUE is generated if group is not an element edge 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 getDistributedLoadFaceGroup(Group *inputFaceGroup, Group *outputFaceGroup)

Derive a group of faces from an input group with distributed loads defined. The output outputFaceGroup must have been previously created and defined as a face group. Note that outputFaceGroup is not cleared by this function, the derived face entities are added to any existing faces in the output outputFaceGroup.

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

Parameters:
  • inputFaceGroup – Pointer to Group object of faces. If NULL, then all faces are assumed.
  • outputFaceGroup – [out] Pointer to derived Group object of faces.
Returns:

Status
Status getDistributedLoadEdgeGroup(Group *inputEdgeGroup, Group *outputEdgeGroup)

Derive a group of edges from an input group with distributed loads defined. The output outputEdgeGroup must have been previously created and defined as an edge group. Note that outputEdgeGroup is not cleared by this function, the derived edge entities are added to any existing edges in the output outputEdgeGroup.

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

Parameters:
  • inputEdgeGroup – Pointer to Group object of edges. If NULL, then all edges are assumed.
  • outputEdgeGroup – [out] Pointer to derived Group object of edges.
Returns:

Status
Status clearConcentratedLoad(ConcentratedLoadType type)

Clear all concentrated loads if type is zero. Clear the specified type otherwise.

Parameters:type – Concentrated load type
Returns:Status
Status clearDistributedLoad(DistributedLoadType type)

Clear all distributed loads if type is zero. Clear the specified type otherwise.

Parameters:type – Distributed load type
Returns:Status
Status clearElementLoad(ElementLoadType type)

Clear all element loads if type is zero. Clear the specified type otherwise.

Parameters:type – Element load type
Returns:Status
Status clearAccelerations()

Clear all defined accelerations.

Returns:Status
Status clear()

Clear all defined loads and accelerations.

Returns:Status
Status hasLoadcaseSpecified(int *flag)

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

Parameters:flag – [out] Flag indicating if any loads are set
Returns:Status
Status add(LoadCase *add)

Add the load case add to this LoadCase. If the load case add contains loads at the same entity and load type as this object then the load values in add are added to the existing values.

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

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

Set user defined integer identifier.

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

Return user defined integer identifier.

Parameters:id – [out] User defined identifier
Returns:Status
Status setName(const char *name)

Set user defined name. The name string can contain up to 81 characters including the terminating NULL.

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

Return user defined name. If the name is not specified it is returned as a single NULL character.

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

Print a textual summary of load case content to standard output.

Returns:Status