Back to Documentation Home

Tensor Field Visualization

Visualizing tensor fields, geodesics, and curvature in general relativity and differential geometry

Visualizing Tensor Components

iTensor provides several techniques for visualizing tensor components and their derivatives across spacetime. These visualization methods help researchers analyze field behavior and identify important structures in curved spacetime.

from itensorpy.visualization import TensorFieldPlot import numpy as np # Create a simple gravitational wave metric perturbation x = np.linspace(-10, 10, 100) y = np.linspace(-10, 10, 100) t = 0.0 # Fixed time slice # Compute metric perturbation h_xx = h_plus * cos(omega*t - k*z) h_plus = 0.01 # Small amplitude omega = 1.0 k = 1.0 X, Y = np.meshgrid(x, y) h_xx = h_plus * np.cos(omega*t - k*Y) h_yy = -h_plus * np.cos(omega*t - k*Y) # Opposite sign for + polarization # Plot the h_xx component plot = TensorFieldPlot() plot.contour(X, Y, h_xx, title="h_xx Component of Gravitational Wave", xlabel="x", ylabel="y", colorbar_label="h_xx") plot.save("gravitational_wave_hxx.png") # Plot the principal directions (eigenvectors) plot.vector_field(X, Y, h_xx, h_yy, title="Principal Directions of Gravitational Wave Strain", scale=2.0) plot.save("gravitational_wave_directions.png")

Component Visualizations

  • Heatmaps: Color-coded visualization of tensor component magnitudes across a domain
  • Contour Plots: Isolines showing regions of equal component values
  • 3D Surface Plots: Height-mapped representation of tensor components
  • Vector Fields: Direction and magnitude representation for vector and covector fields

Tensor Invariants

  • Scalar Curvature: Visualization of the Ricci scalar across spacetime
  • Kretschmann Scalar: RabcdRabcd for identifying curvature singularities
  • Principal Directions: Eigenvectors of tensors such as the extrinsic curvature
  • Eigenvalue Maps: Visualization of tensor eigenvalues

Geodesic Visualization

Geodesics are central to understanding motion in curved spacetime. iTensor provides tools for visualizing both null (light) and timelike (massive particle) geodesics.

from itensorpy.numerical import GeodesicSolver from itensorpy.visualization import GeodesicPlot import numpy as np # Create a Schwarzschild spacetime solver solver = GeodesicSolver.schwarzschild(M=1.0) # Set up different impact parameters for photon geodesics impact_parameters = [3.0, 5.0, 7.0, 10.0, 15.0] colors = ['r', 'g', 'b', 'c', 'm'] geodesics = [] # Initial position at r=50M (far from black hole), θ=π/2 (equatorial plane) r0 = 50.0 theta0 = np.pi/2 # Solve for each impact parameter for b in impact_parameters: # Initial conditions (energy normalized to 1 at infinity) initial_conditions = { 't': 0.0, 'r': r0, 'theta': theta0, 'phi': 0.0, 'dt_dlambda': 1.0, 'dr_dlambda': -np.sqrt(1.0 - (b/r0)**2), 'dtheta_dlambda': 0.0, 'dphi_dlambda': b/r0**2 } # Solve the geodesic equations solution = solver.solve( initial_conditions=initial_conditions, lambda_span=[0, 150], events=[solver.event_horizon_crossing], dense_output=True ) geodesics.append(solution) # Create the visualization plot = GeodesicPlot() # Add horizon and photon sphere plot.add_schwarzschild_features(M=1.0) # Add each geodesic to the plot for i, (solution, b) in enumerate(zip(geodesics, impact_parameters)): plot.add_geodesic(solution, label=f"b={b}M", color=colors[i]) # Customize and display plot.set_title("Light Deflection in Schwarzschild Spacetime") plot.set_limits([-30, 30], [-30, 30]) plot.add_legend() plot.save("schwarzschild_light_deflection.png")

Mathematical Foundation

The geodesic equation governs the motion of particles in curved spacetime:

d²xμ/dλ² + Γμνρ(dxν/dλ)(dxρ/dλ) = 0

where xμ(λ) is the particle's worldline, λ is an affine parameter, and Γμνρ are the Christoffel symbols.

Visualization Techniques for Geodesics

Trajectory Visualization

  • Path Tracing: Visualize the spatial path of geodesics
  • Proper Time Markers: Indicate constant proper time intervals along timelike geodesics
  • Coordinate Grid Intersections: Show where geodesics cross coordinate surfaces
  • Four-Velocity Components: Visualize the components of the four-velocity along geodesics

Physical Effects

  • Gravitational Redshift: Color-coding geodesics by frequency shift
  • Optical Appearance: How objects appear when viewed along null geodesics
  • Gravitational Lensing: Multiple image formation and magnification effects
  • Frame Dragging: Visualization of Lense-Thirring effect in Kerr spacetime

Curvature Visualization

Visualizing spacetime curvature is essential for understanding gravitational effects. iTensor provides several approaches to visualize the Riemann tensor and its contractions.

from itensorpy.numerical import NumericalMetric from itensorpy.visualization import CurvatureVisualizer import numpy as np # Create a grid for Schwarzschild spacetime r_values = np.linspace(2.1, 20.0, 100) # Start outside horizon theta_values = np.linspace(0, np.pi, 50) # Create the numerical metric schwarzschild = NumericalMetric.schwarzschild( r_values=r_values, theta_values=theta_values, M=1.0 ) # Calculate curvature quantities kretschmann = schwarzschild.compute_kretschmann_scalar() ricci_scalar = schwarzschild.compute_scalar_curvature() # Create visualizer vis = CurvatureVisualizer(schwarzschild) # Generate a heatmap of the Kretschmann scalar vis.scalar_heatmap( kretschmann, coordinates=('r', 'theta'), log_scale=True, title="Kretschmann Scalar in Schwarzschild Spacetime", cmap='inferno' ) # Create a 3D visualization of spacetime embedding vis.embedding_diagram( r_range=[2.1, 15.0], phi_range=[0, 2*np.pi], title="Embedding Diagram for Schwarzschild Spacetime", n_points=100 ) # Visualize tidal forces using the Riemann tensor vis.tidal_force_indicators( r_slice=10.0, # Fixed radius theta_range=[0, np.pi], phi_range=[0, 2*np.pi], scale=2.0, title="Tidal Force Indicators at r=10M" )

Advanced Curvature Visualization

Spacetime Embedding

Visualizing the intrinsic curvature of space by embedding a 2D slice into a higher-dimensional Euclidean space, preserving the metric relationships.

Curvature Invariants

Scalar quantities derived from the Riemann tensor that are independent of coordinate choices, including the Kretschmann scalar, Chern-Pontryagin scalar, and Euler scalar.

Tidal Force Visualization

Ellipsoid representations showing how initially spherical objects are distorted by spacetime curvature, directly visualizing the physical effects of the Riemann tensor.

Petrov Classification Visualization

The Petrov classification characterizes the algebraic symmetries of the Weyl tensor, providing insight into the gravitational field's structure. iTensor can visualize the classification across spacetime, showing transitions between different Petrov types.

Coordinate System Visualization

Different coordinate systems can provide clearer insights into various aspects of curved spacetime. iTensor supports visualization of multiple coordinate systems and transformations between them.

from itensorpy.visualization import CoordinateVisualizer import numpy as np # Create a visualizer for Kerr spacetime vis = CoordinateVisualizer.kerr(M=1.0, a=0.9) # Visualize Boyer-Lindquist coordinates vis.show_coordinate_lines( coordinate_system='boyer-lindquist', r_values=[2.0, 4.0, 6.0, 10.0], theta_values=[0, np.pi/6, np.pi/3, np.pi/2, 2*np.pi/3, 5*np.pi/6, np.pi], phi_values=[0, np.pi/2, np.pi, 3*np.pi/2], title="Boyer-Lindquist Coordinates for Kerr Black Hole" ) # Visualize Kerr-Schild coordinates (which extend smoothly through the horizon) vis.show_coordinate_lines( coordinate_system='kerr-schild', r_values=[0.5, 1.0, 2.0, 4.0, 6.0, 10.0], # Can go inside the horizon theta_values=[0, np.pi/4, np.pi/2, 3*np.pi/4, np.pi], phi_values=[0, np.pi/2, np.pi, 3*np.pi/2], title="Kerr-Schild Coordinates for Kerr Black Hole" ) # Visualize a coordinate transformation vis.show_coordinate_transformation( source='boyer-lindquist', target='kerr-schild', r_range=[1.5, 10.0], theta_range=[0, np.pi], grid_density=10, title="Boyer-Lindquist to Kerr-Schild Transformation" )

Specialized Coordinate Visualizations

Horizon-Penetrating Coordinates

Visualization of coordinates like Kruskal-Szekeres, Painlevé-Gullstrand, or Kerr-Schild that smoothly extend through event horizons, revealing the causal structure of black holes.

Penrose-Carter Diagrams

Conformal diagrams showing the causal structure of spacetime, with null geodesics at 45° angles and infinity represented at finite coordinate values.

Ray Tracing and Optical Appearance

The optical appearance of a black hole and its surroundings requires ray tracing in curved spacetime. iTensor provides a GPU-accelerated ray tracer to generate physically accurate images.

from itensorpy.visualization import BlackHoleRayTracer import numpy as np # Create a ray tracer for a Kerr black hole ray_tracer = BlackHoleRayTracer( metric_type="kerr", parameters={"M": 1.0, "a": 0.98}, # Near-extremal Kerr resolution=(1024, 1024), field_of_view=20.0 # degrees ) # Configure camera position ray_tracer.set_camera_position( r=20.0, # Distance from black hole in M units theta=75.0, # Degrees from spin axis phi=0.0 ) # Configure accretion disk model ray_tracer.set_accretion_disk( inner_radius=2.0, # ISCO for this spin outer_radius=15.0, temperature_profile="novikov-thorne", emissivity=lambda r: r**(-2) # Emissivity profile ) # Configure background starfield ray_tracer.set_background( star_count=5000, distribution="uniform" ) # Render the image with all physical effects image = ray_tracer.render( redshift=True, # Include Doppler and gravitational redshift limb_darkening=True, # Include limb darkening of disk adaptive_sampling=True, # Use adaptive sampling for better quality cuda=True # Use GPU acceleration if available ) # Save the result image.save("kerr_black_hole.png") # Create a sequence with varying parameters for animation frames = [] for inclination in np.linspace(0, 90, 24): ray_tracer.set_camera_position(r=20.0, theta=inclination, phi=0.0) frames.append(ray_tracer.render(cuda=True)) # Save as an animation ray_tracer.save_animation(frames, "black_hole_inclination.mp4", fps=12)

Physical Effects in Ray Tracing

Relativistic Effects

  • Gravitational Lensing: Multiple images and Einstein rings
  • Relativistic Doppler Shift: Blueshift and redshift due to motion
  • Gravitational Redshift: Frequency shift in gravitational potential
  • Shapiro Time Delay: Extra light travel time in curved spacetime

Accretion Physics

  • Disk Temperature Profile: Based on Novikov-Thorne or other models
  • Beaming Effects: Enhanced brightness on approaching side
  • Photon Ring: Light orbiting multiple times near photon sphere
  • Black Hole Shadow: Central darkness surrounded by photon ring

Ray Tracing Algorithm

The ray tracer solves the geodesic equation backwards in time, starting from the observer's camera and tracing rays back to their source. This requires integrating the null geodesic equation using a high-precision adaptive step-size method to ensure accurate light paths even in regions with strong spacetime curvature.

Previous: Numerical TensorsNext: Black Hole Visualization