ObjectConnectorCoordinateVector

A constraint which constrains the coordinate vectors of two markers Marker[Node|Object|Body]Coordinates attached to nodes or bodies. The marker uses the objects LTG-lists to build the according coordinate mappings.

Additional information for ObjectConnectorCoordinateVector:

  • This Object has/provides the following types = Connector, Constraint
  • Requested Marker type = Coordinate
  • Short name for Python = CoordinateVectorConstraint
  • Short name for Python visualization object = VCoordinateVectorConstraint

The item ObjectConnectorCoordinateVector with type = ‘ConnectorCoordinateVector’ has the following parameters:

  • name [type = String, default = ‘’]:
    constraints’s unique name
  • markerNumbers [\([m0,m1]\tp\), type = ArrayMarkerIndex, default = [ invalid [-1], invalid [-1] ]]:
    list of markers used in connector
  • scalingMarker0 [\({\mathbf{X}}_{m0} \in \Rcal^{n_{ae} \times n_{q_{m0}}}\), type = NumpyMatrix, default = Matrix[]]:
    linear scaling matrix for coordinate vector of marker 0; matrix provided in Python numpy format
  • scalingMarker1 [\({\mathbf{X}}_{m1} \in \Rcal^{n_{ae} \times n_{q_{m1}}}\), type = NumpyMatrix, default = Matrix[]]:
    linear scaling matrix for coordinate vector of marker 1; matrix provided in Python numpy format
  • quadraticTermMarker0 [\({\mathbf{Y}}_{m0} \in \Rcal^{n_{ae} \times n_{q_{m0}}}\), type = NumpyMatrix, default = Matrix[]]:
    quadratic scaling matrix for coordinate vector of marker 0; matrix provided in Python numpy format
  • quadraticTermMarker1 [\({\mathbf{Y}}_{m0} \in \Rcal^{n_{ae} \times n_{q_{m0}}}\), type = NumpyMatrix, default = Matrix[]]:
    quadratic scaling matrix for coordinate vector of marker 1; matrix provided in Python numpy format
  • offset [\({\mathbf{v}}_\mathrm{off} \in \Rcal^{n_{ae}}\), type = NumpyVector, default = []]:
    offset added to constraint equation; only active, if no userFunction is defined
  • velocityLevel [type = Bool, default = False]:
    If true: connector constrains velocities (only works for ODE2 coordinates!); offset is used between velocities; in this case, the offsetUserFunction_t is considered and offsetUserFunction is ignored
  • constraintUserFunction [\({\mathbf{c}}_{user} \in \Rcal^{n_{ae}}\), type = PyFunctionVectorMbsScalarIndex2VectorBool, default = 0]:
    A Python user function which computes the constraint equations; to define the number of algebraic equations, set scalingMarker0 as a numpy.zeros((nAE,1)) array with nAE being the number algebraic equations; see description below
  • jacobianUserFunction [\({\mathbf{J}}_{user} \in \Rcal^{(n_{q_{m0}}+n_{q_{m1}}) \times n_{ae}}\), type = PyFunctionMatrixContainerMbsScalarIndex2VectorBool, default = 0]:
    A Python user function which computes the jacobian, i.e., the derivative of the left-hand-side object equation w.r.t.the coordinates (times \(f_{ODE2}\)) and w.r.t.the velocities (times \(f_{ODE2_t}\)). Terms on the RHS must be subtracted from the LHS equation; the respective terms for the stiffness matrix and damping matrix are automatically added; see description below
  • activeConnector [type = Bool, default = True]:
    flag, which determines, if the connector is active; used to deactivate (temporarily) a connector or constraint
  • visualization [type = VObjectConnectorCoordinateVector]:
    parameters for visualization of item

The item VObjectConnectorCoordinateVector has the following parameters:

  • show [type = Bool, default = True]:
    set true, if item is shown in visualization and false if it is not shown
  • color [type = Float4, default = [-1.,-1.,-1.,-1.]]:
    RGBA connector color; if R==-1, use default color

DESCRIPTION of ObjectConnectorCoordinateVector

The following output variables are available as OutputVariableType in sensors, Get…Output() and other functions:

  • Displacement: \(\Delta {\mathbf{q}}\)
    relative scalar displacement of marker coordinates, not including scaling matrices
  • Velocity: \(\Delta {\mathbf{v}}\)
    difference of scalar marker velocity coordinates, not including scaling matrices
  • ConstraintEquation: \({\mathbf{c}}\)
    (residuum of) constraint equations
  • Force: \(\tlambda\)
    constraint force vector (vector of Lagrange multipliers), resulting from action of constraint equations

Definition of quantities

intermediate variables
symbol
description
marker m0 coordinate vector
\({\mathbf{q}}_{m0} \in \Rcal^{n_{q_{m0}}}\)
coordinate vector provided by marker \(m0\); depending on the marker, the coordinates may or may not include reference coordinates
marker m1 coordinate vector
\({\mathbf{q}}_{m1} \in \Rcal^{n_{q_{m1}}}\)
coordinate vector provided by marker \(m1\); depending on the marker, the coordinates may or may not include reference coordinates
marker m0 velocity coordinate vector
\(\dot {\mathbf{q}}_{m0} \in \Rcal^{n_{q_{m0}}}\)
velocity coordinate vector provided by marker \(m0\)
marker m1 velocity coordinate vector
\(\dot {\mathbf{q}}_{m1} \in \Rcal^{n_{q_{m1}}}\)
velocity coordinate vector provided by marker \(m1\)
number of algebraic equations
\(n_{ae}\)
number of algebraic equations must be same as number of rows in \({\mathbf{X}}_{m0}\) and \({\mathbf{X}}_{m1}\)
difference of coordinates
\(\Delta {\mathbf{q}} = {\mathbf{q}}_{m1} - {\mathbf{q}}_{m0}\)
Displacement between marker m0 to marker m1 coordinates
difference of velocity coordinates
\(\Delta {\mathbf{v}}= \dot {\mathbf{q}}_{m1} - \dot {\mathbf{q}}_{m0}\)

Remarks

The number of algebraic equations depends on the maximum number of rows in \({\mathbf{X}}_{m0}\), \({\mathbf{Y}}_{m0}\), \({\mathbf{X}}_{m1}\) and \({\mathbf{Y}}_{m1}\). The number of rows of the latter matrices must either be zero or the maximum of these rows.

The number of columns in \({\mathbf{X}}_{m0}\) (or \({\mathbf{Y}}_{m0}\)) must agree with the length of the coordinate vector \({\mathbf{q}}_{m0}\) and the number of columns in \({\mathbf{X}}_{m1}\) (or \({\mathbf{Y}}_{m1}\)) must agree with the length of the coordinate vector \({\mathbf{q}}_{m1}\), if these matrices are not empty matrices. If one marker \(k\) is a ground marker (node/object), the length of \({\mathbf{q}}_{m,k}\) is zero and also the according matrices \({\mathbf{X}}_{m,k}\), \({\mathbf{Y}}_{m,k}\) have zero size and will not be considered in the computation of the constraint equations.

Connector constraint equations

If activeConnector = True and no constraintUserFunction is defined, the index 3 algebraic equations

\[{\mathbf{c}}({\mathbf{q}}_{m0}, {\mathbf{q}}_{m1}) = {\mathbf{X}}_{m1} \cdot {\mathbf{q}}_{m1} + {\mathbf{Y}}_{m1} \cdot {\mathbf{q}}^2_{m1} - {\mathbf{X}}_{m0} \cdot{\mathbf{q}}_{m0} - {\mathbf{Y}}_{m0} \cdot{\mathbf{q}}^2_{m0} - {\mathbf{v}}_\mathrm{off} = 0\]

Note that the squared coordinates are understood as \({\mathbf{q}}^2_{m0} = [q^2_{0,m0}, \; q^2_{1,m0}, \; \ldots]\tp\), same for \({\mathbf{q}}^2_{m1}\).

The index 2 (velocity level) algebraic equation accordingly reads

\[\dot {\mathbf{c}}(\dot {\mathbf{q}}_{m0}, \dot {\mathbf{q}}_{m1}) = {\mathbf{X}}_{m1} \cdot \dot {\mathbf{q}}_{m1} + {\mathbf{Y}}_{m1} \cdot \dot {\mathbf{q}}^2_{m1} - {\mathbf{X}}_{m0} \cdot \dot {\mathbf{q}}_{m0} - {\mathbf{Y}}_{m0} \cdot \dot {\mathbf{q}}^2_{m0} - {\mathbf{d}}_\mathrm{off} = 0\]

The vector \({\mathbf{d}}\) in velocity level equations is zero, except if parameters.velocityLevel = True, then \({\mathbf{d}}={\mathbf{v}}_\mathrm{off}\).

Note that the index 2 equations are used, if the solver uses index 2 formulation OR if the flag parameters.velocityLevel = True (or both). However, the constraintUserFunction has to be chosen accordingly by the user, either as position or as velocity level. The user functions include dependency on time \(t\), but this time dependency is not respected in the computation of initial accelerations. Therefore,

If activeConnector = False, the (index 1) algebraic equation reads for ALL cases:

\[{\mathbf{c}}(\tlambda) = \tlambda = 0\]

If a constraintUserFunction is defined, it also requires an according jacobianUserFunction (and vice versa).

Userfunction: constraintUserFunction(mbs, t, itemNumber, q, q_t, velocityLevel)

A user function, which computes algebraic equations for the connector based on the marker coordinates stored in q and q_t. Depending on velocityLevel, the user function needs to compute either the position-level (velocityLevel=False) or the velocity level (velocityLevel=True) constraint equations. Note that for Index 2 solvers, the constraintUserFunction may be called with velocityLevel=True but jacobianUserFunctionis called with velocityLevel=False. To define the number of algebraic equations, set scalingMarker0 as a numpy.zeros((nAE,1)) array with nAE being the number algebraic equations. The returned vector of constraintUserFunction must have size nAE.

Note that itemNumber represents the index of the ObjectGenericODE2 object in mbs, which can be used to retrieve additional data from the object through mbs.GetObjectParameter(itemNumber, ...), see the according description of GetObjectParameter.

arguments / return
type or size
description
mbs
MainSystem
provides MainSystem mbs to which object belongs to
t
Real
current time in mbs
itemNumber
Index
integer number \(i_N\) of the object in mbs, allowing easy access to all object data via mbs.GetObjectParameter(itemNumber, …)
q
Vector \(\in \Rcal^{(n_{q_{m0}}+n_{q_{m1}})}\)
connector coordinates, subsequently for marker \(m0\) and marker \(m1\), in current configuration
q_t
Vector \(\in \Rcal^{(n_{q_{m0}}+n_{q_{m1}})}\)
connector velocity coordinates in current configuration
velocityLevel
Bool
velocityLevel as currently stored in connector
returnValue
Vector \(\in \Rcal^{n_{ae}}\)
returns vector (numpy array or list) of evaluated constraint equations for connector

Userfunction: jacobianUserFunction(mbs, t, itemNumber, q, q_t, velocityLevel)

A user function, which computes the jacobian of the algebraic equations w.r.t. the ODE2 coordiantes (ODE2_t velocity coordinates if velocityLevel=True). The jacobian needs to exactly represent the derivative of the constraintUserFunction. The returned matrix of jacobianUserFunction must have nAE rows and len(q) columns.

arguments / return
type or size
description
mbs
MainSystem
provides MainSystem mbs to which object belongs to
t
Real
current time in mbs
itemNumber
Index
integer number \(i_N\) of the object in mbs, allowing easy access to all object data via mbs.GetObjectParameter(itemNumber, …)
q
Vector \(\in \Rcal^{(n_{q_{m0}}+n_{q_{m1}})}\)
connector coordinates, subsequently for marker \(m0\) and marker \(m1\), in current configuration
q_t
Vector \(\in \Rcal^{(n_{q_{m0}}+n_{q_{m1}})}\)
connector velocity coordinates in current configuration
velocityLevel
Bool
velocityLevel as currently stored in connector
returnValue
MatrixContainer \(\in \Rcal^{(n_{q_{m0}}+n_{q_{m1}})\times n_{ae}}\)
returns special jacobian for connector, as exu.MatrixContainer, numpy array or list of lists; use MatrixContainer sparse format for larger matrices to speed up computations; sparse triplets MAY NOT contain zero values!

Relevant Examples and TestModels with weblink:

The web version may not be complete. For details, consider also the Exudyn PDF documentation : theDoc.pdf