NRPyPlus_Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img height=\"60px\" src=\"https://blackholesathome.net/images/NRPyPlusLogo.png\" align=\"center\" hspace=\"20px\" vspace=\"5px\">\n",
    "<script async src=\"https://www.googletagmanager.com/gtag/js?id=UA-59152712-8\"></script>\n",
    "<script>\n",
    "  window.dataLayer = window.dataLayer || [];\n",
    "  function gtag(){dataLayer.push(arguments);}\n",
    "  gtag('js', new Date());\n",
    "\n",
    "  gtag('config', 'UA-59152712-8');\n",
    "</script>\n",
    "\n",
    "## The NRPy+ Tutorial: An Introduction to Python-Based Code Generation for Numerical Relativity... and Beyond!\n",
    "\n",
    "### Lead author: [Zachariah B. Etienne](https://etienneresearch.com) $\\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://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Notebook%20Basics.html).***\n",
    "\n",
    "### PART 1: Basic Functionality of NRPy+, a First Application\n",
    "##### NRPy+ Basics\n",
    "+ [NRPy+: Introduction & Motivation](https://nrpyplus.net) (NRPy+ home page)\n",
    "+ [NRPy+: 10-minute Overview](Tutorial-NRPyPlus_10_Minute_Overview.ipynb) $\\leftarrow$ **Start here**\n",
    "+ [Solving the scalar wave equation with `NumPy`](Tutorial-Solving_the_Scalar_Wave_Equation_with_NumPy.ipynb) $\\leftarrow$ **Then go here** (fully worked example of a hyperbolic PDE solver, written in pure Python)\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",
    "+ 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 <font color='green'>**Einstein Toolkit**</font> (*Courtesy Patrick Nelson & Terrence Pierre Jacques*)\n",
    "        + [<font color='green'>**IDScalarWaveNRPy**</font>: Initial data for the scalar wave equation](Tutorial-ETK_thorn-IDScalarWaveNRPy.ipynb) \n",
    "        + [<font color='green'>**WaveToyNRPy**</font>: Solving the scalar wave equation, using the method of lines](Tutorial-ETK_thorn-WaveToyNRPy.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",
    "    + [<font color='green'>**WeylScal4NRPy**</font>: An <font color='green'>**Einstein Toolkit**</font> 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 (<font color='red'>**in progress**</font>)\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",
    "### 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",
    "\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",
    "        + [<font color='green'>**FishboneMoncriefID**</font>: Setting up Fishbone-Moncrief disk initial data within the <font color='green'>**Einstein Toolkit**</font>, 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",
    "+ **BSSN initial data reader**\n",
    "    + [Initial Data Reader/Converter: ADM Spherical/Cartesian to BSSN-with-a-reference-metric](Tutorial-ADM_Initial_Data_Reader__BSSN_Converter.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-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",
    "        + [**Start-to-Finish *numerical* initial data validation notebook**: The TOV solution](Tutorial-Start_to_Finish-BSSNCurvilinear-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",
    "    + [<font color='purple'>**Colliding black holes!**</font>](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",
    "\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",
    "    + [Derivation of the GRMHD evolution equations from $T^{\\mu\\nu}$ in our formalism](Tutorial-Derivation_of_GRMHD_Evolution_Equations.ipynb)\n",
    "+ [**`IllinoisGRMHD`** ](IllinoisGRMHD/doc/) with piecewise-polytrope/hybrid equation of state support (*Courtesy Leo Werneck*): <font color='red'>***In progress***</font>\n",
    "    + Diagnostic notebook: [<font color='green'>**sbPoynETNRPy**</font>: Evaluating $b^\\mu$ and $S^i$ in the <font color='green'>**Einstein Toolkit**</font>, 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 (ipykernel)",
   "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.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}