Arcmancer is a general purpose header-only C++14 library for computing
geodesics and performing polarized radiative transfer in user specified
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
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.
- 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.
To use Arcmancer, you should have the following tools installed on your system:
GNU Make or equivalent.
Required for API documentation.
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
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
python3-dev, depending on the Python version used.
Optional, only required for the example programs.
Optional, only required for the example programs.
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
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)
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
(e.g. when calling
-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
It is also possible use the main C++ library without
in which case all the
necessary include paths need to be specified manually.
However, the recommended way is to use
If multiple versions of Python are installed on the system, it is possible to to build
pyarcmanceragainst a specific one of these by adding the flag
If Boost is not found, try setting
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.
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
and the other examples for details.
The python bindings can be used by adding the lib subdirectory to
or by copying
lib/pyarcmancer.* to a directory on the python module search
Documentation and Examples
doxygen is installed on the system, the main build process generates HTML
documentation for the library.
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.
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).
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.
The following third-party libraries are included with Arcmancer:
The respective licences of these libraries are listed in the file thirdparty/LICENSES.md.