General data: Jacobians

Internally, OrcaFlex evaluates Jacobian matrices, which encode how the forces in the model change due to infinitesimal changes of the coordinates of the model objects. These are used for several main purposes

1. To calculate frequency domain loads.
2. To improve the convergence of static and implicit time domain dynamic analyses.
3. To compute modal analyses.

The settings on this page can be used to adjust how OrcaFlex evaluates its Jacobian matrices.

Jacobian buffering policy

This data determines how OrcaFlex marshals Jacobian contributions for chains of connected objects. In some circumstances, when the chains of connections are deep (e.g. parent -> child -> grandchild -> great-grandchild -> ...), it can greatly improve performance to gather up (buffer) contributions from a particular child object before passing them down to its parent object; conversely, in models having a large number of single depth parent -> child connections, buffering can itself lead to poorer performance.

The Jacobian buffering policy is specified by a string of 0s and 1s, optionally terminated by a * character. The first character in the sequence corresponds to the first child object in a chain (parent -> child -> grandchild -> ...); the second character corresponds to the second child object (grandchild); the third character to the great-grandchild, etc. If the character at a given point in the sequence is 1, then it means to buffer all objects that are connected in a chain at the corresponding depth; if the character is 0, then it means not to buffer at that depth. If any connection chains are longer than the stated buffering policy, then we adopt one of two approaches: if the stated policy does not terminate with a * character, then we repeat the entire policy afresh from the start; if the stated policy does terminate with a * character, then we simply repeat the final 0 or 1 character in the policy ad infinitum.

This is best illustrated by some examples:

• 0 means no buffering.
• 1 means buffer everything.
• 10 means to buffer alternate depths in a chain; so, children, great-grandchildren, great-great-great-grandchildren, etc.
• 01 also means to buffer alternate depths in a chain, but in the opposite sense; so, grandchildren, great-great-grandchildren, etc.
• 10* means to buffer the first child in a chain only and, thereafter, not to buffer.
• 0* means the same as 0.
• 101 means to buffer the first and third children, then the fourth and sixth, then the seventh and ninth, etc.

The default buffering policy is 01. In our experience, this gives the best overall performance for the widest variety of models.

In which circumstances should you consider changing the buffering policy? There are two extreme cases:

1. The model contains a large number of single depth, parent -> child, connections. In this case it is often more efficient to turn off buffering altogther. You may wish to experiment with a buffering policy of 0.
2. The model contains a long chain of connected objects, e.g. parent -> child -> grandchild -> great-grandchild -> ... In this case it may be more efficient to enable buffering at all depths and use a policy of 1. Note that turning off buffering altogether for such cases can lead to a marked reduction in performance, often deteriorating exponentially as more depth is added to the chains of connections. The presence of constraints in such chains can be especially deterimental if buffering is disabled.

This is only general guidance. In reality, the best buffering policy may not be obvious and might require some trial and error to determine.

Jacobian perturbation factor

Sometimes a model will fail to converge because it has a singular Jacobian matrix. This can indicate that there is a problem with the model, but often it just means that some of its coordinates (or some combination of its coordinates) just do not matter. Technically, such models are known as indeterminate. Consider, for instance, the case of a perfectly cylindrical buoy. All other things being equal, this buoy can be rotated by an arbitrary amount about its axis of symmetry without affecting the forces it experiences. Such a system has multiple equilibria and the angle of rotation of the buoy about its axis is effectively redundant. Mathematically, this can cause problems because OrcaFlex's solver is not aware of this redundancy. Such a scenario results in a singular Jacobian matrix because changes to the redundant coordinate have no bearing on the physical forces acting on the model. This is an issue because the various solvers within OrcaFlex often need to invert the Jacobian matrix to find a solution. A singular matrix has no inverse, by definition.

Thankfully, indeterminate models are comparatively rare because most physical systems are sufficiently complex to break any such symmetries, so that the resultant Jacobian matrices are not singular. Nevertheless, such models do arise from time to time, and more so with the advent of indirect constraints, the use of which can lead to indeterminate connection loads when two objects or subsystems are connected together by more than one constraint.

If an indeterminate model is encountered, then it can often be made to run by setting the Jacobian perturbation factor to a small non-zero value. This factor is a non-dimensional number that adds in a small additional contribution to the diagonal of the Jacobian matrix, each additional diagonal entry being weighted by the characteristic scales of the model, so as to keep the Jacobian dimensionally consistent. Even a tiny perturbation (e.g. $10^{-18}$) can be sufficient to resolve the singular Jacobian issue and permit the analysis to proceed. In fact, the smaller the perturbation, the better: the larger the perturbation, the less closely the Jacobian matrix resembles the physical system it is meant to represent. The implications of this discrepancy depend on the type of analysis being performed:

• Statics and implicit time-domain dynamics: the solver only uses the Jacobian matrix as a guide to improve convergence in these analyses. The results will still be accurate up to the user-specified tolerance, provided that convergence is ultimately achieved. If the magnitude of the Jacobian perturbation factor is too large, then the model may not converge when run.
• Explicit time-domain dynamics: the Jacobian perturbation factor has no direct effect on these analyses. However, it can alter the calculation of OrcaFlex's recommended time-step, which can affect the model if it is used in the subsequent analysis.
• Frequency domain and modal analyses: the results from these analyses are directly dependent on the Jacobian matrix. This means that even a small perturbation will change the outcome of the analysis and extreme caution is required. It is recommended to keep the perturbation as small as possible, perhaps by conducting a sensitivity analysis.