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 (NRPy+ home 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 in Cartesian coordinates

• Application: All 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

Solving the Effective-One-Body Equations of Motion

• Application (**in progress**): SEOBNR: The Spinning-Effective-One-Body-Numerical-Relativity Hamiltonian
  • Solving the SEOBNR Hamiltonian equations of motion
    • Taking exact derivatives of the SEOBNR Hamiltonian & generating highly optimized C code with NRPy+

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

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
  • Writing quantities of ADM formalism in terms of BSSN quantities
• 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)
  • Spinning Shifted Kerr-Schild black hole initial data (Courtesy George Vopal)
  • Brill-Lindquist initial data: Two-black-holes released from rest
  • Black hole accretion disk initial data (Fishbone-Moncrief)
    • **FishboneMoncriefID**: Setting up Fishbone-Moncrief disk initial data within the **Einstein Toolkit**, using HydroBase variables as input
  • 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)
      • Spinning (Shifted Kerr-Schild) black hole initial data validation: numerical error convergence to zero (Courtesy George Vopal)
      • 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

• Diagnostic curvilinear BSSN modules

  • The gravitational wave Weyl scalar $\psi_4$, in arbitrary curvilinear coordinates
    • Constructing the quasi-Kinnersley tetrad for $\psi_4$
      • Start-to-Finish validation of above expressions in Cartesian coordinates, against Patrick Nelson's Weyl Scalars & Invariants module
    • Spin-weighted spherical harmonics (Courtesy Brandon Clark)

• 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