Welcome to aurel’s documentation!

Aurel is an open source Python package for numerical relativity analysis. Designed with ease of use in mind, it will automatically calculate relativistic terms.

Key Features

• Comprehensive tensor calculations:
  • Numerically (see the following sections and documentation, examples)
  • Symbolically (documentation, example)
• Dynamic computation and intelligent caching: Aurel automatically calculates only what's needed and caches results, significantly improving performance for complex calculations
• Clear user feedback: Progress bars and informative messages guide you through computations
• Time evolution support: Tools for analyzing data across multiple time steps (documentation, example)
• Flexible data input: Works seamlessly with numerical simulation data, analytical solutions, or custom numpy arrays
• Einstein Toolkit integration: Native support for reading Carpet HDF5 outputs from Einstein Toolkit simulations (documentation, example)
• Advanced finite difference schemes: Multiple discretization schemes for 3D spatial grids
• Built-in analytical solutions: Pre-implemented spacetimes for testing and validation (examples)

Installation

Requirements:

• Python 3.11 or higher (download here)
• pip (usually included with Python, or install separately)

Install aurel using pip (all other dependencies will be installed automatically):

pip install aurel

To get the latest development version:

pip install git+https://github.com/robynlm/aurel.git@development

Getting started

Start your Python session on a jupyter notebook or in a Python script and import the aurel.AurelCore class:

   
   import aurel
   
   # Define your grid parameters
   param = {
       'Nx': 64, 'Ny': 64, 'Nz': 64,
       'xmin': -1.0, 'ymin': -1.0, 'zmin': -1.0,
       'dx': 0.03125, 'dy': 0.03125, 'dz': 0.03125,
   }
   
   # Initialize the finite difference class
   fd = aurel.FiniteDifference(param)
   
   # Initialize the AurelCore class
   rel = aurel.AurelCore(fd)

At this point you need to provide the spacetime metric, extrinsic curvature and matter fields (see assumed quantities), otherwise these are assumed to correspond to Minkowski vacuum. These are passed as numpy arrays to aurel in the following way:

# Define the xx component of the spacetime metric
rel.data['gxx'] = np.ones((param['Nx'], param['Ny'], param['Nz']))

and so on for the other components and required quantities. In this example $g_{xx} = 1$, but you can pass any numpy array; it can be of numerical relativity simulation data, or an array generated from an analytical expression. Take care to run rel.freeze_data() so that your input data is conserved during the cache cleanup.

With everything defined, you can call any entity listed in the descriptions list. Just call it as:

rel["name_of_the_entity"]

Aurel will automatically do its best to calculate any relativistic term you ask for.

For a more in depth example, see the example notebook for applications. Additionally, a symbolic counterpart that works in a very similar way is also available via the aurel.AurelCoreSymbolic class, see the symbolic example notebook for details.

Calculations over time

If you want calculations over multiple moments in coordinate time, you can use the aurel.over_time function. First, create a dictionary containing the spacetime and matter fields over time:

# Define the spacetime metric gxx over time
data = {
    'gxx': [np.ones((param['Nx'], param['Ny'], param['Nz'])),
            np.ones((param['Nx'], param['Ny'], param['Nz']))],
    ...
}

That is a data dictionary with keys the names of the quantities, and values a list of numpy arrays, one for each time step. Calculations will be performed for each of these time steps as:

data = aurel.over_time(
   data, fd, 
   vars=['name_of_the_entity', ..., {'custom_quantity': custom_quantity}], 
   estimates=['name_of_estimate', ..., {'custom_estimate': custom_estimate}],
   **kwargs)

where vars is a list of entities to calculate at each time step (available terms are in the descriptions list, but you can also pass custom functions to calculate your own quantities). Likewise estimates is a list of estimates to calculate at each time step (available functions are in the estimates list, but you can also pass custom functions to calculate your own estimates). See the time evolution example for more details.

Citation

If you use aurel in your work, please cite or reference the arXiv preprint in the following way:

@misc{aurel2026,
  title         = {aurel: A Python package for automatic relativistic calculations},
  author        = {Robyn L. Munoz and Christian T. Byrnes and Will J. Roper},
  year          = {2026},
  doi           = {10.48550/arXiv.2602.00155},
  eprint        = {2602.00155},
  archivePrefix = {arXiv},
  primaryClass  = {astro-ph.IM},
  url           = {https://robynlm.github.io/aurel/}
}

This code is not published yet, so to add to citation count please also include its predecessor:

@article{R.L.Munoz_M.Bruni_2023,
  title     = {EBWeyl: a Code to Invariantly Characterize Numerical Spacetimes},
  author    = {Robyn L. Munoz and Marco Bruni},
  journal   = {Classical and Quantum Gravity},
  volume    = {40},
  number    = {13},
  pages     = {135010},
  year      = {2023},
  month     = {jun},
  doi       = {10.1088/1361-6382/acd6cf},
  archivePrefix = {arXiv},
  eprint    = {2211.08133},
  primaryClass = {gr-qc}
}