Caveats

In the following, we sketch some caveats and limitations of the package that may be useful to be aware of.

Simplicity

The Hamiltonian or Lagrangian should be provided in a form as simple as possible to aid the symbolic algebra system. Many expressions lead to involved symbolic expressions that can be hard to differentiate and lead to errors in the code generation pipeline.

For example, scalar products should be specified as x ⋅ x and not as x' * x. As the transposition also entails complex conjugation, the resulting symbolic expression is substantially more complicated, which can cause problems down the line.

Another potential problem is an array operation, like the dot product, that is preceded by scalar multiplication like in α * x ⋅ x. This can cause problems due to the order of operations, which is (α * x) ⋅ x, where first x is rescaled by α, implying the creation of a temporary array holding the result, which is then contracted with x. This should rather be expressed as x ⋅ x * α or α * (x ⋅ x), where the scalar product is computed first and then the result, which now is just a scalar, is multiplied by α.

Parameters

The handling of parameters requires some massaging of the code generated by Symbolics.jl. To facilitate this, symbolic parameters get ₚ attached to their names.

Initial Guesses

For some problems, in particular regular Lagrangian systems, it is in general not straightforward to automatically compute a first-order system of equations to be used as an initial guess for x in GeometricIntegrators. To circumvent this issue, it is possible to manually specify a function that computes the vector field ẋ to the LODE and LODEProblem constructors via the v̄ keyword. It is also possible to provide a vector field for the initial guess of p via the f̄ keyword, although this is usually not necessary as ṗ can be derived automatically. The same keyword arguments exist for the respective constructors of degenerate Lagrangian systems, although also here the vector fields are provided by default.