Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
Named Indices and Metrics
Plain labels indices by integer position and treats every leg the same. For physics on a manifold and for symbolic tensor algebra one needs more: every index should carry a name, a variance (upper or lower), and a dimension, and contractions must respect the geometry encoded by a metric. The subpackage adds exactly that layer in five stages: describes a single index, collects an ordered tuple of them, wraps a numerical tensor with a Shape, attaches a metric for automatic raising and lowering, and exposes a catalog of the standard pseudo-Riemannian geometries. This tutorial works each layer in turn so that by the end one is computing with Schwarzschild and Kerr metrics with the same comfort as adding two matrices.
Needs["Wolfram`TensorNetworks`"]
1. Why Named Indices?
In tensor calculus an index is more than a position. It is a label on a chart of basis vectors. The expression names three indices, declares two of them lower and one upper, and implicitly fixes which basis they live in. None of that survives 's integer-labelled hyperedges: the contraction graph is correct but the indices have no identity beyond their numerical position, and one cannot distinguish a covariant pair from a contravariant pair without external bookkeeping.
ρ
T
μν
The layer fills that gap. The data carrier is a stack: [d, name] holds a size and a label and uses the sign of d for the variance – positive means contravariant (upper), negative means covariant (lower); glues a list of Dimensions in order; marries a tensor to a Shape and validates the match; attaches one or more metrics so that operations across mismatched variance can use the metric automatically; and specialises that wrapping to a rank-two, square, symmetric (or antisymmetric) object – precisely the geometric metric of differential geometry – and adds a curated set of named built-ins.
Two practical pay-offs are worth stating up front. First, every operation that contracts two indices can verify that the indices actually match by name and that their variances are compatible: is allowed but requires a metric to fix the sign mismatch. Second, the same Shape data drives display: an IndexArray prints with its index symbols decorated as bars and underbars to mark variance, making the type of an expression visible at a glance. The remainder of the tutorial walks each layer with worked examples.
μ
v
w
μ
μ
v
μ
w
2. Dimension and Shape
Load the named-index context. The IndexArray context is loaded implicitly by the main paclet but is also exposed for direct use:
Needs["Wolfram`TensorNetworks`IndexArray`"]
Needs["Wolfram`Arrays`"]
A constructed from plain positive integers gives upper indices with default names , , , … drawn from the latin alphabet starting at :
i
j
k
i
 | Shape |
The two equivalent ways to introduce variance are to pass an explicit Dimension list with negative sizes for lower indices, or to use the (size, name) form where a negated name marks the index as lower. Both produce the same Shape:
| Shape |
 | Dimension |
| Dimension |
| Shape |
Property dispatch exposes the underlying data. The most useful keys are "Names" for the symbolic labels, "Dimensions" for the unsigned sizes (this is what on the underlying tensor returns), "Variance" for the per-index Boolean ( = upper), and "Rank" for the number of free indices. Together they recover everything one might want to know about the index structure:
True
s=
[{3,3,4},{"i",-"j","k"}];{s["Names"],s["Dimensions"],s["Variance"],s["Rank"]}
 | Shape |
Shape is the type and not the data: it is purely declarative and contains no tensor entries. Two Shapes compare equal under when their dimensions match (with zero dimensions treated specially), independent of names – handy when threading shapes through transformations that rename indices.
2.3. DimensionQ and ShapeQ
2.3. DimensionQ and ShapeQ
The predicates and are the cheap validity check applied to each component before passing it to a constructor. A bare integer is not a Dimension, and a bare list of integers is not a Shape, even though the constructors will lift them when given the chance:
| DimensionQ |
| Dimension |
| DimensionQ |
| Dimension |
| DimensionQ |
ShapeQ mirrors the pattern at the next level: a fully specified Shape of Dimensions, and a Shape built from raw integers (auto-converted at construction) both pass; a bare list does not.
| ShapeQ |
| Shape |
| Dimension |
| Dimension |
| ShapeQ |
| Shape |
| ShapeQ |
3. The IndexArray Object
An wraps a numerical (or symbolic) tensor together with a Shape that names its axes. There are three ways to construct one. The most explicit takes a tensor and a fully specified Shape; ArrayDimensions on the tensor must match Shape["Dimensions"], and validity is cached at construction:
mat={{1,2,3},{4,5,6},{7,8,9}};ia=
mat,
[{3,3},{"i",-"j"}];{ia["Names"],ia["Variance"],ia["SignedDimensions"]}
| IndexArray |
| Shape |
A shorter variance-only form passes a list of Booleans, one per axis, with for upper indices and for lower. Names are auto-generated. The shortest form supplies only the tensor and lets the wrapper derive everything from :
True
False
ia2=
[mat,{True,False}];ia3=
[mat];{ia2["SignedDimensions"],ia3["Names"],ia3["Dimensions"]}
| IndexArray |
| IndexArray |
Two distinct subscript forms surface the most common manipulations. Part syntax ia[[i, j]] slices, calling under the hood; function-call syntax ia["k", "l"] renames or permutes axes, calling . A negated name in the juggling form lowers (or raises) the index by toggling its sign:
m={{1.0,2.0},{3.0,4.0}};ia=
m,
[{2,2},{"i","j"}];{ia["k","l"]["Names"],ia[-"i","j"]["Variance"],ia〚1,2〛["Tensor"]}
| IndexArray |
| Shape |
Familiar matrix algebra is overloaded to preserve the Shape: swaps both the data and the index list, inverts the data and toggles every index sign (because the inverse of a (1,1) tensor is naturally a (1,1) tensor with the role of rows and columns reversed), and of two IndexArrays succeeds whenever the multisets of (name, dimension) agree, permuting one operand as needed:
{Transpose[ia]["Names"],Transpose[ia]["Tensor"],Inverse[ia]["Tensor"]}
Other useful properties are "Tensor" (the unwrapped array; identical to [ia] for explicit data), "Shape" (the full Shape object), "Symbol" (the rendered glyph used in box form, with bars and underbars to mark variance), and "Symmetry" (the permutation symmetry reported by ).
3.4. IndexArrayQ
3.4. IndexArrayQ
The predicate holds when the argument is an IndexArray expression whose wrapped tensor's dimensions agree with the declared Shape under any recorded assumptions. A bare matrix fails because it is not wrapped, even though every IndexArray constructor would happily accept it:
m=RandomReal[1,{3,3}];ia=
m,
[3,3];
[ia]
[m]
| IndexArray |
| Shape |
| IndexArrayQ |
| IndexArrayQ |
4. IndexTensor and the Metric
An IndexArray knows what its indices are called and how they covary, but it does not yet know how to identify an upper index with its lower partner. That bridge is a metric: a rank-two symmetric (or antisymmetric) IndexArray on indices of equal sign and dimension. The wrapper attaches such a metric to an IndexArray (or declares the IndexArray itself to be a metric). With a metric in place, contractions of mismatched-variance indices succeed by inserting the metric automatically.
To see this concretely, take the Euclidean metric on and form the contraction of two upper-index vectors. Without a metric is geometrically ill-formed (two upper indices cannot contract), but with the metric attached one of them is lowered on the way to the contraction and the inner product comes out as expected:
3
i
u
i
v
g=
["Euclidean"[3]];u=
{1,2,3},
[3,"i"],g["IndexArray"];v=
{4,5,6},
[3,"i"],g["IndexArray"];Activate
[{u,v}]["Tensor"]
| MetricTensor |
| IndexTensor |
| IndexArray |
 | Shape |
| Dimension |
| IndexTensor |
| IndexArray |
| Shape |
| Dimension |
 | IndexContract |
The contraction returns an [] expression so the index structure stays inspectable; one call to evaluates it. For the Euclidean metric the result is the familiar dot product . Switching the metric to (Minkowski) changes the sign of the time component and gives the spacetime norm:
1×4+2×5+3×6=32
diag(-1,1,1,1)
g=
["Minkowski"[4]];u=
{1,0,0,0},
[4,"i"],g["IndexArray"];Activate
[{u,u}]["Tensor"]
| MetricTensor |
| IndexTensor |
| IndexArray |
| Shape |
| Dimension |
| IndexContract |
Lowering an index outside of a contraction is equally direct. Function-call syntax with a negated name swaps the variance flag, and behind the scenes the IndexTensor inserts the metric so that the data is mapped through =:
u
μ
g
μν
ν
u
u=
{2,1,0,0},
[4,"i"],g["IndexArray"];Activate[u[-"i"]["Tensor"]]
| IndexTensor |
| IndexArray |
| Shape |
| Dimension |
The upper four-vector =(2,1,0,0) becomes =(-2,1,0,0) under the Minkowski signature, exactly as expected from =-1. The same machinery is used by whenever a pair of indices sharing a name has mismatched signs: the index whose sign disagrees with the metric's natural form is dressed by the metric (or its inverse), and the contraction proceeds without further user intervention.
μ
u
u
μ
η
00
4.3. IndexTensorQ
4.3. IndexTensorQ
The predicate validates the inner IndexArray and confirms that each attached metric is rank-two with matching dimensions on the indices it covers. An IndexArray on its own does not satisfy the predicate – the metric attachment is what makes the wrapping an IndexTensor:
m=RandomReal[1,{3,3}];ia=
m,
[3,3];metric=
["Euclidean"[3]]["IndexTensor"]["IndexArray"];it=
[ia,metric];
[it]
| IndexArray |
| Shape |
| MetricTensor |
| IndexTensor |
| IndexTensorQ |
5. The MetricTensor Catalog
Substitute Schwarzschild for Minkowski and the diagonal entries of the metric encode the line element
Reading those four coefficients off Diagonal[g["Matrix"]] is the quickest sanity check that the right metric is loaded:
5.5. MetricTensorQ
5.5. MetricTensorQ
6. Array utilities
6.1. ArrayRank
6.1. ArrayRank
6.2. ArrayName
6.2. ArrayName
6.3. ArrayPart
6.3. ArrayPart
6.4. ArrayTranspose
6.4. ArrayTranspose
6.5. ArrayContract
6.5. ArrayContract
6.6. SimplifyArray
6.6. SimplifyArray
6.7. ZeroArrayQ
6.7. ZeroArrayQ