SIM5 is a C library with a Python interface that contains a collection of routines for relativistic raytracing and radiation transfer in GR. It has a special focus on raytracing from accretion disks, tori, hot spots or any other 3D configuration of matter in Kerr geometry, but it can be used with any other metric as well. It can handle both optically thick and thin sources as well as transport of polarization of the radiation and helps to calculate the propagation of light rays from the source to an observer through a curved spacetime. It supports parallelization and runs on GPUs.
The library contains
- a selection of physical and unit conversion constants related to black hole disk accretion
- an implementation of relativistic thin disk model
- basic routines related to GR and Kerr geometry in particular
- routines for computing null geodesics and GR raytracing with polarization
The library is thread-safe and supports parallelization of the calculations at both CPUs (OpenMP/MPI) and GPUs (CUDA/OpenCL).
Acquire the source code by cloning the git repository
git clone https://github.com/mbursa/sim5
The C code does not have any external library dependencies except the standard system ones. Typically, it is enough to run
make
The compilation process creates a lib folder and puts two files there, sim5lib.c, sim5lib.h and sim5lib.o, which contain a complete C source code merged by the compiler process from all the individual source files in src folder. Use those files to statically link SIM5 in your code (most typical usage in C/C++ codes), see an example bellow.
The Python interface does have a few external dependecies and thus it does not compile by default when calling make. Before compiling the Python interface, make sure you have the following pre-requisities installed:
# python headers
apt install python-dev
# SWIG - a tool that connects C/C++ programs with high-level programming languages
apt install swigHaving those do
make pythonThe library can be directly used in C/C++ projects and with a proper interface it can be used also in other languages (Fortran, ...). It also works as a Python package making most of its functions accessible from Python scripts with no extra effort.
The most typical use of the code in a C/C++ project is to use static linking. Having a sample code that uses SIM5
#include <stdlib.h>
#include "sim5lib.h"
int main(int argc, char *argv[])
//***************************************************
{
double a, rms, rbh;
// for BH spin values from 0 to 1 print the radius of BH horizon and
// the location of the marginally stable orbit
for (a=0.0; a<1.0; a+=0.01) {
rbh = r_bh(a); // radius of the event horizon
rms = r_ms(a); // radius of the marginally stable orbit
fprintf(stderr, "%.4e %e %e\n", a, rbh, rms);
}
return 0;
}we compile the code with (assuming SIM5 is located in subfolder sim5 of the current directory and assuming make has been run on SIM5)
gcc kerr-orbits.c -o kerr-orbits -I./sim5/lib -L./sim5/lib ./sim5/lib/sim5lib.o -lmRefer to examples for further inspiration.
SIM5 can be used as a Python module, which allows its routines to be called from a Python script. It is enough to import sim5 in your script and call the member functions. Some care has to be taken when working with arrays and objects that are passed to SIM5 routines or returned from them. The SIM5 Python interface uses SWIG tool to make an interface between C and Python and you may refer to SWIG documentation to learn about how to do that.
A basic example of a Python script that calls SIM5 may look like this
import sys
import math
import sim5
bh_spin = 0.99 # BH spin parameter
bh_mass = 10.0 # BH mass in units of Solar mass
mdot = 0.1 # disk accreation rate in units of Eddington accreation rate
alpha = 0.1 # alpha parameter for viscosity
rout = 500 # outer disk boudary in units of gravitational radius
# setup a relativistic thin disk model
sim5.disk_nt_setup(bh_mass, bh_spin, mdot, alpha, 0)
print '# Flux from the accretion disk surface as a function of radius for Novikov-Thorne disk model'
print '# mdot =', sim5.disk_nt_mdot(), '[Mdot_Edd]; ', sim5.disk_nt_mdot()*bh_mass*sim5.Mdot_Edd/1e18, 'g/s'
print '# format: radius [GM/c2] local flux [erg/s/cm2]'
r = sim5.disk_nt_r_min()
while (r < rout):
print r, sim5.disk_nt_flux(r)
r = r * 1.05
#end of while This example assumes that SIM5 subfolder does exist in the same folder along with the script. If that is not the case, put a line specifying the path to SIM5 library before the import statement.
sys.path.append('/path/to/sim5')
import sim5
...Python calls to SIM5 routines are handled by the compiled C code in lib/sim5lib.so library. Although there is some overhead connected with the call to SIM5 routines, the actual evaluation of SIM5 functions is as fast as C code can be. This makes complex tasks (like raytracing) reasonably fast even if they are coded in Python (see examples in demo folder).
tbd
As the library is a collection of routines, it does not have any parallelization built in itself, but it is very easy to write CPU/GPU parallel code with it. SIM5 uses strict encapsulation and all its functions use only the data that is passed in as parameters; there are no global variables in the library. This allows to write thread-safe codes that can be straightforwardly parallelized. Examples for OpenMP, MPI and CUDA parallelization are provided in the examples folder.
Documentation for the library is generated automatically (by Doxygen) from the comments in the source code. See doc/sim5lib-doc.md for the compiled file with a list of routines and constants.
If you want to refer to SIM5 in your paper, please give the following reference: Bursa, M. 2017, Proceedings of Ragtime 17-19: Workshops on Black Holes and Neutron Stars, p.7 [ADS link]
If you have used SIM5 in your code or used a code that itself is using SIM5, please acknowledge the use of the software by citing its ASCL record: ascl:1811.011.
SIM5 is released under the MIT License.