README.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "ae5bcca1",
   "metadata": {},
   "source": [
    "## EMRI\\_MC: A GPU-based code for Bayesian inference of EMRI waveforms\n",
    "\n",
    "This is a code developed by **Ippocratis D. Saltas and Roberto Oliveri** to perfrom parameter inference for Extreme Mass Ratio Inspirals (EMRIs) including propagation effects. It is designed to run on GPUs. For more information we refer to:  \n",
    "\n",
    "## 1. Modules\n",
    "\n",
    "On top of Python's usual **numpy** and **scipy** libraries, to run the code one needs the following modules: \n",
    "\n",
    "1. **cuda/cupy**: https://nvidia.github.io/cuda-python/install.html\n",
    "\n",
    "\n",
    "\n",
    "2. **emcee**: https://emcee.readthedocs.io/en/stable/user/install/\n",
    "\n",
    "\n",
    "\n",
    "3. **multiprocessing**: https://pypi.org/project/multiprocessing/\n",
    "\n",
    "\n",
    "4. **corner** or **seaborn** or anything similar: https://corner.readthedocs.io/en/latest/install/  https://seaborn.pydata.org/installing.html\n",
    "\n",
    "The cuda/cupy library provides the GPU functionality, emcee is the library with the MCMC sampler, multiprocessing is needed for parallelisation, and the corner/seaborn for producing the corner plots. \n",
    "\n",
    "## 2. Main files\n",
    "\n",
    "**global\\_parameters.py**: This module defines the values of physical constants in cgs units, the parameters of the fiducial model, geometrical parameters and initial conditions of the binary system, parameters for the ODE solver (e.g., integration time window and grid resolution), and MCMC-related definitions. It also defines the maximum number of orbital overtones $n\\_max$ in the computation of the waveform. A change in the number of the parameters in the MCMC requires adjusting the parameter vector in this module.  \n",
    "\n",
    "**waveform.py**: This module defines the set of kludge ODE equations, the waveform generator, and some GPU-related functionality.\n",
    "\n",
    "**mcmc.py**: This module defines the MCMC-related functions and the MCMC iterator.\n",
    "\n",
    "**propagation.py**: This module defines the functions needed for the propagation of the GW wave through the cosmological background in the presence of any modified gravity effects. \n",
    "\n",
    "**main.ipynb**: Assuming all parameters and fiducial values are properly defined as explained earlier, \n",
    "this Jupyter notebook calls the main functions to initiate the MCMC run, \n",
    "using the package $\\texttt{emcee}$. As a simple choice, we have currently set throughout the numerical computation \n",
    "the source location $\\{\\theta_S,\\phi_S\\} = \\{\\pi/4, 0\\}$, \n",
    "the orientation of the spin $\\{\\theta_K,\\phi_K\\} = \\{\\pi/8, 0\\}$, \n",
    "$\\alpha_{LSO} = 0$, the angle $\\lambda = \\pi/6$, \n",
    "the initial eccentricity $e_{LSO}=0.3$, and $\\gamma_{LSO} = 0$, $\\Phi_{LSO} = 0$, \n",
    "for the respective initial conditions. \n",
    "These can be straighforwardly modified in the file waveform.py.\n",
    "\n",
    "## 3. Running the code\n",
    "\n",
    "Running the code is particularly simple. Placing all files in the same folder, and setting up all parameters as explained above, one starts the notebook main.ipynb, and executes the cells. The first cell computes the fiducial model, and the second starts the MCMC run around the chosen fiducial. The MCMC results are stored in a text file - please make sure the path is defined appropriately. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c1d8499e-76c2-4c3e-907e-72e9fad8ab02",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}