Notation and conventions

This page fixes the notation used throughout the documentation. It is deliberately short: every symbol that is not listed here is redefined on the page where it appears.

Tensor order is carried by the typeface

The convention is that of the Echoes manual, so that formulas can be compared side by side with it.

Object	Typeset as	Example
scalar	italic	, , , , ,
vector (order 1)	underlined	, ,
tensor of order 2	bold	, , , ,
tensor of order 4	blackboard bold	, , , ,
set, geometry, shape function	calligraphic	, , ,

One class of object is deliberately outside that table: the column arrays and matrices of an algebraic formalism, which are not tensors and carry no tensor order — the two-component state vector   and the transfer matrices , of the layered sphere, or the column of phase fractions and the column of ones of the differential scheme. They are typeset in upright bold, with the identity matrix of the corresponding size, and each page states the size and the entries.

The single most useful thing to remember: an underline is a vector, bold is order 2, blackboard bold is order 4. This is what makes an expression such as

readable at a glance: an order-4 tensor is built from an order-2 tensor and a unit vector .

Operators

Operator	Meaning
,	simple contraction (one index)
,	double contraction (two indices)
	tensor product
	symmetrized tensor product (order 4, both symmetries)
	symmetrized box product
	transpose
	jump across an interface,
	volume average over
	surface element in the parametrization

Elasticity and transport: one set of formulas

Hooke's law carries no minus sign; Fourier's and Fick's do. That single asymmetry —    against     — is the only reason order-2 and order-4 mean-field formulas ever look as though they disagreed on a sign. The documentation and the code remove it by taking as the stress analog minus the flux:

This is not bookkeeping. Take a surface of outward normal :

• in mechanics,   is the traction — the force the material outside exerts on the material inside;

• in conduction,   is the flux entering the domain — what the outside delivers to the inside.

With   , the quantity   is, in both theories, what the exterior transmits to the interior across that surface. The two objects are the same physical thing, and the analogy is structural rather than notational — which is why every formula of this documentation comes out identical, symbol for symbol:

elasticity (order 4)	transport (order 2)
, , ,	, , ,

Two consequences worth keeping in mind while reading the code:

• the localization tensors named flux_gradient_loc, flux_flux_loc, gradient_flux_loc carry   , not . The names are kept for continuity with their elastic twins; the sign is the one stated here.

• a conductivity and a stiffness are then interchangeable in every scheme, which is exactly why one implementation serves both physics.

The Green operator maps a polarization onto minus the field

The second convention that must be fixed once is the sign of the Green operator, since two incompatible ones are current in the literature. This documentation follows [3]:

The leading minus makes the Fourier symbol of positive semi-definite and its interior average plus the Hill tensor,   , so the one-inclusion case is the     used on every page of this section. Interaction tensors develops the consequences and names the references that use the opposite sign.

Isotropic and transversely isotropic bases

Any isotropic order-4 tensor is a combination of the spherical and deviatoric projectors, with the order-4 identity:

A transversely isotropic order-4 tensor needs five coefficients. The documentation uses the Walpole basis , in which a major-symmetric tensor has and sharing a single coefficient — hence five independent numbers written , with no :

This is the storage used by TensND.TensTI{4} and by hill_tensor on a transversely isotropic matrix ([4], [5]).

Ellipsoid geometry

An ellipsoid is described by an invertible order-2 shape tensor such that   is symmetric positive definite, with eigenvalues the squared semi-axes:

Semi-axes are ordered      , with the orthonormal eigenvectors. Two aspect ratios recur:

•   — in-plane aspect ratio (of a crack, in particular);

• — the flatness , or the axial-to-transverse ratio of a spheroid, depending on the page. It is always redefined locally, because the two usages differ.

The figure below is drawn from an actual Ellipsoid instance, so the guides are the stored in the stored frame — the same ones every closed form on the following pages is written in. Semi-axes  , hence   and  .

plotly_scene(shape_traces(Ellipsoid(3.0, 1.5, 0.8)); uid = "notation-ellipsoid",
    height = 430, title = "Semi-axes a ≥ b ≥ c and the principal frame")

Storage: Kelvin–Mandel

Order-2 and order-4 tensors are stored in the Kelvin–Mandel convention (orthonormal 6-dimensional basis, off-diagonal components carrying and factors), not in the engineering Voigt convention. This makes a double contraction an ordinary matrix product and a tensor inverse an ordinary matrix inverse. The practical consequences when reading printed components are spelled out in A storage convention worth knowing.

denotes the   Kelvin–Mandel matrix of an order-4 tensor, and the same matrix expressed in the ellipsoid's principal frame.

Two rules this documentation follows

Every symbol is defined where it is used. A page never relies on a symbol introduced only on another page, even at the cost of repeating a definition.

No formula without a traceable source

Every expression in this documentation is either (i) accompanied by a citation to published work, or (ii) derived explicitly on the page from expressions that are. Where a convention differs between references — the crack opening displacement tensor is the notable case, see Crack opening displacement — the competing conventions are named and the one implemented by MeanFieldHomogenization is stated.