Theory — reading path

What the package covers

• Bases — canonical, rotated, orthogonal or fully general, with covariant and contravariant components and the metric that relates them.

• Tensor algebra — , , , , and contractions of one, two or four indices.

• Structured types — TensISO, TensTI, TensCubic and TensOrtho store 2, 5, 3 and 9 scalars and compute products and inverses in closed form, one to three orders of magnitude faster than the dense route.

• Symmetry projection — the closest isotropic, transversely isotropic or orthotropic tensor, with the orientation given or optimized.

• Differential operators in curvilinear coordinates, symbolically or by automatic differentiation, plus embedded surfaces.

• One generic implementation for Float64, ForwardDiff.Dual, SymPy.Sym and Symbolics.Num.

The design is inspired by the Maple library Tens3d of Jean Garrigues.

TensND does two things: it represents tensors of arbitrary order and dimension on arbitrary bases, and it differentiates tensor fields on arbitrary coordinate charts. This section states the mathematics behind both, in the order in which it is built. Every page is self-contained on notation (Notation and conventions), and every formula is either cited, derived on the page, or read off the implementation with the source file named.

The two pillars

Algebra. What a tensor is on a general basis, how the products work, how minor-symmetric tensors are stored as   matrices, what the symmetry classes are, and how to project an arbitrary tensor onto one of them.

Analysis. How a basis that varies from point to point produces Christoffel symbols and the five differential operators, and what changes when the chart describes an embedded surface rather than the whole space.

Page by page

Page	What it adds
Notation and conventions	typefaces, index conventions, the dictionary from symbol to Julia operator, and the pair-wise double-contraction convention
Tensor algebra	, , , , the contractions, and the identities that make closed-form products possible
Bases and variance	dual basis, metric, covariant/contravariant components, and the basis-type hierarchy that fixes the cost of everything else
Kelvin–Mandel representation	the isometry onto   matrices, and why its rotation matrix being orthogonal is the whole point
Rotations and Euler angles	the Z–Y–Z convention as implemented,  , and the degeneracies of any three-angle parametrization
Isotropic tensors	, , the algebra, isotropization, and why it does not commute with inversion
The Walpole basis	the six , the multiplication table, the synthetic   triplet, and the of
The extended Walpole algebra	why the axially invariant space is eight-dimensional, and what a five-parameter description silently discards
TI parametrizations	components, engineering constants, Hoenig ratios — three conventions, one class
Orthotropy	nine constants, the block-diagonal matrix, and why a product of two orthotropic tensors needs twelve
Projection onto a symmetry class	normal equations, the condensed objective, the orientation search, and the difference between projecting and averaging
Curvilinear differential calculus	natural basis, Lamé coefficients, Christoffel symbols, the five operators and their index placement
Submanifolds	first and second fundamental forms, Gauss–Weingarten, curvatures

Relation to the Echoes manual

The algebraic half of this section is aligned on the appendix of the Echoes manual: same conventions, same Walpole basis, same Kelvin–Mandel ordering, overlapping bibliography, so that expressions can be compared side by side.

Three families of difference are worth knowing in advance.

Present here, absent there. The Echoes manual works exclusively in an orthonormal Cartesian frame and states outright that variance is unnecessary there. Consequently Bases and variance, Curvilinear differential calculus and Submanifolds have no counterpart in it and are derived from scratch here. So is The extended Walpole algebra, which as far as we are aware appears in no standard reference.

Generality. TensND is not restricted to dimension 3, nor to minor-symmetric order-4 tensors, nor to Float64: the same code runs on Sym, Num and ForwardDiff.Dual. Where a statement holds only in 3-D, it says so.

Conventions that genuinely differ. Two are worth flagging because they are easy to trip over:

• the spherical coordinates are ordered , not , so that    reproduces the canonical basis in the canonical order (Curvilinear differential calculus);

• the gradient appends the derivative index on the right, and the divergence contracts the last index — a library using the opposite convention differs by a transpose (Curvilinear differential calculus).

Finally, one claim circulating about the Walpole basis is simply false and is corrected here: is not , and is not  . The correct identities are on The Walpole basis and are pinned by tests.

Reading path

Section	For
Theory	the mathematics the library implements, stated once and cited
Manual	how to call it, task by task
Tutorials	runnable scripts, each also a notebook
Developer	the source layout, and how to extend it
API	every exported name, grouped by theme

Newcomers should start with Getting started, then the tutorial Bases, variance and the metric — variance is the one notion a Cartesian-only tensor library does without, and everything else rests on it.