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 matricesVelocity
: \(\Delta {\mathbf{v}}\)difference of scalar marker velocity coordinates, not including scaling matricesConstraintEquation
: \({\mathbf{c}}\)(residuum of) constraint equationsForce
: \(\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
, the index 3 algebraic equations
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}\).
If the offsetUserFunction \(\mathrm{UF}\) is defined, \({\mathbf{c}}\) instead becomes (\(t\) is current time)
The activeConnector = True
, index 2 (velocity level) algebraic equation reads
The vector \(dv\) in velocity level equations is zero, except if parameters.velocityLevel = True, then \({\mathbf{d}}={\mathbf{v}}_\mathrm{off}\).
If velocity level constraints are active and the velocity level offsetUserFunction_t
\(\mathrm{UF}_t\) is defined,
\(\dot {\mathbf{c}}\) instead becomes (\(t\) is current time)
Note that the index 2 equations are used, if the solver uses index 2 formulation OR if the flag parameters.velocityLevel = True (or both). The user functions include dependency on time \(t\), but this time dependency is not respected in the computation of initial accelerations. Therefore, it is recommended that \(\mathrm{UF}\) and \(\mathrm{UF}_t\) does not include initial accelerations.
If activeConnector = False
, the (index 1) algebraic equation reads for ALL cases:
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 jacobianUserFunction
is 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:
coordinateVectorConstraint.py (TestModels/), coordinateVectorConstraintGenericODE2.py (TestModels/), rigidBodyAsUserFunctionTest.py (TestModels/)
The web version may not be complete. For details, consider also the Exudyn PDF documentation : theDoc.pdf