NRPy 2: Python/SymPy-Based Code Generation for Numerical Relativity... and Beyond!

Quick start, Step 1:

pip install nrpy

Quick start, Step 2: Choose a project to build.

BlackHoles@Home infrastructure (standalone): Choose a project, run the provided command, then follow the instructions for compiling & running the generated C code.

• Wave equation solver
  • Cartesian coordinates:

    python3 -m nrpy.examples.wave_equation_cartesian
    

  • Curvilinear coordinates:

    python3 -m nrpy.examples.wave_equation_curvilinear
    

• General relativity
  • Two black holes collide:

    python3 -m nrpy.examples.two_blackholes_collide
    

  • Black hole spectroscopy:

    python3 -m nrpy.examples.blackhole_spectroscopy
    

  • Spinning black hole:

    python3 -m nrpy.examples.spinning_blackhole
    

  • Binary black hole initial data, courtesy NRPyElliptic:

    python3 -m nrpy.examples.nrpyelliptic_conformally_flat
    

Einstein Toolkit infrastructure: Choose a project to build, run the provided command. Check the examples/et_* directory for a ThornList and parameter file. Thorns will be output to project/

• Wave equation solver
  • Cartesian coordinates, with Carpet AMR infrastructure:

    python3 -m nrpy.examples.carpet_wavetoy_thorns
    

• General relativity: Generate Baikal and BaikalVacuum thorns
  • Cartesian coordinates, with Carpet AMR infrastructure:

    python3 -m nrpy.examples.carpet_baikal_thorns
    

superB infrastructure: Choose a project, run the provided command, then follow the instructions for installing Charm++, compiling and running the generated C++ code.

• General relativity
  • Two black holes collide:

    python3 -m nrpy.examples.superB_two_blackholes_collide
    

Quick Start, Step 3

1. If working with a BlackHoles@Home project: follow the directions at the end of the code generation, starting with "Now go into [directory name] and type make to build, then [executable] to run. Parameter file can be found in [parameter filename]."
2. Parameter files are text files, making it easy to adjust simulation parameters.
3. In addition, parameters can be set at the command line. For example, wavetoy has a parameter convergence_factor that increases the resolution (technically Nx=Ny=Nz) by this factor. To output at twice the resolution, simply run ./wavetoy 2.0, and a new file will be output out0d-conv_factor2.00.txt, which contains data at 2x the resolution.
4. Analyze the output from out0d-conv_factor1.00.txt and out0d-conv_factor2.00.txt in e.g., gnuplot.
5. If working with an Einstein Toolkit project, the output will be Einstein Toolkit modules (thorns). You'll want to either copy or link them to an arrangement in arrangements/[subdirectory]/, then add the thorns to your ThornList, and compile.
6. If working with a superB project, Install Charm++ following the instructions in Charm++ documentation. Then, go to project/superB_two_blackholes_collide and open the Makefile. Replace "~/charm" in CC = ~/charm/bin/charmc with the path to your Charm++ installation directory. Type make to build. Type ./charmrun +p4 ./superB_two_blackholes_collide to run with 4 processors, for example. As in a BlackHoles@Home project parameters can be changed and output from out0d-conv_factor1.00.txt and out0d-conv_factor2.00.txt can be analyzed using e.g., gnuplot.

Contributing to NRPy 2

Want to contribute to NRPy 2? Great! First clone the NRPy 2.0 repo:

git clone https://github.com/nrpy/nrpy.git

Next, you'll want to make sure your development environment is consistent with what GitHub Actions expects:

cd nrpy
pip install -U -r requirements-dev.txt

Finally, to run anything in the NRPy repo, you'll need to set your PYTHONPATH appropriately. If you're using bash, attach the following line to the bottom of your .bashrc file:

export PYTHONPATH=$PYTHONPATH:.

Once this is set up, you can run any Python script in the NRPy 2 repo from the repository's root directory. For example,

python3 nrpy/helpers/cse_preprocess_postprocess.py

will run all the doctests in that file.

Key Improvements over nrpytutorial version of NRPy (NRPy 1):

Easy Installation

• NRPy has been transformed into a proper Python project and can now be installed via pip! Use the command pip install nrpy to get started.
• Visit our PyPI page for more information.
  • With pip, it's easier than ever to build your own projects based on NRPy.
  • You can now generate a complete C project from start to finish without the need for running a Jupyter notebook.
    • For instance, running pip install nrpy && python3 -m nrpy.examples.two_blackholes_collide will generate a C code project that evolves Brill-Lindquist forward in time using the BSSN formulation.
  • Check out GitHub README for instructions on generating other pre-baked example codes... or use them to generate your own codes!

Python 3.6+ Features

• NRPy now makes use of Python features introduced in version 3.6 and above, such as f-strings.
• The code is now more Pythonic and incorporates objects where useful. Global variables are now a thing of the past!

User-friendly

• It's much simpler to work with NRPy now; you no longer have to read the source code of each function you call.
  • Facilitating this, you'll find:
    • Docstrings for all functions, classes, and modules.
    • Type hints across all modules; mypy --strict passes.
    • Numerous doctests.
    • Code formatted with Black.
    • Stricter linting.

Improved Continuous Integration

• GitHub Actions now checks all files within the repo and will fail if any of the following conditions are met:
  • Doctest failure
  • pylint score less than 9.5
  • Black needs to reformat any .py file
  • mypy --strict fails on any .py file
  • Generating and compiling all examples from the pip-installed NRPy fresh from the latest git commit fails.

More Extensible

• The "SENR" infrastructure has been replaced with "BHaH" (BlackHoles@Home). All BHaH-specific functionality is located in nrpy/infrastructures/BHaH/.
  • While BHaH currently only supports single grids, multi-patch support will be added soon.
  • You'll notice the old paramstruct has been broken into commondata_struct (data shared by all grids) and griddata (contains data specific to a particular grid).
    • Adding multi-patch support is a matter of setting commondata.NUMGRIDS > 1 and all the special algorithms.
  • There is a common but slightly customizable main.c file used by all BHaH codes, see nrpy/infrastructures/BHaH/main_c.py. This should greatly minimize code duplication in BHaH codes.
  • Parameter files are now supported, as well as advanced command-line input.
  • The infrastructures/ directory includes helper functions for specific infrastructures. It currently contains BHaH and CarpetX subdirectories, with more to come.
  • Cparameters has been renamed to CodeParameters, allowing for future extensions of NRPy to output kernels in Python, Fortran, etc.
  • Rewritten expression validation infrastructure, to make it easier to validate newly added sympy expressions -- regardless of how complex they are.

Plans for Old nrpytutorial Code

• We'll migrate the Jupyter notebooks to a new nrpytutorial GitHub repo as they are updated to NRPy 2.
• All the core .py files from nrpytutorial have been modernized & ported to NRPy 2.
• What .py files remain in nrpytutorial will be ported to NRPy 2.