Odyssey: a GPU-based GRRT code

• About
• Summary of Source Codes
• Code Structure
• Code Structure: more details
• Credit
• Odyssey_Edu: an free educational software

About

Odyssey is a public, GPU-based General Relativistic Radiative Transfer (GRRT) code for computing images and/or spectra in Kerr metric, which described the spacetime aroung a rotating black hole. Implemented in CUDA C/C++, Odyssey is based on the ray-tracing algorithm presented in Fuerst & Wu (2004), and radiative transfer formulation described in Younsi, Wu, & Fuerst. (2012).

For flexibility, namespace structure in C++ is used for different tasks. Two default tasks are presented in the source code. Including :

1. The redshift of a Keplerian disk
2. The image of Keplerian rotating shell at 340GHz
(See the example results here)

Summary of Source Codes

Odyssey source code provided in the src folder includes the following files:

main.cpp assign parameters (black hole spin, inclinaiton angle, image size, observed frequency, CUDA configuration...), call Task, then save CUDA computed result to output file

task1.h declare namespace for Task1

task1.cpp define functions for setting up CUDA computation for Task1, including setDims(), PRE(), GPUcompute(), and AFTER()

task2.h declare namespace for Task2

task2.cpp define functions for setting up CUDA computation for Task2

Odyssey.cu describe job details of each specific Tasks, such as __global__ GPU_task1work(), __global__ GPU_task1work(). Computation result will return to main.cpp

Odyssey_def.h define constants (such as black hole mass, distance to the black hole),
and variables which will be saved in the GPU global memory during computation

Odyssey_def_fun.h define functions needed for:

• Ray-Tracing
such as initial conditions `initial()` , differential equations for geodesics, adaptive step size Runge-Kutta method `rk5()`
• Radiative Transfer
such as table of Bessel function of the second kind (for computation of thermal synchoron emission), unit conversion to Jansky or Luminosity (erg/sec)

Code Structure

The flow chart for the code structure of Odyssey is provided below.

In main.cpp, task1() is called by main(), then go through to

task1():
|---assign parameters
|
|---set CUDA configuration setDims()
|
|---allocate memory on device for input and output PRE()
|
|---compute number of grids, to cover the whole image plane
|
|---perform the for-loop for GRRT GPUcompute()
|
|---copy memory form device to host and free CUDA memory AFTER()
|
|---save result to ouput

Code Structure: more details

By calling GPUcompute(), the parallel computation will be performed according to the job-detials described inside __global__ GPU_task1work() in Odyssey.cu.

__global__ GPU_task1work():
|---setup initial condition initial()
|
|================Loop Start=====================
|--- update the ray backward in time by adaptive size, Runge-Kutta method rk5()

job-details:
   ex. when the ray hit the disk, compute the redshift
       (you can define a different job here)

|--- exit if the ray enters the black hole or moves outside the region of interest, otherwise, contine the Loop
|================Loop End=====================

Odyssey is fast, accurate, and flexible. Users can easiliy assign a different job by simply modifying the job-details.
Alternatively, users can also add a new Task (e.g., task 3) by following suggested recipe:

1. add file: task3.h
2. add file: task3.cpp
3. add subroutine: task3() in main.cpp
4. add related subroutines and describe job-details in Odyssey.cu

Credit

Odyssey is distributed freely under the GNU general public license. We ask that users of Odyssey cite the following paper in their subsequent scientific literature and publications which result from the use of any part of Odyssey:

"Odyssey: A Public GPU-based Code for General-relativistic Radiative Transfer in Kerr Spacetime"
by Hung-Yi Pu, Kiyun Yun, Ziri Younsi and Suk-Jin Yoon (2016 Astrophysical Journal 820, 105)

Odyssey_Edu: a free educational software

An educational software, Odyssey_Edu, is devloped together with Odyssey for visualizing the ray trajectories in the Kerr spacetime.