HTTPS SSH

Arcmancer

Arcmancer is a general purpose header-only C++14 library for computing
geodesics and performing polarized radiative transfer in user specified
spacetimes.
The library includes high-level constructs which allow quickly defining
relativistic ray-tracing computations and provides generic implementations
of basic differential geometric objects that allow the implementation of
more complex procedures.
In addition to the C++ library, most of the main features are also available
through the pyarcmancer Python module, which allows combining the convenience
of Python with the speed of the C++ code.

While the main focus of Arcmancer is on general relativistic polarized radiative
transfer, it also offers various features that are applicable in very general
contexts.
The main features of Arcmancer include:

  • User defined (Pseudo-)Riemannian manifolds:

    • Arbitrary dimension, not limited to 4D spacetimes.
    • Multiple coordinate systems at once.
    • Support for both spacetime signature conventions, i.e. (+---) and (-+++)
    • Simple to define: only need to specify functions for the metric and its.
      derivatives, and potentially the coordinate system transitions.
  • General tensors:

    • Automatic conversion of components between coordinate systems.
    • Type checked tensor index operations.
      Tensor index types (covariant/contravariant) are known at compile time
      and checked to ensure mathematical validity of operations.
    • Parallel transport along curves.
  • Geodesics and Curves:

    • Accurate solution of the curve equation of motion using adaptive
      integration with configurable tolerances.
    • Support for curves with an arbitrary acceleration term.
    • Transport of objects along curves during curve computation.
      Includes e.g. the parallel transport of tensors, but custom objects are
      also supported.
    • Interpolation of points at arbitrary values of curve parameter.
    • Solution of differential equations along precomputed curves.
  • Polarized Radiative Transfer:

    • Solution of the polarized radiative transfer equation along null geodesic
      rays. Multiple frequencies can be computed at once.
    • Simple interface for defining the fluid and radiation content: just
      implement two functions / functor objects.
    • Generic tools for generating ray initial conditions and performing
      parallel computation over the image.

For more details and results from some example computations performed using
Arcmancer see the code paper.

Getting Started

Prerequisites

To use Arcmancer, you should have the following tools installed on your system:

Additionally, the following libraries are required:

  • Boost C++ Libraries v1.53+
    Only header-only components are used in the main library,
    the example programs additionally use ProgramOptions.

  • HDF5 C++ libraries
    Known to work at least with version 1.8.16.

  • UnitTest++ (a.k.a. unittest-cpp) v2.0+
    Optional, only required for running the tests.

  • Python development headers
    On Linux these are usually included in either python-dev or python3-dev,
    depending on the Python version used.

  • NumPy (v1.7.0+)

  • Matplotlib
    Optional, only required for the example programs.

  • H5py
    Optional, only required for the example programs.

Cloning/Downloading

The best way of getting the library is to simply clone the git repository with

git clone --recurse-submodules https://bitbucket.org/popiha/arcmancer.git

This ensures that the git submodule bringing in
the pybind11 library is also initialized correctly.
The most recently released stable version of Arcmancer is on the master
branch, which is selected by default.

The Bitbucket page also allows downloading
released versions of the library without fetching the whole history.
However, in this case you must manually add the correct version of pybind11
(the version the submodule points to)
under pyarcmancer/pybind11 in order to compile the Python bindings.

Configuring and Building

To configure and build the project run the following commands

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make

This will build the pyarcmancer Python bindings for Arcmancer,
the library API documentation and the unit tests,
as well as generating a CMake target file which can be used by other projects
to conveniently add a dependency on Arcmancer.

It may be necessary to manually specify paths to some external libraries.
In this case the error messages should contain the necessary details,
but also see below.

Additional compiler flags (e.g. -march=native for more efficient code) can
be specified using CMAKE_CXX_FLAGS variable
(e.g. when calling cmake add -DCMAKE_CXX_FLAGS="-march=native" to the call).

You can also build only specific targets, in case not all of them are necessary.
For a list of all possible build targets, use the command make help.

It is also possible use the main C++ library without CMake,
in which case all the
necessary include paths need to be specified manually.
However, the recommended way is to use CMake.

CMake troubleshooting

  • If multiple versions of Python are installed on the system, it is possible to
    to build pyarcmancer against a specific one of these by adding the flag
    -DPYTHON_EXECUTABLE=path/to/python to the cmake call.

  • If Boost is not found, try setting -DBOOST_ROOT=path/to/boost.

  • Similarly, for HDF5 libraries and header files, set
    -DHDF5_ROOT=path/to/hdf5-libraries. This is particularly necessary,
    if there are several HDF5 libraries installed on the system, e.g. with
    a Python distribution, as CMake can easily confuse these, which may
    break the build.

Installing

At the moment we do not provide an install method integrated into the build
system, but using the library is still fairly straightforward.

The header library can be used in an external project with CMake,
see examples/example_project
and the other examples for details.

The python bindings can be used by adding the lib subdirectory to PYTHONPATH
or by copying lib/pyarcmancer.* to a directory on the python module search
path.

Documentation and Examples

If doxygen is installed on the system, the main build process generates HTML
documentation for the library.
Open docs/doxygen/html/index.html to view this documentation.

The examples directory contains various examples of using
Arcmancer both as a C++ library as well as through the Python bindings.
These examples are built separately, see their respective READMEs for more
details.

Note that most of the Python code in the examples
has been tested using Python 3,
and may require small modifications to function correctly if used with
Python 2.

License

This project is licensed under the MIT License.
See the LICENSE file for details.

If work utilizing Arcmancer results in a scientific publication,
please cite the code paper Pihajoki et al. (2018).

Contributing

If you detect bugs or have feature requests, please submit an issue on the
project Bitbucket page.
You may also submit pull requests for code features you have implemented.

Third-Party Libraries

The following third-party libraries are included with Arcmancer:

The respective licences of these libraries are listed in the file
thirdparty/LICENSES.md.