TensorAtlas

TensorAtlas is a SymPy-backed Python package for symbolic tensor algebra, coordinate geometry, differential forms, curvature calculations, tensor-valued forms, and orthogonal-metric geometric algebra. Conventions are explicit, objects expose summaries and validation helpers, and expensive symbolic simplification can be controlled.

Author: Bhuvanesh Bhatt (bhuvaneshbhatt@gmail.com) License: GNU General Public License v3.0 only (GPL-3.0-only)

Highlights

• Coordinate charts, coordinate maps, scalar/vector/covector/tensor fields, and coordinate-field transformations.
• Vector-calculus helpers for gradients, divergence, curl, Hessians, and Laplacians in coordinate bases.
• Symbolic tensor arrays with tensor products, contractions, transposes, summaries, validation, and SymPy array bridges.
• Differential forms, frames, coframes, Hodge-oriented workflows, and tensor-valued forms for Cartan-style geometry.
• Relativity utilities for metric catalogs, Christoffel symbols, Riemann/Ricci/scalar/Einstein curvature, geodesic equations, selected components, and nonzero-component inspection.
• Abstract and indexed tensor canonicalization with dummy-index normalization and identity-oriented reduction utilities.
• Orthogonal-metric multivector geometric algebra with geometric, exterior, inner, and contraction products, involutions, duals, reflections, and rotor helpers.
• Algebraic tensor geometry with Segre/Veronese/secant parameterizations, flattening rank certificates, CP/Waring decomposition, and generic identifiability criteria.
• A large tutorial notebook plus tested example modules and runnable scripts.

Installation for development

From the repository root:

python -m pip install -e ".[dev,plot,docs]"
python -m pytest
python tools/release_audit.py
python examples/five_minute_tour.py

The base runtime dependency is SymPy. Plotting examples use the optional plot dependencies.

Quick examples

Curvature of the two-sphere

from tensoratlas.relativity import scalar_curvature, two_sphere_metric

sphere = two_sphere_metric()
print(scalar_curvature(sphere))

Expected output:

2/R**2

Coordinate-field transformation

import sympy as sp
from tensoratlas.core import catalog_transition_map, transform_scalar_field

x, y = sp.symbols("x y", real=True)
cart_to_polar = catalog_transition_map("cartesian2", "polar")
print(cart_to_polar.summary())
print(transform_scalar_field(x**2 + y**2, cart_to_polar))

Tensor products and contractions

from tensoratlas.core import tensor_contract, tensor_product

A = ((1, 2), (3, 4))
B = ((0, 5), (6, 7))
product = tensor_product(A, B)
contracted = tensor_contract(product, (1, 2))
print(contracted.components)

Orthogonal geometric algebra

from tensoratlas.geometric_algebra import GeometricAlgebra

alg = GeometricAlgebra(3)
e1 = alg.vector("e1")
e2 = alg.vector("e2")
print(e1 * e1)
print(e1.wedge(e2))

Tutorial and examples

The main tutorial is the TensorAtlas demo notebook.

It includes tensor theory background, coordinate workflows, vector calculus, differential forms, electromagnetic forms, tensor-valued forms and Cartan equations, curvature on the two-sphere, Schwarzschild and FLRW examples, abstract tensor canonicalization, geometric algebra, debugging, validation, and performance notes.

Plain Python example scripts are in the examples directory, and tested reusable workflows are in the package examples.

Mathematical conventions

Relativity helpers use mostly-plus Lorentzian signature for built-in spacetime metrics. The Riemann convention is

R^a{}_{bcd} = ∂_c Γ^a{}_{bd} - ∂_d Γ^a{}_{bc}
              + Γ^a{}_{ce} Γ^e{}_{bd} - Γ^a{}_{de} Γ^e{}_{bc}

with Ricci contraction R_bd = R^a{}_{bad} and scalar curvature R = g^{ab} R_ab. Tensor-valued Cartan helpers use

T^a = dθ^a + ω^a{}_b ∧ θ^b
Ω^a{}_b = dω^a{}_b + ω^a{}_c ∧ ω^c{}_b

See the conventions guide for the full convention reference.

Scope and limitations

TensorAtlas focuses on symbolic tensor algebra/analysis. It is not a numerical relativity framework, a plotting library, or a complete replacement for specialized tensor-canonicalization and geometric-algebra systems. The geometric algebra layer currently supports diagonal/orthogonal metrics; non-diagonal Clifford metrics are rejected rather than simplified incorrectly.

Usability and performance notes

Geometric algebra examples usually unpack basis vectors directly:

from tensoratlas.geometric_algebra import GeometricAlgebra

ga = GeometricAlgebra.euclidean(3)
e1, e2, e3 = ga.basis_vectors()
rotor_input = e1.wedge(e2)

Dense helpers such as nonzero_riemann compute a full tensor before filtering. For larger metrics, prefer selected components such as christoffel_component, riemann_component, ricci_component, and einstein_component.

Small benchmark scripts are available under benchmarks/:

python benchmarks/benchmark_import_time.py
python benchmarks/benchmark_relativity.py
python benchmarks/benchmark_geometric_algebra.py
python benchmarks/benchmark_tensor_canonicalization.py

Optional visualization examples

Install the optional plotting dependencies and run:

python examples/visualization_workflow.py

The visualization examples illustrate basis changes, covectors, metrics, tensor products, contractions, forms, pullbacks, curvature, geodesics, continuum-mechanics tensors, quadrupole moments, geometric-algebra rotors, and canonicalization diagrams.

Five-minute tour

A compact public example is available here:

python examples/five_minute_tour.py

It demonstrates coordinate maps, vector-calculus helpers, tensor products and contractions, differential forms, selected curvature calculations, and a small geometric-algebra rotor workflow.

Algebraic tensor geometry

tensoratlas.algebraic provides grouped matrix flattenings, determinantal rank constraints, Segre and Veronese varieties, certified CP-rank bounds, CP decomposition, and symmetric/Waring decomposition (without attaching statistical semantics). Exact matrix and rank-one paths require only SymPy; higher-order numerical ALS is available through the optional decomposition extra. See the algebraic tensor geometry guide.

Stability policy

Stable public interfaces are the documented top-level exports and the curated tensoratlas.api modules. Canonical implementation layers live under tensoratlas.semantics, tensoratlas.normalization, and tensoratlas.realizations; internal modules are not part of the compatibility contract. See the API reference.

Choosing the right layer

Use tensoratlas.api.semantics to declare manifolds, abstract/indexed tensors, chart specifications, forms, spinors, and other mathematical objects without committing to components.

Use tensoratlas.api.normalization for canonicalization, identity reduction, indexed normalization, algebraic simplification, and Fierz or form reductions.

Use tensoratlas.api.realizations for coordinates, frames, component tensors, chart geometry, vector calculus, explicit matrices, and other concrete representations.

Use tensoratlas.api.pipeline when a workflow should move from a semantic declaration through normalization into a realization. Domain packages such as tensoratlas.relativity and tensoratlas.geometric_algebra remain available for focused workflows.

Historical tensoratlas.core component and vector-calculus imports remain available as deprecated compatibility paths, but new examples and application code should use the curated API modules above.

Example limitations

The public examples are designed to be small and inspectable. Dense curvature helpers such as full nonzero-component scans compute large intermediate arrays before filtering, so selected-component APIs are preferable for larger metrics. Visualization examples return Matplotlib figures and the runnable script closes them immediately so release checks do not accumulate open figures.