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!

If you are unfamiliar with using Jupyter Notebooks, first review the official Jupyter Notebook Basics Guide.

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
• cmdline_helper: Multi-platform command-line helper functions (Courtesy Brandon Clark)
• 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
• Method of Lines for PDEs: Step PDEs forward in time using ODE methods
  • Solving ODEs using explicit Runge Kutta methods (Courtesy Brandon Clark)
    • The Family of explicit Runge-Kutta methods and their Butcher tables
    • Validating Runge Kutta Butcher tables using truncated Taylor series
  • Generating C Code to implement Method of Lines timestepping with explicit Runge Kutta-like methods (Courtesy Brandon Clark)
• Writing your own NRPy+ tutorial module: A Style Guide (Courtesy Brandon Clark)

PART 2: Basic Physics Applications

Using 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 exact initial data validation module: Confirms all exact initial data types listed above satisfy Einstein's equations of general relativity. (Courtesy Brandon Clark & George Vopal)
  • 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 numerical initial data validation module: The TOV solution: Neutron star initial data, confirms numerical errors converge to zero at expected order (TOV initial data are generated via the numerical solution of a system of ODEs, thus are known only numerically)

• 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