iTensor System Architecture

Technical overview of the computational stack that powers symbolic and numerical tensor calculations

Core Components

iTensor consists of three principal components arranged in a layered architecture. Each layer is designed for a specific class of tensor operations required in general relativity and differential geometry.

Primary System Components

Symbolic Engine (Python): SymPy-based tensor algebra system for exact, analytical calculations with full step-by-step derivations
Numerical Library (Python/C++): Optimized tensor array operations built on NumPy with C++ extensions for high-performance calculations
C++ Visualization Core: CUDA-accelerated raytracing engine for relativistic optics in curved spacetime
Python API Layer: Unified interface exposing all capabilities with automatically generated documentation
Optional Web Interface: Lightweight access for users without local installation

Computational Flow Diagram

The diagram below illustrates how a typical computation flows through the system layers:

┌────────────────────────────┐      ┌────────────────────────────────┐
│                            │      │                                │
│ User Input (Metric Tensor) │──┬──►│     Symbolic Processing        │
│                            │  │   │   (Algebraic calculations)     │
└────────────────────────────┘  │   │                                │
                                │   └───────────────┬────────────────┘
                                │                   │
                                │                   ▼
                                │   ┌────────────────────────────────┐
                                │   │                                │
                                └──►│     Numerical Processing       │
                                    │  (Concrete value computation)  │
                                    │                                │
                                    └───────────────┬────────────────┘
                                                    │
                 ┌───────────────────────┐         │
                 │                       │         │
                 │ Visualization Engine  │◄────────┘
                 │                       │
                 └───────────────────────┘

Symbolic Engine Architecture

The symbolic engine handles all exact tensor operations for derivation and mathematical proof. It forms the foundation of iTensor's ability to manipulate expressions containing variables like coordinates or metric parameters.

Technical Implementation

Core Class: SymbolicTensor class with support for rank-N tensors in arbitrary coordinates
Symbolic Framework: Built on SymPy with custom tensor simplification algorithms
Coordinate Handling: Representation of covariant and contravariant indices with automatic handling of metric contractions
Tensor Algebra: Implementation of key operations:
- Tensor addition, multiplication, and contraction
- Covariant differentiation with metric connection
- Lie derivatives and parallel transport
- Algebraic tensor symmetry operations
Physics Functionality: Specialized objects for common tensors:
- Metric, connection, and curvature tensors
- Maxwell tensor and stress-energy tensors
- Killing vectors and geodesic equations

# Example symbolic engine code fragment from itensorpy.symbolic import Metric # Define Schwarzschild metric with symbolic mass parameter M = symbols('M') schwarzschild = Metric.schwarzschild(mass=M) # Calculate Christoffel symbols with full derivation steps christoffel = schwarzschild.compute_christoffel_symbols(show_steps=True) # Calculate Riemann tensor riemann = schwarzschild.compute_riemann_tensor() print(riemann.display_components())

Numerical Engine Architecture

The numerical engine processes tensor calculations with concrete numerical values, enabling simulation, visualization, and practical application of tensor physics.

Implementation Features

Array Storage

Multi-dimensional NumPy arrays with index mapping optimized for sparse tensors. Efficient memory layout for both dense and sparse tensors with configurable precision (32/64-bit).

Computational Optimizations

Vectorized operations with SIMD parallelism, OpenMP thread parallelism for grid calculations, and BLAS/LAPACK acceleration for linear algebra operations.

C++ Extensions

Critical path calculations implemented in C++ with Python bindings for tensor contractions, einsum operations, and integration of tensor ODEs/PDEs.

GPU Acceleration

Optional CUDA kernels for large tensor calculations and field evaluations across spacetime grids, with automatic fallback to CPU implementation when CUDA is unavailable.

# Example of numerical tensor processing from itensorpy.numerical import NumericalMetric import numpy as np # Create numerical Schwarzschild metric at specific points r_values = np.linspace(2.1, 20.0, 100) # From just outside event horizon metric_values = NumericalMetric.schwarzschild(r_values, M=1.0) # Calculate Ricci scalar at each point ricci_values = metric_values.compute_ricci_scalar() # Output should be ~0 (vacuum solution) print(f"Max absolute Ricci scalar: {np.max(np.abs(ricci_values))}")

Differential Geometry Module

The differential geometry module implements computational methods for:

Automatic calculation of connection coefficients (Christoffel symbols) from metric tensors
Parallel transport along curves with configurable integration methods
Geodesic equation solvers with adaptive step size control
Calculation of curvature invariants (scalar curvature, Kretschmann scalar)
Evaluation of Einstein tensor for non-vacuum spacetimes
Tetrad-based calculations for observer-dependent quantities

Visualization Core

The visualization core is a specialized C++ engine for ray-tracing in curved spacetime. It numerically solves the geodesic equation for light rays to generate physically accurate renderings of black holes and other relativistic objects.

Technical Components

Ray Tracing System

High-precision geodesic integration using adaptive Runge-Kutta methods
Parallelized ray casting with configurable camera models
Physically correct rendering of:
- Gravitational lensing of background stars
- Relativistic Doppler and gravitational redshift effects
- Accretion disk dynamics with thermal emission model
- Realistic light transport with polarization effects
Support for various black hole metrics:
- Schwarzschild (non-rotating)
- Kerr (rotating)
- Reissner-Nordström (charged)
- Kerr-Newman (rotating and charged)

# Python interface to the C++ visualization core from itensorpy.visualization import BlackHoleRenderer # Configure a Kerr black hole with spin parameter a=0.9M renderer = BlackHoleRenderer( metric_type="kerr", mass=1.0, spin=0.9, resolution=(1024, 1024), field_of_view=20.0, # degrees observer_distance=50.0, # M units observer_inclination=80.0 # degrees from spin axis ) # Configure accretion disk model renderer.set_accretion_disk( inner_radius=2.0, # ISCO for this spin outer_radius=20.0, temperature_profile="novikov-thorne" ) # Render image with CUDA acceleration if available image = renderer.render(use_gpu=True) image.save("kerr_black_hole.png")

API Design

The Python API unifies all system components into a coherent interface with consistent method naming and parameter conventions.

API Design Principles

Type Consistency: All tensor objects follow the same interface regardless of whether they are symbolic or numerical
Physics-First Naming: Methods and parameters named according to standard physics notation rather than programming conventions
Chainable Operations: Tensor methods return new tensor objects allowing method chaining
Comprehensive Error Messages: Physics-specific error messages that explain not just what went wrong but why it fails mathematically
Performance Transparency: Clear indication of computational complexity for operations on large tensors

# Example demonstrating unified API for symbolic and numerical operations from itensorpy import Metric # Create symbolic metric symbolic_metric = Metric.friedmann_lemaitre_robertson_walker(symbolic=True) symbolic_einstein = symbolic_metric.compute_einstein_tensor() # Create numerical metric with specific scale factor values import numpy as np a_values = np.linspace(0.1, 2.0, 100) # Scale factor numerical_metrics = [Metric.friedmann_lemaitre_robertson_walker(a=a) for a in a_values] numerical_einsteins = [m.compute_einstein_tensor() for m in numerical_metrics] # Both approaches use identical method names despite different internal implementations

Extensibility

iTensor is designed for extensibility in several key areas:

Custom Metrics

Define your own metric tensors either through direct component specification or as perturbations of known solutions. All tensor operations will automatically work with custom metrics.

Coordinate Systems

Implement additional coordinate systems beyond the built-in spherical, cylindrical, and cartesian systems. The framework automatically handles coordinate transformations and tensor component mapping.

Field Equations

Add custom field equation solvers for modified gravity theories or alternative formulations of general relativity. The solver architecture supports arbitrary tensor differential equations.

Visualization Plugins

Extend the visualization system with custom renderers for specialized physics or alternative rendering techniques, with hooks provided for custom shader inclusion.

For detailed information on extending iTensor, see the Extension Guide which covers plugin architecture and the relevant APIs.

Previous: Installation Next: Symbolic Tensors