Constraints: Curvilinear coordinates

Curvilinear constraints allow a wide class of generalised constraint problems to be modelled in OrcaFlex, such as restricting the motion of the out-frame to lie on an arbitrary curve or surface, mixed calculated and imposed motion, and dynamic release of the out-frame based upon user-specified criteria.

Note: It is necessary to have both Python and the Python SymPy module installed in order to use curvilinear constraints. See Python Interface: Installation for more information on installing Python, and on the embedded Python distribution that can be automatically installed as part of the OrcaFlex installation process.

The utility of curvilinear constraints comes from the ability to define a bespoke set of coordinates in which to model the motion of the out-frame relative to the in-frame. The number of user-specified coordinates corresponds to the number of degrees of freedom in which motion of the out-frame is possible: one user-specified coordinate corresponds to motion along a curve, two to motion on a surface, etc. We will illustrate this shortly with an example, but for now let us recall the six basic degrees of freedom of the constraint: $x$, $y$, $z$, $Rx$, $Ry$ and $Rz$. These are defined in the same way as for a simple Cartesian constraint: $x$, $y$ and $z$ are the translational coordinates of the out-frame origin relative and with respect to the axes of the in-frame; $Rx$, $Ry$ and $Rz$ are the components of a rotation vector, again expressed relative and with respect to the axes of the in-frame. The magnitude of this rotation vector is the angle of rotation necessary to rotate the in-frame to the out-frame; its direction gives the axis of rotation.

As an example, consider constraining the motion of the out-frame to lie on the straight line $X{=}Z$, where $X$ and $Z$ are the usual coordinates with repect to global axes. This is straightforward to achieve via a Cartesian constraint: simply place the constraint at the global origin, set the declination of the in-frame to $45$° and the $z$ DOF to be free. Using a curvilinear constraint, we could instead define a single free coordinate, $q$ say, and then define the mappings $x=q$ and $z=q$, which are parametric equations of a straight line. How such mappings are set up will be described below, but for now the aim is to present the general concept. Similarly, the constraint $z=5x$ can be implemented by specifying $x=q$, $z=5q$. In fact, we can do better than this, and simply define $x$ itself as a free coordinate, so that we merely need to specify $z=5x$. It may seem trivial, but try doing this with a Cartesian constraint!

Figure: $\boldsymbol{z=5x}$

So far, $q$ (or $x$), is our only free coordinate, so the motion of the out-frame relative to the in-frame will be one-dimensional. A straight line is a relatively uninteresting constraint though, so let us consider the curve $z=x^2$: a parabola. To implement this, we define $x$ as our free coordinate and then specify $z=x^2$.

Figure: $\boldsymbol{z=x^2}$

A two-dimensional surface can be defined in an analogous fashion: consider two coordinates $r$ and $\phi$, together with the mappings $x=r \cos \phi$, $y=r \sin \phi$ and $z=r^2$. These mappings define a parabolic well in polar coordinates, with $r$ the horizontal distance between the the out-frame and the in-frame (i.e. in the $x$-$y$ plane) and $\phi$ the azimuth angle measured from the $x$-axis.

Figure: $\boldsymbol{x=r \cos \phi, \quad y=r \sin \phi, \quad z=r^2}$

Mappings, and free coordinates, are defined on the coordinates page of the constraint data form.

Free coordinates

Free coordinates are defined, one per row, in this table. The following data are associated with each free coordinate:

Out-frame release stage

In the same way as for Cartesian constraints, the out-frame can be released from the in-frame at the start of any stage of the simulation, such that all of its six DOFs become free.


The mapping between the free coordinates and the six basic DOFs ($x$, $y$, $z$, $Rx$, $Ry$ and $Rz$) is defined via a series of Python commands entered as free-form text. It is essential that all six basic DOFs are defined on the coordinates page, either as free coordinates or as a mapping. For instance, the default mapping is

x = 0

y = 0

z = 0

Rx = 0

Ry = 0

Rz = 0

which means that no DOFs are free: the in-frame and the out-frame are rigidly connected and, since all the values are zero, coincident. The earlier example of $z=5x$ can be implemented in one of two ways: you can either define a free coordinate $q$ and the mapping

x = q

y = 0

z = 5*q

Rx = 0

Ry = 0

Rz = 0

or define $x$ itself to be a free coordinate and define the mapping

y = 0

z = 5*x

Rx = 0

Ry = 0

Rz = 0

Similarly, the following mapping defines the earlier parabolic well example with $r$ and $\phi$ (phi) as free coordinates:

x = r*cos(phi)

y = r*sin(phi)

z = r**2

Rx = 0

Ry = 0

Rz = 0

In all cases, all six DOFs are defined, with the definitions being shared between the free coordinates and mappings.

As you edit the mappings, OrcaFlex will try to evaluate them dynamically. Text in the bottom-left corner of the coordinates page indicates whether or not the current mapping text is valid and, if it is not, will provide details of any problems.

The preceding example has one free translational DOF and is fixed in rotation. To have the same translational mapping but with free rotational motion in all directions, define $Rx$, $Ry$ and $Rz$ as additional free coordinates, and specify the remaining DOF, $y$, as a mapping along with $z$:

Figure: Free DOFs $\boldsymbol{x}$, $\boldsymbol{Rx}$, $\boldsymbol{Ry}$ and $\boldsymbol{Rz}$

Many common mathematical functions are available to mappings, including $\sin$, $\cos$, $\tan$ and $\exp$. It is important to note that these functions are defined within SymPy and act symbolically, rather than numerically. Some common constants, such as pi, are also pre-defined. A (non-comprehensive) list of functions available via SymPy is available on the SymPy help pages.

OrcaFlex also has certain reserved symbols available for use in mappings. These are

Further examples of mappings, illustrating the use of mathematical functions and time-varying quantities, can be found on the curvilinear constraints examples page.

Out-frame release condition

As well as the ability to release the out-frame from the in-frame based on the simulation stage, you can also arrange that the out-frame is released if a user-defined condition is satisfied. Once again, this condition is specified using a free-form Python script, which this time sets a Python boolean variable named releaseCondition. For example,

releaseCondition = x > 10

will release the out-frame if and when the $x$ coordinate becomes greater than 10. Unlike mappings, the release condition is evaluated numerically, not symbolically, so it is necessary to import modules such as NumPy to gain access to common mathematical operators. Several pre-defined variables can be accessed in the release condition script:

t, t0 and ramp, as available to mappings, are also available to the release condition. As an example, consider the case in which the out-frame is rigidly attached to the in-frame via the default mapping, and define the following release condition:

from numpy.linalg import norm

releaseCondition = norm(F) > 1000

This release condition means that the out-frame will be released once the magnitude of the connection force becomes greater than $1000$ force units (the units used in the Python script must be consistent with those prevailing in the OrcaFlex model). This may be useful for modelling the failure of a rigid connection when some maximum tension (or compression) has been exceeded.

Further examples of release conditions are given on the curvilinear constraints examples page.