Metadata-Version: 2.4
Name: tensoratlas
Version: 0.2.0
Summary: SymPy-backed symbolic tensor algebra, coordinate geometry, forms, relativity, and geometric algebra.
Author: Bhuvanesh Bhatt (bhuvaneshbhatt@gmail.com)
License-Expression: GPL-3.0-only
Keywords: sympy,tensor algebra,differential geometry,relativity,geometric algebra
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sympy>=1.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Requires-Dist: numpy>=1.26; extra == "plot"
Provides-Extra: decomposition
Requires-Dist: numpy>=1.26; extra == "decomposition"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Requires-Dist: pytest-timeout>=2; extra == "test"
Requires-Dist: hypothesis>=6; extra == "test"
Requires-Dist: matplotlib>=3.8; extra == "test"
Requires-Dist: numpy>=1.26; extra == "test"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6; extra == "release"
Dynamic: license-file

# 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:

```bash
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

```python
from tensoratlas.relativity import scalar_curvature, two_sphere_metric

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

Expected output:

```text
2/R**2
```

### Coordinate-field transformation

```python
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

```python
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

```python
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](https://github.com/BhuvaneshBhatt/tensoratlas/blob/main/notebooks/tensoratlas_demo.ipynb).

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](https://github.com/BhuvaneshBhatt/tensoratlas/tree/main/examples), and tested reusable workflows are in the [package examples](https://github.com/BhuvaneshBhatt/tensoratlas/tree/main/src/tensoratlas/examples).

## Mathematical conventions

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

```text
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

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

See the [conventions guide](https://github.com/BhuvaneshBhatt/tensoratlas/blob/main/docs/conventions.md) 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:

```python
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/`:

```bash
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:

```bash
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:

```bash
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](https://github.com/BhuvaneshBhatt/tensoratlas/blob/main/docs/algebraic_tensor_geometry.md).

## 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](https://github.com/BhuvaneshBhatt/tensoratlas/blob/main/docs/api_reference.md).

## 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.
