Curvilinear differential calculus

<!– crosslinks: written by .github/scripts/crosslinks.py from docs/crosslinks.toml; do not edit –>

See also

Manual: Coordinate systems (symbolic) · Coordinate systems (numerical)

Tutorials: Differential operators, symbolically · Christoffel symbols · Differential operators, numerically · Classical identities of the differential operators

<!– /crosslinks –>

The second pillar of the library, and the second chapter with no counterpart in the Echoes manual, which works only in Cartesian coordinates. Everything below is derived from the definitions and matches src/coorsystems.jl (symbolic) and src/coorsystems_num.jl (automatic differentiation). A classical treatment of the underlying tensor analysis is Simmonds (1994).

Chart, natural basis, metric

A coordinate system is a map from a chart onto . Its natural basis is the coordinate frame

with the dual basis and the metric    of Bases and variance. Everything on that page applies here verbatim; a coordinate system is a basis that varies from point to point.

Lamé coefficients and the normalized basis

The natural vectors are generally neither unit nor orthogonal. Their norms are the Lamé coefficients

and is the normalized basis — the frame in which physical components are read. For an orthogonal system the metric is  , the dual vectors are  , and the line element is

TensND stores both bases: natural_basis and normalized_basis, with natvec and unitvec for individual vectors and lame_coefficients for the .

Predefined systems

System	Coordinates		Lamé
coorsys_cartesian
coorsys_polar
coorsys_cylindrical
coorsys_spherical
coorsys_spheroidal

with, for the prolate spheroidal system,  ,   and half the distance between its two foci. All five are orthogonal, so each normalized basis is orthonormal; its vectors are named after their coordinate, , , … — for an orthonormal basis the dual basis is the basis itself, and the position of the label carries no meaning.

The spherical coordinates are ordered (\theta,\varphi,r)

Not . The ordering is chosen so that    reproduces the canonical basis in the canonical order, which makes the spherical frame a genuine RotatedBasis — see Rotations — and lets spherical results be compared with Euler-angle results without a permutation. The same ordering applies to init_spherical and to .

The figures below draw each curvilinear system at a point set by the sliders: the canonical basis at the origin , the normalized basis at , the angles and lengths that locate , and, when the box is ticked, the lines (in 2-D) or surfaces (in 3-D) on which one coordinate is constant. Each coordinate keeps one color throughout. Since   is the gradient of , the unit vector of a coordinate is normal to the surface on which that coordinate is constant, and both are drawn in its color. A 3-D figure turns with the mouse.

Polar coordinates

With   and taken on any interval of length (the slider of the figure runs from to ):

Cylindrical coordinates

The polar pair in the plane  , completed by the axial direction: and as above, and  . The surfaces of constant coordinate are the cylinders of axis (), the half-planes bounded by that axis () and the planes normal to it ().

Spherical coordinates

With  , the colatitude   measured from and the azimuth measured from :

In this order the triad is the image of the canonical basis by the rotation of Rotations and Euler angles. The surfaces of constant coordinate are the cones of axis and apex (), the half-planes bounded by that axis () and the spheres of center ().

Spheroidal coordinates, prolate and oblate

coorsys_spheroidal is the prolate system of the table. With    and  , its surfaces of constant coordinate all share the foci  .   is the prolate spheroid

  the sheet, on the side  , of the hyperboloid of two sheets

and   a half-plane bounded by the axis. The normalized basis, ordered as the coordinates, is

Far from the foci, as  ,   tends to the radius and to : the spheroids and hyperboloids become the spheres and cones of the spherical system.

The oblate system revolves the same confocal ellipses and hyperbolas of a meridian plane about their minor axis instead of their major one:

Its foci form the circle of radius in the plane  .   is the oblate spheroid

  the half, on the side  , of the hyperboloid of one sheet

and the Lamé coefficients and the normalized basis are those of the prolate system with replaced by and by . TensND does not predefine this system: the figure draws it for comparison. Its buttons switch between the two systems, and a fourth slider sets , the unit vectors of the canonical basis giving the scale.

Christoffel symbols

The natural basis varies, and the rate at which it does is the connection:

They are symmetric in because  . The covariant derivative of a vector field follows,

and it is the terms — not the partial derivatives — that make a divergence in spherical coordinates differ from a sum of derivatives.

For the predefined systems, the non-vanishing ones are

All Christoffel symbols of the Cartesian system vanish, which is the definition of a Cartesian chart.

Storage convention

christoffel returns a    array indexed  : the contravariant index is last. The same convention is used by the Γ_func closure of the pointwise CoordinateSystem.

The five operators

TensND defines the differential operators intrinsically, as sums over the chart directions:

Operator	Definition	Order
grad
symgrad
divergence
laplacian
hess

Here is the full derivative of the tensor field, basis included — which is where the Christoffel symbols enter.

Index placement is a convention, and this is the one

is appended on the right, so for a vector field

and divergence contracts the last index,

A library using the opposite convention differs by a transpose. The choice here is what makes    correct as written. For a symmetric field the distinction is immaterial; for a general order-2 field it is not, and it is pinned by a test (Testing and conventions).

Note also that symgrad is a primitive, not (grad + transpose)/2 — applied to a displacement field it is directly the linearized strain tensor.

Two implementations, one interface

The operators have the same names and meaning whether the derivatives are taken symbolically or by automatic differentiation.

	CoordinateSystem	the pointwise CoordinateSystem
derivatives	SymPy / Symbolics, exact	ForwardDiff, machine precision
stores	, bases, , as expressions	, , as closures, evaluated pointwise
result	a formula, valid everywhere	a number, at one point
cost	grows with expression size	constant per point
needs	a symbolic	any differentiable OM(x)
best for	deriving and simplifying closed forms	evaluating fields, sweeps, gradients

A PointwiseGeometry stores the geometry as three closures — χ_func (Lamé), R_func (the rotation to the normalized frame) and Γ_func (Christoffel, with the   convention) — so a custom system needs only a differentiable position map, with no symbolic setup at all.

Because everything downstream is generic in the element type, ForwardDiff.Dual numbers flow through the operators in both directions: an operator result can be differentiated again with respect to the evaluation point, and with respect to a parameter carried by the field itself. The internal buffers promote the element type of the geometry (the Lamé coefficients) with that of the field value, so a Dual-valued field evaluated on a Float64 coordinate system is handled correctly.

Simplification machinery

Non-trivial symbolic charts — the spheroidal one is the standard example — produce metric expressions that SymPy will not reduce on its own. The exact CoordinateSystem therefore accepts:

Argument	Role
tmp_coords	auxiliary variables standing for compound expressions
params	constants appearing in
rules	rewrite rules applied after each simplification
tmp_var	substitutions replacing expressions by temporary variables
to_coords	how to eliminate the temporaries before differentiating

Without them the Christoffel symbols of a spheroidal chart are computable in principle and unusable in practice. Their use is shown in Christoffel symbols among the tutorials.