aurel: A Python package for automatic relativistic calculations

The paper introduces **aurel**, an open-source Python package that streamlines both symbolic and numerical relativistic calculations by leveraging a flexible caching system and finite-difference methods to process data from analytical expressions or Numerical Relativity simulations.

The Gist

Imagine you are trying to understand a complex, shifting landscape where space and time themselves are bending, stretching, and warping like a trampoline under heavy weights. This is the world of General Relativity, the physics theory that describes gravity.

For decades, scientists have built massive, powerful supercomputer simulations (called Numerical Relativity) to model these wild landscapes, such as two black holes smashing into each other. These simulations produce mountains of raw data—gigabytes of numbers representing how space and time are behaving at every single point.

However, there's a problem: The data is there, but the answers aren't.

The Problem: A Mountain of Raw Ingredients

Think of these simulations like a giant, high-tech kitchen that has just baked a massive, perfect cake (the simulation data). But the cake is just sitting there in a pan. If a scientist wants to know the specific flavor of the frosting, the exact density of the sponge, or how much sugar is in a single crumb, they have to manually measure, mix, and calculate it themselves.

In the past, every new scientist had to build their own "measuring cup" and "recipe book" from scratch to analyze this cake.

• It was slow: They spent months writing code just to do basic math.
• It was messy: If they made a tiny mistake in their measuring cup, the whole result was wrong.
• It was repetitive: Everyone was reinventing the same wheel over and over again.

The Solution: Enter "Aurel"

The paper introduces Aurel, a new free software tool (a Python package) that acts like an automated, super-smart sous-chef for these physics simulations.

Here is how Aurel works, using simple analogies:

1. The "Smart Filing System" (Caching)

Imagine you are solving a giant puzzle. Usually, you might calculate the same piece of the puzzle five different times because you forgot you already did it.
Aurel is like a super-organized librarian.

• When you ask it, "What is the curvature of space here?" it calculates it once and puts the answer in a special, labeled box.
• If you ask again, or if a different calculation needs that same answer, Aurel instantly pulls the box off the shelf instead of doing the math again.
• It even knows when the library is getting too full, so it smartly throws away old, unused boxes to make room for new ones, ensuring the computer doesn't crash.

2. The "Automatic Assembly Line" (Dependency Tracking)

In physics, to calculate a complex thing (like "gravitational waves"), you first need to calculate simpler things (like "how fast space is stretching").

• Without Aurel, a scientist has to manually write code to calculate step A, then step B, then step C, in the right order.
• With Aurel, you just say, "I want the gravitational waves." Aurel looks at its map, realizes, "Oh, I need Step C, which needs Step B, which needs Step A," and automatically runs the whole assembly line in the correct order. You don't have to worry about the order; the software handles the logic.

3. The "Universal Translator"

Different supercomputers speak different "languages" (data formats).

• Aurel comes with built-in dictionaries that can read data from the most popular simulation tools (like the Einstein Toolkit). It translates the raw, confusing data from the supercomputer into a format that Aurel can instantly understand and work with.

Why Does This Matter?

Before Aurel, a new student or researcher might spend six months just learning how to write the code to analyze a simulation. With Aurel, they can start analyzing the physics on day one.

• For Experts: It saves them from doing boring, repetitive math so they can focus on the big discoveries.
• For Students: It lowers the barrier to entry, letting them understand complex black hole collisions without needing to be a master coder first.
• For the Field: It creates a standard way of doing things, so everyone is speaking the same language and making fewer mistakes.

In a Nutshell

Aurel is the tool that turns a mountain of raw, confusing numbers from a black hole simulation into clear, understandable answers about how the universe works. It automates the heavy lifting, so scientists can stop worrying about how to calculate the math and start focusing on what the math is telling us about the cosmos.

Note: The authors of the paper even used AI to help write the code and documentation, making this a modern tool built with modern tools!

Technical Summary

Based on the provided paper, here is a detailed technical summary of aurel, a Python package for automatic relativistic calculations.

1. Problem Statement

General Relativity (GR) involves complex, highly nonlinear tensor algebra where the distribution of matter dictates the geometry of spacetime. While Numerical Relativity (NR) has become essential for modern astrophysics (e.g., gravitational wave modeling), researchers face significant hurdles in post-processing simulation data:

• High Overhead: Newcomers must spend substantial time developing personal post-processing codes to calculate derived quantities.
• Error-Prone Manual Work: Even experienced researchers face tedious tasks handling intermediary variables and tensor indices, leading to potential errors.
• Fragmented Ecosystem: Existing NR codes (e.g., Einstein Toolkit, GRChombo) often have built-in diagnostic tools specific to their architecture. Switching codes requires learning new ecosystems, and many specific relativistic quantities are not pre-calculated, forcing users to implement them manually.
• Symbolic vs. Numerical Gap: While symbolic tools exist, they often struggle with the complexity of nonlinearities found in full NR simulations, necessitating a robust numerical solution that can handle arbitrary spacetime and matter data arrays.

2. Methodology and Software Design

aurel is an open-source Python package designed to automate the calculation of relativistic quantities from spacetime and matter data. It operates in two modes:

• Symbolic Mode (AurelCoreSymbolic): Built on SymPy, extending it with additional tensorial calculations for analytical expressions.
• Numerical Mode (AurelCore): Built on NumPy (specifically utilizing numpy.einsum for efficient array operations), this mode computes tensorial quantities directly from data arrays using finite-difference methods.

Key Technical Features:

• Input Flexibility: Accepts inputs from analytical expressions or Numerical Relativity simulations. It includes helper functions to read standard NR data formats (specifically Carpet output from the Einstein Toolkit), handling parameter files, iterations, restarts, chunks, and refinement levels.
• Derivative Schemes: All spatial derivatives are computed via a FiniteDifference class supporting 2nd, 4th, 6th, and 8th-order schemes with periodic, symmetric, or one-sided boundary conditions.
• Automatic Dependency Resolution (Lazy Evaluation):
  • The core innovation is a lazy-evaluation memoised property pattern.
  • Quantities are requested via a dictionary-style interface (e.g., rel["s_RicciS"]).
  • The system checks a cache; if the quantity is missing, it recursively calculates dependencies (e.g., calculating the metric before the Ricci tensor) until the result is derived.
  • This eliminates the need for users to manually define the order of operations or manage intermediate variables.
• Intelligent Caching & Memory Management:
  • Results are cached to avoid redundant computations.
  • An intelligent eviction policy (inspired by Python's garbage collection) manages memory by tracking footprint, evaluation counts, and last-access times. It removes older/heavier cached quantities when thresholds are exceeded while protecting base quantities.
• Time Dependence: Calculations are performed on single time slices. For time-series analysis, the over_time function automates the creation of AurelCore objects for each step and computes summary statistics (max/min) across the grid.

3. Key Contributions

• Code-Agnostic Post-Processing: aurel provides a standardized framework that works with any NR simulation output, removing the need to learn specific diagnostic tools for different codes.
• Extensive Quantity Catalog: It supports a vast range of calculations, including:
  • Spacetime and matter distributions (Eulerian, Lagrangian, conserved).
  • NR formulations and constraints.
  • Fluid covariant kinematics and null ray expansion.
  • 3D and 4D curvature tensors.
  • Gravito-electromagnetism, Weyl scalars, and invariants (including gravitational waves).
• Automatic Computational Pathway: The dependency-tracking system automatically constructs the calculation pathway at runtime, significantly reducing the "boilerplate" code required for tensor algebra.
• Accessibility: The package is designed to lower the barrier to entry for master's students and new researchers, allowing them to analyze NR simulations and obtain results quickly without deep expertise in tensor coding.

4. Results and Impact

• Workflow Efficiency: In ongoing studies involving primordial black hole formation, aurel has successfully redirected development efforts from repetitive coding to exploring broader simulated scenarios.
• Educational Value: The transparent design has served as an effective gateway for master's students to analyze NR simulations within the short duration of their projects.
• Community Adoption: The package has been disseminated through conference interactions and collaborations, with early testers (e.g., Nat Kemp) validating its integration and dependency resolution.
• Development Transparency: The authors utilized AI (GitHub Copilot/Claude Sonnet 4) for scaffolding tests and drafting docstrings, with all core design decisions and structural innovations remaining human-led.

5. Significance

aurel addresses a critical bottleneck in the field of Numerical Relativity: the transition from raw simulation data to physical insight. By automating the complex tensor algebra and dependency management required in General Relativity, it:

1. Standardizes post-processing across different NR codes.
2. Reduces the risk of human error in tensor index manipulation.
3. Accelerates research cycles, allowing physicists to focus on physical interpretation rather than computational implementation.
4. Democratizes access to advanced relativistic diagnostics, supporting the popularization of NR in astrophysics and cosmology.

The package is open-source (CC BY 4.0), hosted on GitHub, and available via PyPI, positioning it as a vital tool for the growing community of relativistic physicists.