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)
• Solving the scalar wave equation with NumPy $\leftarrow$ Start here (provides the basic structure of a PDE solver like NRPy+)
• 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.)
• Loop Generation
• Finite Difference Derivatives
  • Instructional notebook: How NRPy+ Computes Finite Difference Derivative Coefficients
  • Start-to-Finish Example: Finite-Difference Playground: A Complete C Code for Validating NRPy+-Based Finite Differences
• NRPy+ SymPy LaTeX Interface (Courtesy Ken Sible)
  • Start-to-Finish Example: LaTeX Interface: BSSN (Cartesian)
• 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)
• Convenient mathematical operations
  • Representing min(a,b) and max(a,b) without if() statements; defining piecewise functions (Courtesy Patrick Nelson)
  • Symbolic Tensor Rotation using Quaternions (Courtesy Ken Sible)
  • Sommerfeld Outer Boundary Condition (Courtesy Terrence Pierre Jacques)
• Contributing to NRPy+
  • The NRPy+ Tutorial Style Guide (Courtesy Brandon Clark)
  • Adding Unit Tests (Courtesy Kevin Lituchy)

PART 2: Basic Physics Applications

Using NRPy+ to Numerically Solve the Scalar Wave Equation in Cartesian Coordinates

• Application: The Scalar Wave Equation in Cartesian Coordinates
  • 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 & Terrence Pierre Jacques)
    • **IDScalarWaveNRPy**: Initial data for the scalar wave equation
    • **WaveToyNRPy**: Solving the scalar wave equation, using the method of lines

Using NRPy+ to Numerically Solve Maxwell's Equations in Cartesian Coordinates

• Application: Maxwell's Equations in Cartesian Coordinates
  • Start-to-Finish Example: Numerically Solving Maxwell's Equations: A Complete C Code (Courtesy Terrence Pierre Jacques)
  • Solving Maxwell's Equations with the **Einstein Toolkit** (Courtesy Terrence Pierre Jacques & Patrick Nelson)
    • **MaxwellVacuumID**: An initial data thorn for Maxwell's equations
    • **MaxwellVacuum**: Solving Maxwell's equations in the using the method of lines

Diagnostic Notebooks: 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)

Solving the Effective-One-Body Equations of Motion

• Application: SEOBNR: The Spinning-Effective-One-Body-Numerical-Relativity Hamiltonian, version 3
  • Solving the SEOBNR Hamiltonian equations of motion (**in progress**)
    • Initial data: Setting the initial trajectory
    • SymPy-generated exact derivatives of the SEOBNR Hamiltonian
  • The SEOBNRv4P Hamiltonian

NRPyPN: Validated Post-Newtonian Expressions for Input into Wolfram Mathematica, SymPy, or Highly-Optimized C Codes

• NRPyPN Main Menu $\leftarrow$ includes NRPyPN Table of Contents and a quick interface for setting up low-eccentricity (up to 3.5 PN order) momentum parameters for binary black hole initial data

NRPyCritCol: Critical phenomena in gravitational collapse

• ADM initial data for massless scalar field (The initial data is shown to satisfy the constraints at the expected convergence rate in this tutorial notebook) (Courtesy Leo Werneck)
• Massless scalar field energy-momentum tensor (Courtesy Leo Werneck)
• Massless scalar field evolution equations (Courtesy Leo Werneck)
• Start-to-finish example: gravitational collapse of a massless scalar field (Courtesy Leo Werneck)

PART 3: Solving PDEs in Curvilinear Coordinate Systems

• Moving beyond Cartesian Grids: Reference Metrics
• Start-to-Finish Example: Implementation of Curvilinear Boundary Conditions, Including for Tensorial Quantities
• 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
• Application: Maxwell's Equations in Curvilinear Coordinates, using a Reference Metric (Courtesy Terrence Pierre Jacques)
  • Start-to-Finish Example: Numerically Solving Maxwell's Equations in Curvilinear Coordinates: A Complete C Code

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
  • Basis transformations of BSSN variables
• Initial data notebooks. 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)
    • Implementation of Single and Piecewise Polytropic EOSs (Courtesy Leo Werneck)
• 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 notebook: 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 notebook: 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 notebook
    • 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
  • Gravitational collapse of a massless scalar field (Courtesy Leo Werneck)

PART 5: Numerical Relativity $-$ General Relativistic Hydrodynamics (GRHD), Force-Free Electrodynamics (GRFFE), & Magnetohydrodynamics (GRMHD)

• The equations of general relativistic hydrodynamics (GRHD), in Cartesian coordinates
• The equations of general relativistic, force-free electrodynamics (GRFFE), in Cartesian coordinates
• The equations of general relativistic magnetohydrodynamics (GRMHD), in Cartesian coordinates
• IllinoisGRMHD with piecewise-polytrope/hybrid equation of state support (Courtesy Leo Werneck): ***In progress***
  • Diagnostic notebook: **sbPoynETNRPy**: Evaluating $b^\mu$ and $S^i$ in the **Einstein Toolkit**, using HydroBase variables as input
    • Tutorial notebook: Computing the 4-Velocity Time-Component $u^0$, the Magnetic Field Measured by a Comoving Observer $b^{\mu}$, and the Poynting Vector $S^i$