The NRPy+ Tutorial: An Introduction to Python-Based Code Generation for Numerical Relativity... and Beyond!

Lead author: Zachariah B. Etienne $\leftarrow$ Please feel free to email comments, revisions, or errata!

PART 1: Basic Functionality of NRPy+, a First Application

NRPy+ Basics

• NRPy+: Introduction & Motivation ([email protected] web page)
• Basic C Code Output, NRPy+'s Parameter Interface
• Numerical Grids
• Indexed Expressions (e.g., tensors, pseudotensors, etc.)
• Finite Difference Derivatives
  • Instructional module: How NRPy+ Computes Finite Difference Derivative Coefficients
  • Start-to-Finish Example: Finite-Difference Playground: A Complete C Code for Validating NRPy+-Based Finite Differences

PART 2: Basic Physics Applications

Leveraging NRPy+ to Numerically Solve PDEs

• Application: The Scalar Wave Equation in Cartesian Coordinates, with Plane-Wave Initial Data
  • Start-to-Finish Example: Numerically Solving the Scalar Wave Equation: A Complete C Code
  • Solving the Wave Equation with the **Einstein Toolkit** (Courtesy Patrick Nelson)
    • **IDScalarWaveNRPy**: Plane-wave initial data module for the scalar wave equation
    • **WaveToyNRPy**: Solving the scalar wave equation, using the method of lines
• Application (in progress): Two Formulations of Maxwell's Equations in Cartesian Coordinates. (Formulations based on Illustrating Stability Properties of Numerical Relativity in Electrodynamics by Knapp, Walker, and Baumgarte.) (Courtesy Patrick Nelson)
  • **IDMaxwellNRPy**: An **Einstein Toolkit** initial data thorn for Maxwell's equations
  • **MaxwellEvol**: Solving Maxwell's equations in the **Einstein Toolkit** using the method of lines

Diagnostic Modules: Gravitational Wave Extraction

• Application: The Weyl Scalars and Invariants in Cartesian Coordinates (Courtesy Patrick Nelson)
  • **WeylScal4NRPy**: An **Einstein Toolkit** Diagnostic Thorn (Courtesy Patrick Nelson)

Diagnostic Modules: GRMHD/GRFFE

• Application: Computing the 4-Velocity Time-Component $u^0$, the Magnetic Field Measured by a Comoving Observer $b^{\mu}$, and the Poynting Vector $S^i$
  • **sbPoynETNRPy**: Evaluating $b^\mu$ and $S^i$ in the **Einstein Toolkit**, using HydroBase variables as input

PART 3: Solving PDEs in Curvilinear Coordinate Systems

• Moving beyond Cartesian Grids: Reference Metrics
• Application: The Scalar Wave Equation in Curvilinear Coordinates, using a Reference Metric
  • Start-to-Finish Example: Numerically Solving the Scalar Wave Equation in Curvilinear Coordinates: A Complete C Code
• Start-to-Finish Example: Implementation of Curvilinear Boundary Conditions, Including for Tensorial Quantities
• Application: Maxwell's Equations in Curvilinear Coordinates, using a Reference Metric (Courtesy Ian Ruchlin)

PART 4: Numerical Relativity; BSSN in Curvilinear Coordinates

• Overview: Covariant BSSN formulation of general relativity in curvilinear coordinates
  • Construction of useful BSSN quantities
  • BSSN time-evolution equations
  • Time-evolution equations for BSSN gauge quantities $\alpha$ and $\beta^i$
  • Hamiltonian and momentum constraint equations
  • Enforcing the conformal 3-metric $\det{\bar{\gamma}_{ij}}=\det{\hat{\gamma}_{ij}}$ constraint
• Initial data modules. Initial data are set in terms of standard ADM formalism spacetime quantities.
  • Non-Spinning ("static trumpet") black hole initial data (Courtesy Terrence Pierre Jacques & Ian Ruchlin)
  • Spinning ("UIUC") Black Hole initial data (Courtesy Terrence Pierre Jacques & Ian Ruchlin)
  • Brill-Lindquist initial data: Two-black-holes released from rest
  • Neutron Star initial data: The Tolman-Oppenheimer-Volkoff (TOV) solution (Courtesy Phil Chang)
• ADM-to-curvilinear-BSSN initial data conversion
  • Exact ADM Spherical/Cartesian to BSSN Curvilinear Initial Data Conversion (Use this module for initial data conversion if the initial data are known exactly. The BSSN quantity $\lambda^i$ will be computed exactly using SymPy from given ADM quantities.)
    • Start-to-Finish initial data validation modules:
      • Non-Spinning ("static trumpet") black hole initial data validation: numerical error convergence to zero (Courtesy Terrence Pierre Jacques)
      • Two-black-hole initial data validation: numerical error convergence to zero
  • Numerical ADM Spherical/Cartesian to BSSN Curvilinear Initial Data Conversion (Use this module for initial data conversion if the initial data are provided by an initial data solver, and are thus known to roundoff error at best. The BSSN quantity $\lambda^i$ will be computed using finite-difference derivatives from given ADM quantities.)
    • Start-to-Finish initial data validation modules: (Note that UIUC black hole initial data are exact; however we choose to set them up as though they were only known numerically, as a validation test for the numerical ADM-Spherical-to-BSSN-Curvilinear initial data conversion module. TOV initial data on the other hand are generated via the solution of a system of ODEs, thus are truly known only numerically):
      • Spinning ("UIUC") black hole initial data validation: numerical error convergence to zero
      • Neutron star (TOV solution) initial data validation: numerical error convergence to zero
• Start-to-Finish curvilinear BSSN simulation examples:
  • **Colliding black holes!**
  • The "Hydro without Hydro" test: evolving the spacetime fields of TOV star with $T^{\mu\nu}$ assumed static In progress