Overview

RePrimAnd is a support library for numerical simulations of general relativistic magnetohydrodynamics and other neutron star related problems, written in C++ (a Python interface is also available)

The full documentation can be found here

Installation

The main target and devolpment platform is Linux, although the library code is not platform-specific and should also work on Macs. Windows and AIX are not supported. For use in HPC, users need to build the library from source. For use in postprocessing, the Python intferface can also be installed via pip (binary wheel of the library available for Linux). There is also an experimental conda package for the C++ library (Python interface not included yet).

Requirements

• A C++11 capable compiler (tested with gcc and clang).
• Meson build system.
• Boost library.
• GNU Scientific Library version >= 2.0
• HDF5 library (Only C-bindings required, not the C++ API).
• Doxygen (only for documentation)
• Sphinx with Breathe and bibtex extensions (only for documentation)
• Python matplotlib (only for benchmark plots)

Building from Source

The library is build using the modern Meson build system, which is available as standard package in most distributions and can also be installed via Python's pip.

To build the library,

cd <repository>
meson mbuild --buildtype=release --prefix=<custom install location>
ninja -C mbuild

This will compile with optimization and without debug symbols. Other possibilities are --buildtype=debug and --buildtype=debugoptimized To use a different compiler, e.g. clang, prefix the meson command with CC=clang CXX=clang++. See here for general Meson usage.

Note on Conda environments: if you build for a conda environment and meson does not detect the boost library or the wrong version, use

BOOST_ROOT=$CONDA_PREFIX meson setup --prefix=$CONDA_PREFIX mbuild

Note on HDF5: meson and hdf5 do not play along nicely (partly caused by bad hdf5 packaging). Make sure there is a pkg-config file for the version you want to build with. Another common cause is that you are building within a conda environment. In that case prefixing LD_LIBRARY_PATH with $CONDA_PREFIX/lib might help.

Installing

To install the library, use

ninja -C mbuild install

This will install in a user-defined location if the --prefix option was given during the build setup, otherwise systemwide (not recommended).

Using the Library

The various header files needed for using the library are installed in a subdirectory reprimand. The executables have to be linked with library RePrimAnd.

A minimal example can be found in example/minimal.cc. Assuming the library is installed where the compiler (below we use gcc as example) can find it, compilation should be straightforward:

g++ -lRePrimAnd --std=c++11 minimal.cc

Python Bindings

If only the Python interface is required on a Linux platform, it is easiest to install from pypi

pip install reprimand

Otherwise, one first has to buid and install the C++ library as shown above.

To build and install the Python interface, do

cd bindings/python
pip install .

This will also pip install packages numpy and pybind11>=2.6.0. When using conda environment, it may be better to install those first using conda.

The Python extension module is called pyreprimand.

Einstein Toolkit Support

RePrimAnd does provide a thorn that builds the library within an EinsteinToolkit (ET) environment, using the ExternalLibraries mechanism. The thorn is part of the official ET framework. The version in the master brach of this repository may however be ahead of the ET version. It can be found in the folder ET_interface/thorns/RePrimAnd/. The thorn depends on the HDF5, GSL, and BOOST ExternalLibraries thorns. Building it via the ET build system does not require meson. Note this only builds the library, but not the tests and Python bindings.

There are two experimental (and largely undocumented for now) thorns that aim to simplifying the usage. RePrimAnd_Global_EOS provides a centralized selection of a global thermal EOS (e.g. for evolution and analysis) and a global barotropic EOS (e.g. for initial data). RePrimAnd_EOS_Omni_API provides the most important subset of the EOS_Omni thorn interface, forwarding EOS calls to the reprimand EOS set by RePrimAnd_Global_EOS. It is intended for transitioning existing code to the new interface.

Creating Documentation

Building the documentation is deactivated by default. To build it, specify

meson configure -Dbuild_documentation=true

and then build the target documentation.

ninja documentation

The resulting pages can be found in the build directory under docsrc/sphinx/index.html.

The building of the documentation requires sphinx with the breathe and sphinxcontrib-bibtex extensions as well as doxygen.

If the documentation is build, it is installed automatically when installing the library, by default to <prefix>/usr/local/share/doc/libreprimand/index.html.

Running Tests

Unit tests

Building the unit tests is deactivated by default. To build them, specify

meson configure -Dbuild_tests=true

and then

ninja test

Please report errors on the issue tracker.

Benchmarks

The repository contains code to map the efficiency and accuracy of the primitive recovery, producing the plots shown in the article. To recreate the data and plots,

meson configure -Dbuild_benchmarks=true
ninja benchplots
ninja accuracyplots

The resulting pdf figures are placed in the build directory under tests/benchmarks.

This requires Python+matplotlib.

Visualizing Con2Prim Master Function

In addition, there is code to sample the primitive recovery master function (the central ingredient of the con2prim scheme) for various cases, as shown in the paper.

meson configure -Dbuild_benchmarks=true
ninja srootdata

The resulting data files are placed in the build directory under tests/sample_root/.