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)
• NRPy+: 10-minute Overview $\leftarrow$ Start here
• Solving the scalar wave equation with NumPy $\leftarrow$ Then go here (fully worked example of a hyperbolic PDE solver, written in pure Python)
• 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)
• 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

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.

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

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)

• BSSN initial data reader

  • Initial Data Reader/Converter: ADM Spherical/Cartesian to BSSN-with-a-reference-metric (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)
    • 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

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
  • Derivation of the GRMHD evolution equations from $T^{\mu\nu}$ in our formalism
• 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$