Type definitions

This section defines a couple of structures (C++: enum aka enumeration type), which are used to select, e.g., a configuration type or a variable type. In the background, these types are integer numbers, but for safety, the types should be used as type variables. See this examples:

#Conversion to integer is possible:
x = int(exu.OutputVariableType.Displacement)
#also conversion from integer:
varType = exu.OutputVariableType(8)
#use in settings:
SC.visualizationSettings.contour.outputVariable = exu.OutputVariableType.StressLocal
#use outputVariableType in sensor:
sensor = mbs.AddSensor(SensorBody(bodyNumber=rigid, storeInternal=True,
                                  outputVariableType=exu.OutputVariableType.Displacement))

python/Notebooks/reference/generalInformation.ipynb

OutputVariableType

The enumeration type OutputVariableType is used for selecting output values, e.g., for GetObjectOutput(…) or for selecting variables for contour plot.

Available output variables and the interpreation of the output variable can be found at the object definitions. The OutputVariableType does not provide information about the size of the output variable, which can be either scalar or a list (vector). For vector output quantities, the contour plot option offers an additional parameter for selection of the component of the OutputVariableType. The components are usually out of {0,1,2}, representing {x,y,z} components (e.g., of displacements, velocities, …), or {0,1,2,3,4,5} representing {xx,yy,zz,yz,xz,xy} components (e.g., of strain or stress). In order to compute a norm, chose component=-1, which will result in the quadratic norm for other vectors and to a norm specified for stresses (if no norm is defined for an outputVariable, it does not compute anything)

The class OutputVariableType has the following functions and structures:

  • _None: no value; used, e.g., to select no output variable in contour plot

  • Distance: e.g., measure distance in spring damper connector

  • Position: measure 3D position, e.g., of node or body

  • Displacement: measure displacement; usually difference between current position and reference position

  • DisplacementLocal: measure local displacement, e.g., in local joint coordinates

  • Velocity: measure (translational) velocity of node or object

  • VelocityLocal: measure local (translational) velocity, e.g., in local body or joint coordinates

  • Acceleration: measure (translational) acceleration of node or object

  • AccelerationLocal: measure (translational) acceleration of node or object in local coordinates

  • RotationMatrix: measure rotation matrix of rigid body node or object

  • Rotation: measure, e.g., scalar rotation of 2D body, Euler angles of a 3D object or rotation within a joint

  • AngularVelocity: measure angular velocity of node or object

  • AngularVelocityLocal: measure local (body-fixed) angular velocity of node or object

  • AngularAcceleration: measure angular acceleration of node or object

  • AngularAccelerationLocal: measure angular acceleration of node or object in local coordinates

  • CoordinatesTotal: measure the total coordinates (including reference configuration) of a node or object; otherwise the same as Coordinates

  • Coordinates: measure the coordinates of a node or object; coordinates just contain displacements, but not the reference (position or rotation) values - see also definition of respective nodes or objects

  • Coordinates_t: measure the time derivative of coordinates (= velocity coordinates) of a node or object

  • Coordinates_tt: measure the second time derivative of coordinates (= acceleration coordinates) of a node or object

  • SlidingCoordinate: measure sliding coordinate in sliding joint

  • Director1: measure a director (e.g., of a rigid body frame), or a slope vector in local 1 or x-direction

  • Director2: measure a director (e.g., of a rigid body frame), or a slope vector in local 2 or y-direction

  • Director3: measure a director (e.g., of a rigid body frame), or a slope vector in local 3 or z-direction

  • Force: measure global force, e.g., in joint or beam (resultant force), or generalized forces; see description of according object

  • ForceLocal: measure local force, e.g., in joint or beam (resultant force)

  • Torque: measure torque, e.g., in joint or beam (resultant couple/moment)

  • TorqueLocal: measure local torque, e.g., in joint or beam (resultant couple/moment)

  • StrainLocal: measure local strain, e.g., axial strain in cross section frame of beam or Green-Lagrange strain

  • StressLocal: measure local stress, e.g., axial stress in cross section frame of beam or Second Piola-Kirchoff stress; choosing component==-1 will result in the computation of the Mises stress

  • CurvatureLocal: measure local curvature; may be scalar or vectorial: twist and curvature of beam in cross section frame

  • ConstraintEquation: evaluates constraint equation (=current deviation or drift of constraint equation)

  • KineticEnergy: measure kinetic energy of a body, position independent

  • PotentialEnergy: measure potential (=elastic) energy of a body or connector, position independent

  • HomogeneousTransformation: measure the homogeneous transformation of a node, body point or marker: its rotation matrix A and position p as the 4x4 matrix [A p; 0 1]; the Get…Output functions return it as exu.HT, a sensor stores its 16 components row by row; every item with Position and RotationMatrix provides it

  • HomogeneousTransformationLocal: measure the homogeneous transformation of a frame relative to another, e.g., of joint frame J1 in joint frame J0: the 4x4 matrix [A p; 0 1] with the relative rotation matrix A and the relative position p in the first frame; returned and stored as HomogeneousTransformation

InspectType

The enumeration type InspectType selects what mbs.Inspect(itemIndex, what) reports about an item; each answer is a list of the enumeration types Exudyn exports, the flags of C++ split into their single members.

The class InspectType has the following functions and structures:

  • OutputVariables: the output variables of an object, node or marker (OutputVariableType), with its current parameters: the energies only where they can be computed

  • ObjectType: the type flags of an object (ObjectType): Body, Connector, Constraint, SuperElement, …

  • NodeType: the types a node provides (NodeType): Position, Orientation, RotationEulerParameters, …

  • RequestedNodeTypes: for each node of an object, the node types it requests (NodeType), all of them; for the node of a node marker, a list of requirements, each a list of alternatives of which the node provides one - [[NodeType.Position, NodeType.Position2D]] for MarkerNodePosition

  • MarkerType: the types a marker provides (MarkerType)

  • RequestedMarkerTypes: for each marker of a connector, constraint or load, the marker types it requests (MarkerType)

  • AccessFunctions: the access functions a body offers (AccessFunctionType), which decide the body markers it takes

ComputeItemType

The enumeration type ComputeItemType selects what mbs.ComputeItem(itemIndex, what, …) computes for an item at the current state of the system; matrices and vectors refer to the coordinates of the item (its local-to-global ODE2 coordinates, mbs.systemData.GetObjectLTGODE2, or the coordinates of the node).

The class ComputeItemType has the following functions and structures:

  • PositionJacobian: the position Jacobian, d(velocity)/d(q_t): of a body at localPosition, of a node, of a marker

  • RotationJacobian: the rotation Jacobian, d(angular velocity)/d(q_t), global: of a body at localPosition, of a node, of a rigid marker

  • JacobianTTimesVectorDerivative: the derivative of the transposed Jacobian times a vector by the coordinates: of a body at localPosition and of a marker, d(J_pos^T f + J_rot^T tau)/dq with vector = [f, tau] (6 values); of a node, d(J_rot^T tau)/dq with vector = tau (3 values); an empty matrix where it is zero

  • MassWeightedPositionJacobian: the integral of the density times the position Jacobian over a body, as the mass-proportional load uses it

  • ODE2LHS: the left-hand side of the second order equations of an object - a body, or the forces of a connector projected on its markers -, with the sign of ComputeODE2LHS

  • MassMatrix: the mass matrix of a body

  • AlgebraicEquations: the algebraic equations of a constraint, or of a body with algebraic equations

  • ConstraintJacobian: the Jacobian of the algebraic equations by the ODE2 coordinates (by the velocities for a constraint at velocity level)

  • ReactionForces: the reaction forces C_q^T lambda of a constraint, with the current Lagrange multipliers

  • Kinematics: the marker data of a marker, without Jacobians, as a dict: position, velocity, rotationMatrix and angularVelocityLocal where the marker has an orientation, value and value_t for a coordinate marker

  • CoordinateJacobian: the Jacobian of a coordinate marker by the coordinates it acts on

  • JacobianODE2: the analytic Jacobian d(ODE2LHS)/dq of a body or connector, where it has one - the one the solver uses; for the others, NumericalJacobian of ODE2LHS

  • JacobianODE2_t: the analytic Jacobian d(ODE2LHS)/dq_t of a body or connector, where it has one

ConfigurationType

The enumeration type ConfigurationType is used for selecting a configuration for reading or writing information to the module. Specifically, the ConfigurationType.Current configuration is usually used at the end of a solution process, to obtain result values, or the ConfigurationType.Initial is used to set initial values for a solution process.

The class ConfigurationType has the following functions and structures:

  • _None: no configuration; usually not valid, but may be used, e.g., if no configurationType is required

  • Initial: initial configuration prior to static or dynamic solver; is computed during mbs.Assemble() or AssembleInitializeSystemCoordinates()

  • Current: current configuration during and at the end of the computation of a step (static or dynamic)

  • Reference: configuration used to define deformable bodies (reference configuration for finite elements) or joints (configuration for which some joints are defined)

  • StartOfStep: during computation, this refers to the solution at the start of the step = end of last step, to which the solver falls back if convergence fails

  • Visualization: this is a state completely de-coupled from computation, used for visualization

  • EndOfEnumList: this marks the end of the list, usually not important to the user

ItemType

The enumeration type ItemType is used for defining types of indices, e.g., in render window and will be also used in item dictionaries in future.

The class ItemType has the following functions and structures:

  • _None: item has no type

  • Node: item or index is of type Node

  • Object: item or index is of type Object

  • Marker: item or index is of type Marker

  • Load: item or index is of type Load

  • Sensor: item or index is of type Sensor

NodeType

The enumeration type NodeType is used for defining node types for 3D rigid bodies.

The class NodeType has the following functions and structures:

  • _None: node has no type

  • Ground: ground node

  • Position2D: 2D position node

  • Orientation2D: node with 2D rotation

  • Point2DSlope1: 2D node with 1 slope vector

  • Position: 3D position node

  • Orientation: 3D orientation node

  • RigidBody: node that can be used for rigid bodies

  • RotationEulerParameters: node with 3D orientations that are modelled with Euler parameters (unit quaternions)

  • RotationRxyz: node with 3D orientations that are modelled with Tait-Bryan angles

  • RotationRotationVector: node with 3D orientations that are modelled with the rotation vector

  • LieGroupWithDirectUpdate: node to be solved with Lie group methods, without data coordinates

  • GenericODE2: node with general ODE2 variables

  • GenericODE1: node with general ODE1 variables

  • GenericAE: node with general algebraic variables

  • GenericData: node with general data variables

  • PointSlope1: node with 1 slope vector

  • PointSlope12: node with 2 slope vectors in x and y direction

  • PointSlope23: node with 2 slope vectors in y and z direction

MarkerType

The enumeration type MarkerType lists the properties of a marker as bits; a connector or load requests a combination of them (GetRequestedMarkerType), which the marker type must contain.

The class MarkerType has the following functions and structures:

  • _None: no type is used

  • Body: marker is attached to a body (must also be Object)

  • Node: marker is attached to a node

  • Object: marker is attached to an object

  • SuperElement: marker only applicable to super elements; accesses (virtual) nodes of super elements

  • KinematicTree: marker only applicable to KinematicTree; accesses (virtual) nodes of KinematicTree

  • Position: can measure position, apply distance constraint

  • Orientation: can measure rotation, apply general rigid body constraint (if Position is set)

  • Coordinate: access any coordinate (always available)

  • Coordinates: access all coordinates (always available)

  • BodyLine: line load (vector load applied to line)

  • BodySurface: surface load / connector (e.g. for revolute joint with FE-mesh)

  • BodyVolume: volume load, usually gravity

  • BodyMass: mass proportional load, usually gravity

  • BodySurfaceNormal: surface pressure (uses scalar load)

  • MultiNodal: multinodal marker uses a weighting matrix to transform node values into the marker value

  • ReducedCoordinates: marker uses reduced (modal) coordinates of a super element

  • ODE1: marker addresses ODE1 coordinate(s) (standard is ODE2)

  • JacobianDerivativeNonZero: the derivative of the marker jacobian is non-zero (e.g. for rotations)

  • JacobianDerivativeAvailable: the derivative of the marker jacobian is implemented

  • HasPostNewton: the PostNewton function has to be called

  • Beam2DShape: access to 2D beam shape

  • Beam3DShape: access to 3D beam shape

JointType

The enumeration type JointType is used for defining joint types, used in KinematicTree.

The class JointType has the following functions and structures:

  • _None: node has no type

  • RevoluteX: revolute joint type with rotation around local X axis

  • RevoluteY: revolute joint type with rotation around local Y axis

  • RevoluteZ: revolute joint type with rotation around local Z axis

  • PrismaticX: prismatic joint type with translation along local X axis

  • PrismaticY: prismatic joint type with translation along local Y axis

  • PrismaticZ: prismatic joint type with translation along local Z axis

AccessFunctionType

The enumeration type AccessFunctionType lists the access functions (jacobians) an object provides for markers, as bits; its values share the bits of MarkerType. A marker can be attached to an object only if the object provides the access function the marker needs.

The class AccessFunctionType has the following functions and structures:

  • _None: no access function

  • TranslationalVelocity_qt: for application of forces, position constraints

  • AngularVelocity_qt: for application of torques, rotational constraints

  • Coordinate_q: for application of generalized forces

  • DisplacementLineIntegral_q: for line loads

  • DisplacementSurfaceIntegral_q: for surface loads

  • DisplacementVolumeIntegral_q: for distributed (body-volume) loads

  • DisplacementMassIntegral_q: for distributed (body-mass) loads

  • DisplacementSurfaceNormalIntegral_q: for surface loads; pressure acts normal to the surface

  • SuperElement: for super elements, using TranslationalVelocity_qt and AngularVelocity_qt

  • KinematicTree: for KinematicTree, using TranslationalVelocity_qt and AngularVelocity_qt

  • OwnMarkersOnly: the access functions serve only the object’s own markers (super element or kinematic tree markers); the general body markers are refused

  • JacobianTtimesVector_q: derivative of jacobian^T times vector (provided in markerData.vectorValue)

DynamicSolverType

The enumeration type DynamicSolverType is used for selecting dynamic solvers for simulation.

The class DynamicSolverType has the following functions and structures:

  • GeneralizedAlpha: an implicit solver for index 3 problems; intended to be used for solving directly the index 3 constraints using the spectralRadius sufficiently small (usually 0.5 .. 1)

  • TrapezoidalIndex2: an implicit solver for index 3 problems with index2 reduction; uses generalized alpha solver with settings for Newmark with index2 reduction

  • ExplicitEuler: an explicit 1st order solver (generally not compatible with constraints)

  • ExplicitMidpoint: an explicit 2nd order solver (generally not compatible with constraints)

  • RK33: an explicit 3 stage 3rd order Runge-Kutta method, aka “Heun third order”; (generally not compatible with constraints)

  • RK44: an explicit 4 stage 4th order Runge-Kutta method, aka “classical Runge Kutta” (generally not compatible with constraints), compatible with Lie group integration and elimination of CoordinateConstraints

  • RK67: an explicit 7 stage 6th order Runge-Kutta method, see ‘On Runge-Kutta Processes of High Order’, J. C. Butcher, J. Austr Math Soc 4, (1964); can be used for very accurate (reference) solutions, but without step size control!

  • ODE23: an explicit Runge Kutta method with automatic step size selection with 3rd order of accuracy and 2nd order error estimation, see Bogacki and Shampine, 1989; also known as ODE23 in MATLAB

  • DOPRI5: an explicit Runge Kutta method with automatic step size selection with 5th order of accuracy and 4th order error estimation, see Dormand and Prince, ‘A Family of Embedded Runge-Kutta Formulae.’, J. Comp. Appl. Math. 6, 1980

  • DVERK6: [NOT IMPLEMENTED YET] an explicit Runge Kutta solver of 6th order with 5th order error estimation; includes adaptive step selection

  • VelocityVerlet: [TEST phase] a special explicit time integration scheme, the ‘velocity Verlet’ method (similar to leap frog method), with second order accuracy for conservative second order differential equations, often used for particle dynamics and contact; implementation uses Explicit Euler for ODE1 equations

CrossSectionType

The enumeration type CrossSectionType is used for defining beam cross section types.

The class CrossSectionType has the following functions and structures:

  • Polygon: cross section profile defined by polygon

  • Circular: cross section is circle or elliptic

KeyCode

The enumeration type KeyCode is used for special key codes in keyPressUserFunction.

The class KeyCode has the following functions and structures:

  • SPACE: space key

  • ENTER: enter (return) key

  • TAB

  • BACKSPACE

  • RIGHT: cursor right

  • LEFT: cursor left

  • DOWN: cursor down

  • UP: cursor up

  • F1: function key F1

  • F2: function key F2

  • F3: function key F3

  • F4: function key F4

  • F5: function key F5

  • F6: function key F6

  • F7: function key F7

  • F8: function key F8

  • F9: function key F9

  • F10: function key F10

LinearSolverType

The enumeration type LinearSolverType is used for selecting linear solver types, which are dense or sparse solvers.

The class LinearSolverType has the following functions and structures:

  • _None: no value; used, e.g., if no solver is selected

  • EXUdense: use dense matrices and according solvers for densly populated matrices (usually the CPU time grows cubically with the number of unknowns)

  • EigenSparse: use sparse matrices and according solvers; additional overhead for very small multibody systems; specifically, memory allocation is performed during a factorization process

  • EigenSparseSymmetric: use sparse matrices and according solvers; NOTE: this is the symmetric mode, which assumes symmetric system matrices; this is EXPERIMENTAL and should only be used of user knows that the system matrices are (nearly) symmetric; does not work with scaled GeneralizedAlpha matrices; does not work with constraints, as it must be symmetric positive definite

  • EigenDense: use Eigen’s LU factorization with partial pivoting (faster than EXUdense) or full pivot (if linearSolver.ignoreSingularJacobian=True; is much slower, but can resolve overdetermined and underdetermined problems!); NOTE: in the default partial pivoting mode a singular matrix is NOT detected - Eigen provides no invertibility check there - so the solver continues with an undefined result instead of reporting a singular jacobian; use EXUdense or EigenSparse if that must be reported, or full pivot (ignoreSingularJacobian=True), which resolves the singular system by least squares on purpose

ContactTypeIndex

The enumeration type ContactTypeIndex is used in GeneralContact to select specific contact items, such as spheres, ANCFCable or triangle items.

The class ContactTypeIndex has the following functions and structures:

  • IndexSpheresMarkerBased: spheres attached to markers

  • IndexANCFCable2D: ANCFCable2D contact items

  • IndexTrigsRigidBodyBased: triangles attached to rigid body (or rigid body marker)

  • IndexEndOfEnumList: signals end of list