examples/example_3dq8.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example usage of NRSur3dq8Remnant fit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import surfinBH"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "fit_name = 'NRSur3dq8Remnant'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load the fit, this only needs to be done once at the start of a script"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Loaded NRSur3dq8Remnant fit.\n"
     ]
    }
   ],
   "source": [
    "fit = surfinBH.LoadFits(fit_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Read the documentation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on Fit3dq8 in module surfinBH._fit_evaluators.fit_3dq8 object:\n",
      "\n",
      "class Fit3dq8(surfinBH.surfinBH.SurFinBH)\n",
      " |  A class for the NRSur3dq8Remnant model presented in Varma et al.,\n",
      " |  arxiv:1809.09125. This model is referred to as surfinBH3dq8 in the paper.\n",
      " |  \n",
      " |  This model predicts the final mass mf, final\n",
      " |  spin chif and final kick velocity vf, for the remnants of nonprecessing\n",
      " |  binary black hole systems. The fits are done using Gaussian Process\n",
      " |  Regression (GPR) and also provide an error estimate along with the fit\n",
      " |  value.\n",
      " |  \n",
      " |  This model has been trained in the parameter space:\n",
      " |      q <= 8, |chiAz| <= 0.8, |chiBz| <= 0.8\n",
      " |  \n",
      " |  However, it extrapolates reasonably to:\n",
      " |      q <= 10, |chiAz| <= 1, |chiBz| <= 1\n",
      " |  \n",
      " |  =========================================================================\n",
      " |  Usage:\n",
      " |  \n",
      " |  import surfinBH\n",
      " |  \n",
      " |  # Load the fit\n",
      " |  fit = surfinBH.LoadFits('NRSur3dq8Remnant')\n",
      " |  \n",
      " |  We provide the following call methods:\n",
      " |      # remnant mass and 1-sigma error estimate\n",
      " |      mf, mf_err = fit.mf(q, chiA, chiB, **kwargs)\n",
      " |  \n",
      " |      # remnant spin and 1-sigma error estimate\n",
      " |      chif, chif_err = fit.chif(q, chiA, chiB, **kwargs)\n",
      " |  \n",
      " |      # remnant recoil kick and 1-sigma error estimate\n",
      " |      vf, vf_err = fit.vf(q, chiA, chiB, **kwargs)\n",
      " |  \n",
      " |      # All of these together\n",
      " |      mf, chif, vf, mf_err, chif_err, vf_err\n",
      " |          = fit.all(q, chiA, chiB, **kwargs)\n",
      " |  \n",
      " |  The arguments for each of these call methods are as follows:\n",
      " |  Arguments:\n",
      " |      q:      Mass ratio (q>=1)\n",
      " |  \n",
      " |      chiA:   Dimensionless spin of the larger BH (array of size 3).\n",
      " |  \n",
      " |      chiB:   Dimensionless spin of the smaller BH (array of size 3).\n",
      " |              This model allows only nonprecessing spins, so only the\n",
      " |              z-components of these arrays should be non-zero.\n",
      " |  \n",
      " |  Optional arguments:\n",
      " |      allow_extrap:\n",
      " |          If False, raises a warning when q > 8.1 or |chiA|,|chiB| > 0.81,\n",
      " |              and raises an error when q > 10.1 or |chiA|,|chiB| > 1.\n",
      " |          If True, allows extrapolation to any q and |chiA|,|chiB| <= 1.\n",
      " |              Use at your own risk.\n",
      " |          Default: False.\n",
      " |  \n",
      " |  The spin and kick vectors are defined in the coorbital frame at t=-100 M\n",
      " |  from the peak of the waveform. This frame is defined as:\n",
      " |  The z-axis is along the orbital angular momentum direction of the binary.\n",
      " |  The x-axis is along the line of separation from the smaller BH to\n",
      " |      the larger BH at this time.\n",
      " |  The y-axis completes the triad.\n",
      " |  We obtain this frame from the waveform as defined in arxiv:1705.07089.\n",
      " |  \n",
      " |  Method resolution order:\n",
      " |      Fit3dq8\n",
      " |      surfinBH.surfinBH.SurFinBH\n",
      " |      __builtin__.object\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __init__(self, name)\n",
      " |      #-------------------------------------------------------------------------\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Methods inherited from surfinBH.surfinBH.SurFinBH:\n",
      " |  \n",
      " |  all(self, *args, **kwargs)\n",
      " |      Evaluates fit and 1-sigma error estimate for remnant mass, spin\n",
      " |      and kick velocity.\n",
      " |      Returns:\n",
      " |          mf, chif, vf, mf_err_est, chif_err_est, vf_err_est\n",
      " |      \n",
      " |      chif, vf, chif_err_est and vf_err_est are arrays of size 3.\n",
      " |  \n",
      " |  chif(self, *args, **kwargs)\n",
      " |      Evaluates fit and 1-sigma error estimate for remnant spin.\n",
      " |      Returns:\n",
      " |          chif, chif_err_est\n",
      " |      \n",
      " |      chif and chif_err_est are arrays of size 3.\n",
      " |  \n",
      " |  mf(self, *args, **kwargs)\n",
      " |      Evaluates fit and 1-sigma error estimate for remnant mass.\n",
      " |      Returns:\n",
      " |          mf, mf_err_est\n",
      " |  \n",
      " |  vf(self, *args, **kwargs)\n",
      " |      Evaluates fit and 1-sigma error estimate for remnant kick velocity.\n",
      " |      Returns:\n",
      " |          vf, vf_err_est\n",
      " |      \n",
      " |      vf and vf_err_est are arrays of size 3.\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data descriptors inherited from surfinBH.surfinBH.SurFinBH:\n",
      " |  \n",
      " |  __dict__\n",
      " |      dictionary for instance variables (if defined)\n",
      " |  \n",
      " |  __weakref__\n",
      " |      list of weak references to the object (if defined)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(fit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Evaluate the fits"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "q = 4.3             # Mass ratio q>=1\n",
    "chiA = [0,0,0.6]    # Spin of larger BH (z-direction only)\n",
    "chiB = [0,0,-0.7]   # Spin of smaller BH (z-direction only)\n",
    "\n",
    "## Evaluate the fits and GPR error estimate.\n",
    "\n",
    "# remnant mass and 1-sigma error estimate\n",
    "mf, mf_err = fit.mf(q, chiA, chiB)\n",
    "\n",
    "# remnant spin and 1-sigma error estimate\n",
    "chif, chif_err = fit.chif(q, chiA, chiB)\n",
    "\n",
    "# remnant recoil kick and 1-sigma error estimate\n",
    "vf, vf_err = fit.vf(q, chiA, chiB)\n",
    "\n",
    "# All of these together\n",
    "mf, chif, vf, mf_err, chif_err, vf_err = fit.all(q, chiA, chiB)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}