README.md

The MCRaT Code

MCRaT (pronounced _Em-Cee-Rat_ ) code is a next generation radiation transfer code that can be used to analyze the radiation signature expected from hydrodynamically simulated astrophysical outflows.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgements

About The Project

With advances in simulating astrophysical fluid flows and radiative transfer simulations through the flows, MCRaT represents a next generation radiative transfer simulation that conducts radiative calculations using the background of realistic fluid flow profiles that have been acquired from hydrodynamically simulated outflows. Although MCRaT has primarily been used to study the emission from Gamma Ray Burst jets, it can also be used to study the emission from other astrophysical phenomenon such as jets from Active Galactic Nuclei and Tidal Disruption Events.

MCRaT injects photons into a hydrodynamic simulation of an outflow and calculates the evolution of the trapped radiation within the fluid until the end of the hydrodynamic simulation. In simulating the radiation, MCRaT takes a number of physical processes into account including:

• Compton Scattering
• The Klein–Nishina Cross Section Including the Effects of Polarization
• Cyclo-synchrotron Emission and Absorption

Once the MCRaT calculations have completed, users can construct mock observed light curves, spectra, and polarization measurements from the MCRaT results using the ProcessMCRaT package.

Currently, MCRaT can be used to analyze the output of FLASH and PLUTO hydrodynamic simulations in the specified dimensions and coordinate systems:

• FLASH
  • 2D: Cartesian and Cylindrical
• PLUTO (.dbl files only) and PLUTO-Chombo
  • 2D/2.5D: Cartesian, Cylindrical, and Spherical
  • 3D: Cartesian, Polar, and Spherical

Additionally, MCRaT can analyze PLUTO and PLUTO-Chombo magneto-hydrodynamic simulations in the same dimensions and coordinate systems specified above.

Built With

• Message Passing Interface (MPI)
• OpenMP
• The GNU Scientific Library (GSL)
• The HDF5 library

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

The following are necessary to compile the MCRaT code and should be installed in the manner that each packages specifies:

• GCC or ICC
• Message Passing Interface (MPI)
• OpenMP -- typically comes with the GCC or ICC compiler
• The GNU Scientific Library (GSL)
• The HDF5 library -- need to install the serial and parallel versions (v1.10 and greater)

In addition to the above, you will also need a hydrodynamical simulation that you want to calculate radiation from. Currently, this can be a FLASH, PLUTO, or PLUTO-Chombo simulation with dimensions and coordinates previously specified.

Installation

1. Clone the repo

   git clone https://github.com/lazzati-astro/MCRaT.git

2. Copy one of the template Makefile files into the Src/ directory and rename it Makefile if necessary. The file named Makefile is a template for a smaller compute cluster while the file named Makefile_supercomputer is a template for compiling MCRaT on a supercomputer using icc.

   cp Makefile_supercomputer Src/Makefile 

3. Modify the Makefile to specify the location of the installed prerequisite libraries that are needed to compile MCRaT. In some rare cases this may not need to be done if the system that the user is on uses modules and paths are set correctly.
4. Set the necessary parameters in the mcrat_input.h file and the mc.par file for the hydrodynamics simulations that MCRaT is using and the physical processes that the user wants MCRaT to consider
5. Compile the code by running

   make 

6. Run the MCRaT code using mpiexec

These steps are provided in greater detail in the Documentation

Usage

The typical MCRaT workflow is as follows:

1. Compile MCRaT as was briefly mentioned in the previous section
2. Run the MCRaT code
3. Process the output of the MCRaT calculations using the included Merge code
4. Use the ProcessMCRaT library to produce mock observed light curves, spectra, and polarization measurements for the simulated astrophysical outflow

The video below shows an example of MCRaT scattering photons through a Gamma Ray Burst jet. MCRaT allows us to track the evolution fo the photon spectrum as they photons propagate through the jet and as the jet propagates through space. Additionally, we can keep track of how well the photons are in equilibrium with the matter in the jet, as indicated by the effective temperatures.

For more details, please refer to the Documentation

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Tyler Parsotan - Personal Website - [email protected]

Project Link: https://github.com/lazzati-astro/MCRaT

Acknowledgements

• In using MCRaT and the ProcessMCRaT codes, we ask that you cite the following papers:
  • Lazzati (2016)
  • Parsotan & Lazzati (2018)
  • Parsotan et al. (2018)
  • Parsotan et. al. (2020)
• The code was initially written in python by Dr. Davide Lazzati as a proof of concept. The code was then translated into C by Tyler Parsotan and made to use the OpenMP, MPI, HDF5, and GNU Scientific libraries.
• README Template from: othneildrew/Best-README-Template