## Constraints: Curvilinear examples |

Curvilinear constraints are an extremely versatile feature of OrcaFlex; here, we give just a few examples of how they can be used.

Time-dependent mappings can constrain the motion of the out-frame to curves and surfaces which change shape as the simulation progresses. For instance, with $x$ as a free coordinate and using the reserved symbols t and t0, the following mapping defines a travelling wave with the out-frame constrained to move along its surface:

v = 1 # velocity

y = 0

z = sin(x - v*(t - t0))

Rx = 0

Ry = 0

Rz = 0

Figure: | $\boldsymbol{z = \sin[x - v(t-t_0)]}$ |

This wave travels from left to right with constant velocity $v{=}1$.

Now, in statics, all objects have zero velocity (at least for zero starting velocity, which is usually the case); and so, to avoid discontinuities, the free coordinates are all given zero velocity (or the starting velocity) at the start of dynamics, when t$=$t0. This does not, however, avoid discontinuities in the *mapped* coordinates. In this example, although the initial $x$-velocity, $\dot{x}$, is forced to be zero, the initial $z$-velocity of $\dot{z}=(\dot{x}{-}v) \cos x$ is not, in general, zero.

To avoid the discontinuity between statics and dynamics that arise from mappings such as this, we recommend that the ramping factor be used to gradually phase in the time-dependence of the mapping. A better choice of mapping in this example might therefore be:

v = 1 # velocity

y = 0

z = sin(x - ramp*v*(t - t0))

Rx = 0

Ry = 0

Rz = 0

Note: | Time-dependent curvilinear constraints and Rayleigh damping are not fully compatible. This may lead to unrealistic tension results for any connected lines that use Rayleigh damping. |

Time-dependent mappings can be used to completely impose the motion of the out-frame relative to the in-frame. This can be a more convenient alternative to an imposed motion constraint when the motion is a prescribed function of time. For example, consider a case where the out-frame rotates about the $y$-axis of the in-frame at a constant angular velocity, $\omega = $ 1 rad/s:

omega = 1.0 # rad/s

x = 0

y = 0

z = 0

Rx = 0

Ry = omega*t

Rz = 0

This would be impossible to achieve exactly with a time-history imposed motion constraint and would require much more work using an externally calculated one.

Note: | There is no need to define free coordinates in an imposed motion mapping because the position of the out-frame relative to the in-frame is entirely prescribed. |

Consider the case of of translational motion defined in terms of spherical polar coordinates, $r$, $\theta$ and $\phi$, where for convenience we wish $\theta$ and $\phi$ to be expressed in degrees. We can use the rad function to define the following mapping:

theta_r = rad(theta)

phi_r = rad(phi)

x = r*cos(theta_r)*sin(phi_r)

y = r*sin(theta_r)*sin(phi_r)

z = r*cos(phi_r)

Rx = 0

Ry = 0

Rz = 0

In this case, the out-frame has three translational degrees of freedom, just like in the case of a Cartesian constraint with $x$, $y$ and $z$ free. The difference is that OrcaFlex will be solving the equations of motion in a different *coordinate system*, which can sometimes be convenient, either for numerical stability or for the reporting of results. Mathematically, this is known as a *diffeomorphism*. However, not all coordinate systems are equal. For instance, in the spherical polar coordinates defined above, problems may occur if the in-frame and the out-frame are coincident, such that $r\!\rightarrow\!0$. In this limit, changes to the $\theta$ and $\phi$ values lead to vanishingly small changes to values of the $x$, $y$ and $z$ coordinates, which can lead to numerical instability. This limit is an example of a *coordinate singularity*.

One important point to bear in mind is that the mappings to the basic $Rx$, $Ry$ and $Rz$ DOFs are expected to be specified in **radians**, not degrees. This differs from the convention used when defining a Cartesian constraint because it is usually more convenient to work in radians when defining mathematical formulae. User-coordinates can be expressed in any dimensions or units, so an angle coordinate could have units of either radians or degrees at the user's discretion. Often it is useful to define angle coordinates in degrees for purposes of setting coordinate initial values, in which case the rad function can again be of use.

Further examples of coordinate singularities arise in the parameterisation of rigid body rotations: the mapping between three rotational coordinates and the orientation of the rigid body. For Cartesian constraints, we chose to work in terms of the rotation vector defined by the $Rx$, $Ry$ and $Rz$ coordinates. We made this choice in the expectation that these would be the most useful coordinates to work with. However, we could equally well have worked with a set of Euler angles or some other coordinate system. Rotation vectors and Euler angles both suffer from coordinate singularities (for rotation vectors, it is the limit that the magnitude of the rotation vector approaches $2\pi$) and care must be taken to avoid these. Mathematically, this means that the space of rigid body rotations cannot be exactly covered by a single choice of coordinates – a *coordinate chart* – and it may be necessary to transition between different charts to avoid singularities. For Cartesian constraints, this chart switching logic is handled internally within OrcaFlex. For curvilinear constraints, in which you are only permitted to define a single set of coordinates within the constraint, this switching logic cannot be applied and the simulation could potentially encounter numerical difficulties at large angles of rotation. In principle, it would be possible to allow multiple coordinate charts and the transition functions between them, but this would add unnecessary complexity to an already complex feature.

Note: | It is possible to define a coordinate system for rigid body rotations that does not have a coordinate singularity. These coordinates are known as quaternions and provide a 2:1 mapping onto the space of rigid body rotations, known as SO(3). Whilst the use of quaternions alleviates the necessity to switch between coordinate charts, their definition and use is far from intuitive. |

It is also possible to couple translational and rotational motion. For instance, the mapping:

theta = rad(10) # slope angle = 10 degrees

R = 10 # object radius, m

x = l*cos(theta)

y = 0

z = l*sin(theta)

Rx = 0

Ry = l/R

Rz = 0

where $l$ is a free coordinate, could be used to model an object of radius $R$ rolling without slipping down a inclined slope: the out-frame rotates through a full 360° every time the object moves a distance along the slope equal to its circumference $(2 \pi R)$. A similar mapping could be used to model an object constrained to move along a screw thread, which would couple, for example, the $z$ and $Rz$ DOFs.

Contraint surfaces made up of distinct sections can be defined by using the Piecewise function, e.g.:

y = 0

z = Piecewise((10, x < -10), (-x, x < 10), (-10, True))

Rx = 0

Ry = 0

Rz = 0

where $x$ is the only free coordinate. This will work best if the defined piecewise curve is everywhere continuous and smooth – unlike this example – otherwise the motion may not be physically realistic as the out-frame crosses a boundary between two distinct sections of the constraint surface.

Figure: | $z = \begin{cases} 10 & x \lt -10 \\ -x & -10 \leq x \leq 10 \\ -10 & x \gt 10 \end{cases}$ |

As an example of a release condition, consider the case in which the out-frame is sliding along the circumference of a circle in the vertical plane,

R = 10 # circle radius

x = R*sin(theta)

y = 0

z = R*cos(theta)

Rx = 0

Ry = 0

z = 0

where $\theta$ (theta) is the only free coordinate.

Figure: | $x = R \sin \theta \quad z = R \cos \theta$ |

We wish to model the motion of the out-frame starting from the initial position $\theta=\theta_0$. With no release condition specified, the out-frame is constrained to lie on the circle for the entire duration of the simulation. In reality, however, the circle can only provide an outwards pushing force; it cannot pull inwards. The out-frame will therefore remain constrained only so long as the component of the connection force in the outward normal direction to the circle is positive. If this is not the case, then the out-frame would be expected to fall off. This leads us to the following release condition:

from numpy import cross

releaseCondition = cross(thetaHatT, F)[1] > 0 # the connection force is in the inward normal direction when the y-component of the cross product is positive

where $\hat{\vec{\theta}}_\mathrm{t}$ (thetaHatT) is a unit vector tangential to the circle at the current value of $\theta$.

Notes: | The release condition is only evaluated after the dynamic simulation has started; the out-frame will never be released during the statics calculation. |

You can define that the out-frame is released at the start of a particular stage and specify a release condition: the out-frame will release as soon as the first of the two release criteria is satisfied. |