Curvilinear differential calculus

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 [12].

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 for the .

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.

Storage convention

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

The five operators

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

Operator	Definition	Order
GRAD
SYMGRAD
DIV
LAPLACE
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 DIV 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.

Predefined systems

System	Coordinates		Lamé
coorsys_cartesian
coorsys_polar
coorsys_cylindrical
coorsys_spherical
coorsys_spheroidal		prolate spheroidal	see the constructor

Their non-vanishing Christoffel symbols:

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

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 .

Two implementations, one interface

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

	CoorSystemSym	CoorSystemNum
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

CoorSystemNum stores its 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. CoorSystemSym 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.