{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "\n", "\n", "\n", "## The NRPy+ Tutorial: An Introduction to Python-Based Code Generation for Numerical Relativity... and Beyond!\n", "\n", "### Lead author: [Zachariah B. Etienne](http://astro.phys.wvu.edu/zetienne/) $\\leftarrow$ Please feel free to email comments, revisions, or errata! \n", "\n", "***If you are unfamiliar with using Jupyter Notebooks, first review the official [Jupyter Notebook Basics Guide](https://nbviewer.jupyter.org/github/jupyter/notebook/blob/master/docs/source/examples/Notebook/Notebook%20Basics.ipynb).***\n", "\n", "### PART 1: Basic Functionality of NRPy+, a First Application\n", "##### NRPy+ Basics\n", "+ [NRPy+: Introduction & Motivation](http://astro.phys.wvu.edu/bhathome/nrpy.html) (NRPy+ home page)\n", "+ [Solving the scalar wave equation with `NumPy`](Tutorial-Solving_the_Scalar_Wave_Equation_with_NumPy.ipynb) $\\leftarrow$ **Start here** (provides the basic structure of a PDE solver like NRPy+)\n", "+ [Basic C Code Output, NRPy+'s Parameter Interface](Tutorial-Coutput__Parameter_Interface.ipynb)\n", "+ [`cmdline_helper`: Multi-platform command-line helper functions](Tutorial-cmdline_helper.ipynb) (*Courtesy Brandon Clark*)\n", "+ [Numerical Grids](Tutorial-Numerical_Grids.ipynb)\n", "+ [Indexed Expressions (e.g., tensors, pseudotensors, etc.)](Tutorial-Indexed_Expressions.ipynb)\n", "+ [Loop Generation](Tutorial-Loop_Generation_Cache_Blocking.ipynb)\n", "+ [Finite Difference Derivatives](Tutorial-Finite_Difference_Derivatives.ipynb)\n", " + Instructional notebook: [How NRPy+ Computes Finite Difference Derivative Coefficients](Tutorial-How_NRPy_Computes_Finite_Difference_Coeffs.ipynb)\n", " + **Start-to-Finish Example**: [Finite-Difference Playground: A Complete C Code for Validating NRPy+-Based Finite Differences](Tutorial-Start_to_Finish-Finite_Difference_Playground.ipynb)\n", "+ [NRPy+ SymPy LaTeX Interface](Tutorial-SymPy_LaTeX_Interface.ipynb) (*Courtesy Ken Sible*)\n", " + **Start-to-Finish Example**: [LaTeX Interface: BSSN (Cartesian)](Tutorial-LaTeX_Interface_Example-BSSN_Cartesian.ipynb)\n", "+ Method of Lines for PDEs: Step PDEs forward in time using ODE methods\n", " + Solving ODEs using explicit Runge Kutta methods (*Courtesy Brandon Clark*)\n", " + [The Family of explicit Runge-Kutta methods and their Butcher tables](Tutorial-RK_Butcher_Table_Dictionary.ipynb)\n", " + [Validating Runge Kutta Butcher tables using truncated Taylor series](Tutorial-RK_Butcher_Table_Validation.ipynb)\n", " + [Generating C Code to implement Method of Lines timestepping with explicit Runge Kutta-like methods](Tutorial-Method_of_Lines-C_Code_Generation.ipynb) (*Courtesy Brandon Clark*)\n", "+ Convenient mathematical operations\n", " + [Representing `min(a,b)` and `max(a,b)` without `if()` statements; defining piecewise functions](Tutorial-Min_Max_and_Piecewise_Expressions.ipynb) (*Courtesy Patrick Nelson*)\n", " + [Symbolic Tensor Rotation using Quaternions](Tutorial-Symbolic_Tensor_Rotation.ipynb) (*Courtesy Ken Sible*)\n", " + [Sommerfeld Outer Boundary Condition](Tutorial-SommerfeldBoundaryCondition.ipynb) (*Courtesy Terrence Pierre Jacques*)\n", "+ Contributing to NRPy+\n", " + [The NRPy+ Tutorial Style Guide](Tutorial-Template_Style_Guide.ipynb) (*Courtesy Brandon Clark*)\n", " + [Adding Unit Tests](Tutorial-UnitTesting.ipynb) (*Courtesy Kevin Lituchy*)\n", "\n", "### PART 2: Basic Physics Applications \n", "##### Using NRPy+ to Numerically Solve the Scalar Wave Equation in Cartesian Coordinates\n", "+ Application: [The Scalar **Wave Equation** in Cartesian Coordinates](Tutorial-ScalarWave.ipynb)\n", " + **Start-to-Finish Example**: [Numerically Solving the Scalar Wave Equation: A Complete C Code](Tutorial-Start_to_Finish-ScalarWave.ipynb)\n", " + Solving the Wave Equation with the **Einstein Toolkit** (*Courtesy Patrick Nelson & Terrence Pierre Jacques*)\n", " + [**IDScalarWaveNRPy**: Initial data for the scalar wave equation](Tutorial-ETK_thorn-IDScalarWaveNRPy.ipynb) \n", " + [**WaveToyNRPy**: Solving the scalar wave equation, using the method of lines](Tutorial-ETK_thorn-WaveToyNRPy.ipynb)\n", "\n", "##### Using NRPy+ to Numerically Solve Maxwell's Equations in Cartesian Coordinates\n", "+ Application: [**Maxwell's Equations** in Cartesian Coordinates](Tutorial-VacuumMaxwell_formulation_Cartesian.ipynb)\n", " + **Start-to-Finish Example**: [Numerically Solving Maxwell's Equations: A Complete C Code](Tutorial-Start_to_Finish-Solving_Maxwells_Equations_in_Vacuum-Cartesian.ipynb) (*Courtesy Terrence Pierre Jacques*)\n", " + Solving Maxwell's Equations with the **Einstein Toolkit** (*Courtesy Terrence Pierre Jacques & Patrick Nelson*)\n", " + [**MaxwellVacuumID**: An initial data thorn for Maxwell's equations](Tutorial-ETK_thorn-MaxwellVacuumID.ipynb)\n", " + [**MaxwellVacuum**: Solving Maxwell's equations in the using the method of lines](Tutorial-ETK_thorn-MaxwellVacuum.ipynb)\n", "\n", "##### Diagnostic Notebooks: Gravitational Wave Extraction in Cartesian coordinates\n", "+ Application: [All Weyl scalars and invariants in Cartesian Coordinates](Tutorial-WeylScalarsInvariants-Cartesian.ipynb) (*Courtesy Patrick Nelson*)\n", " + [**WeylScal4NRPy**: An **Einstein Toolkit** Diagnostic Thorn](Tutorial-ETK_thorn-Weyl_Scalars_and_Spacetime_Invariants.ipynb) (*Courtesy Patrick Nelson*)\n", "\n", "\n", "##### Solving the Effective-One-Body Equations of Motion\n", "\n", "+ Application: [SEOBNR: The Spinning-Effective-One-Body-Numerical-Relativity Hamiltonian, version 3](Tutorial-SEOBNR_v3_Hamiltonian.ipynb)\n", " + Solving the SEOBNR Hamiltonian equations of motion (**in progress**)\n", " + [Initial data: Setting the initial trajectory](in_progress/Tutorial-SEOBNR_Initial_Conditions.ipynb)\n", " + [SymPy-generated exact derivatives of the SEOBNR Hamiltonian](in_progress/Tutorial-Spinning_Effective_One_Body_Numerical_Relativity_Hamiltonian-Cartesian.ipynb)\n", " + [The SEOBNRv4P Hamiltonian](Tutorial-SEOBNR_v4P_Hamiltonian.ipynb)\n", "\n", "##### NRPyPN: Validated Post-Newtonian Expressions for Input into Wolfram Mathematica, SymPy, or Highly-Optimized C Codes\n", "\n", "+ [NRPyPN Main Menu](NRPyPN/NRPyPN.ipynb) $\\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\n", "\n", "##### NRPyCritCol: Critical phenomena in gravitational collapse\n", "+ [ADM initial data for massless scalar field](Tutorial-ADM_Initial_Data-ScalarField) (The initial data is shown to satisfy the constraints at the expected convergence rate [in this tutorial notebook](Tutorial-Start_to_Finish-BSSNCurvilinear-Setting_up_ScalarField_initial_data.ipynb)) (*Courtesy Leo Werneck*)\n", "+ [Massless scalar field energy-momentum tensor](Tutorial-ScalarField_Tmunu.ipynb) (*Courtesy Leo Werneck*)\n", "+ [Massless scalar field evolution equations](Tutorial-ScalarField_RHSs.ipynb) (*Courtesy Leo Werneck*)\n", "+ [Start-to-finish example: gravitational collapse of a massless scalar field](Tutorial-Start_to_Finish-BSSNCurvilinear-ScalarField_Collapse.ipynb) (*Courtesy Leo Werneck*)\n", "\n", "### PART 3: Solving PDEs in Curvilinear Coordinate Systems\n", "+ [Moving beyond Cartesian Grids: Reference Metrics](Tutorial-Reference_Metric.ipynb)\n", "+ **Start-to-Finish Example**: [Implementation of Curvilinear Boundary Conditions, Including for Tensorial Quantities](Tutorial-Start_to_Finish-Curvilinear_BCs.ipynb)\n", "+ Application: [**The Scalar Wave Equation** in Curvilinear Coordinates, using a Reference Metric](Tutorial-ScalarWaveCurvilinear.ipynb)\n", " + **Start-to-Finish Example**: [Numerically Solving the Scalar Wave Equation in Curvilinear Coordinates: A Complete C Code](Tutorial-Start_to_Finish-ScalarWaveCurvilinear.ipynb)\n", "+ Application: [**Maxwell's Equations** in Curvilinear Coordinates, using a Reference Metric](Tutorial-VacuumMaxwell_formulation_Curvilinear.ipynb) (*Courtesy Terrence Pierre Jacques*)\n", " + **Start-to-Finish Example**: [Numerically Solving Maxwell's Equations in Curvilinear Coordinates: A Complete C Code](Tutorial-Start_to_Finish-Solving_Maxwells_Equations_in_Vacuum-Curvilinear.ipynb)\n", "\n", "### PART 4: Numerical Relativity $-$ BSSN in Curvilinear Coordinates\n", "\n", "+ [**Overview: Covariant BSSN formulation of general relativity in curvilinear coordinates**](Tutorial-BSSN_formulation.ipynb)\n", " + [Construction of useful BSSN quantities](Tutorial-BSSN_quantities.ipynb)\n", " + [BSSN time-evolution equations](Tutorial-BSSN_time_evolution-BSSN_RHSs.ipynb)\n", " + [Time-evolution equations for BSSN gauge quantities $\\alpha$ and $\\beta^i$](Tutorial-BSSN_time_evolution-BSSN_gauge_RHSs.ipynb)\n", " + [Hamiltonian and momentum constraint equations](Tutorial-BSSN_constraints.ipynb)\n", " + [Enforcing the conformal 3-metric $\\det{\\bar{\\gamma}_{ij}}=\\det{\\hat{\\gamma}_{ij}}$ constraint](Tutorial-BSSN_enforcing_determinant_gammabar_equals_gammahat_constraint.ipynb)\n", " + [Writing quantities of ADM formalism in terms of BSSN quantities](Tutorial-ADM_in_terms_of_BSSN.ipynb)\n", " + [Basis transformations of BSSN variables](Tutorial-BSSN-basis_transforms.ipynb)\n", "+ **Initial data notebooks**. Initial data are set in terms of standard [ADM formalism](https://en.wikipedia.org/wiki/ADM_formalism) spacetime quantities.\n", " + [Non-Spinning (\"static trumpet\") black hole initial data](Tutorial-ADM_Initial_Data-StaticTrumpet.ipynb) (*Courtesy Terrence Pierre Jacques & Ian Ruchlin*)\n", " + [Spinning UIUC black hole initial data](Tutorial-ADM_Initial_Data-UIUC_BlackHole.ipynb) (*Courtesy Terrence Pierre Jacques & Ian Ruchlin*)\n", " + [Spinning Shifted Kerr-Schild black hole initial data](Tutorial-ADM_Initial_Data-ShiftedKerrSchild.ipynb) (*Courtesy George Vopal*)\n", " + [Brill-Lindquist initial data: Two-black-holes released from rest](Tutorial-ADM_Initial_Data-Brill-Lindquist.ipynb)\n", " + [Black hole accretion disk initial data (Fishbone-Moncrief)](Tutorial-FishboneMoncriefID.ipynb)\n", " + [**FishboneMoncriefID**: Setting up Fishbone-Moncrief disk initial data within the **Einstein Toolkit**, using HydroBase variables as input](Tutorial-ETK_thorn-FishboneMoncriefID.ipynb)\n", " + [Neutron Star initial data: The Tolman-Oppenheimer-Volkoff (TOV) solution](Tutorial-ADM_Initial_Data-TOV.ipynb) (*Courtesy Phil Chang*)\n", " + [Implementation of Single and Piecewise Polytropic EOSs](Tutorial-TOV-Piecewise_Polytrope_EOSs.ipynb) (*Courtesy Leo Werneck*)\n", "+ **ADM-to-curvilinear-BSSN initial data conversion**\n", " + [**Exact** ADM Spherical/Cartesian to BSSN Curvilinear Initial Data Conversion](Tutorial-ADM_Initial_Data-Converting_Exact_ADM_Spherical_or_Cartesian_to_BSSNCurvilinear.ipynb) (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.)\n", " + [**Start-to-Finish *exact* initial data validation notebook**](Tutorial-Start_to_Finish-BSSNCurvilinear-Setting_up_Exact_Initial_Data.ipynb): Confirms all exact initial data types listed above satisfy Einstein's equations of general relativity. (*Courtesy Brandon Clark & George Vopal*)\n", " + [**Numerical** ADM Spherical/Cartesian to BSSN Curvilinear Initial Data Conversion](Tutorial-ADM_Initial_Data-Converting_Numerical_ADM_Spherical_or_Cartesian_to_BSSNCurvilinear.ipynb) (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.)\n", " + [**Start-to-Finish *numerical* initial data validation notebook**: The TOV solution](Tutorial-Start_to_Finish-BSSNCurvilinear-Setting_up_TOV_initial_data.ipynb): 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](https://en.wikipedia.org/wiki/Tolman%E2%80%93Oppenheimer%E2%80%93Volkoff_equation), thus are known only numerically)\n", "+ **Diagnostic curvilinear BSSN modules**\n", " + [The gravitational wave Weyl scalar $\\psi_4$, in arbitrary curvilinear coordinates](Tutorial-Psi4.ipynb)\n", " + [Constructing the quasi-Kinnersley tetrad for $\\psi_4$](Tutorial-Psi4_tetrads.ipynb)\n", " + [Start-to-Finish validation of above expressions in Cartesian coordinates, against Patrick Nelson's Weyl Scalars & Invariants notebook](BSSN/Psi4Cartesianvalidation/Tutorial-Psi4-Cartesian_validation.ipynb)\n", " + [Spin-weighted spherical harmonics](Tutorial-SpinWeighted_Spherical_Harmonics.ipynb) (*Courtesy Brandon Clark*)\n", "\n", "+ **Start-to-Finish curvilinear BSSN simulation examples**:\n", " + [**Colliding black holes!**](Tutorial-Start_to_Finish-BSSNCurvilinear-Two_BHs_Collide.ipynb)\n", " + [The \"Hydro without Hydro\" test: evolving the spacetime fields of TOV star with $T^{\\mu\\nu}$ assumed static](Tutorial-Start_to_Finish-BSSNCurvilinear-Neutron_Star-Hydro_without_Hydro.ipynb)\n", " + [Gravitational collapse of a massless scalar field](Tutorial-Start_to_Finish-BSSNCurvilinear-ScalarField_Collapse.ipynb) (*Courtesy Leo Werneck*)\n", "\n", "### PART 5: Numerical Relativity $-$ General Relativistic Hydrodynamics (GRHD), Force-Free Electrodynamics (GRFFE), & Magnetohydrodynamics (GRMHD)\n", "\n", "+ [The equations of general relativistic hydrodynamics (**GRHD**), in Cartesian coordinates](Tutorial-GRHD_Equations-Cartesian.ipynb)\n", "+ [The equations of general relativistic, force-free electrodynamics (**GRFFE**), in Cartesian coordinates](Tutorial-GRFFE_Equations-Cartesian.ipynb)\n", "+ [The equations of general relativistic magnetohydrodynamics (**GRMHD**), in Cartesian coordinates](Tutorial-GRMHD_Equations-Cartesian.ipynb)\n", "+ [**`IllinoisGRMHD`** ](IllinoisGRMHD/doc/) with piecewise-polytrope/hybrid equation of state support (*Courtesy Leo Werneck*): ***In progress***\n", " + Diagnostic notebook: [**sbPoynETNRPy**: Evaluating $b^\\mu$ and $S^i$ in the **Einstein Toolkit**, using HydroBase variables as input](Tutorial-ETK_thorn-u0_smallb_Poynting.ipynb)\n", " + 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$](Tutorial-u0_smallb_Poynting-Cartesian.ipynb)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.5" } }, "nbformat": 4, "nbformat_minor": 2 }