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 :ref:`LTG <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 :ref:`ODE2 <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
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
: \tlambdaconstraint force vector (vector of Lagrange multipliers), resulting from action of constraint equations
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}
|
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.
If activeConnector = True
, 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}.
If the offsetUserFunction \mathrm{UF} is defined, {\mathbf{c}} instead becomes (t is current time)
{\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} - \mathrm{UF}(mbs, t,{\mathbf{v}}_\mathrm{off}) = 0
The activeConnector = True
, index 2 (velocity level) algebraic equation 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 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)
\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} - \mathrm{UF}_t(mbs, t,{\mathbf{v}}_\mathrm{off}) = 0
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:
{\mathbf{c}}(\tlambda) = \tlambda = 0
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