New fits NRSur3dq8BMSRemnant

examples/example_3dq8BMS.ipynb

@@ -0,0 +1,256 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Example usage of NRSur3dq8BMSRemnant fit."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import surfinBH"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fit_name = 'NRSur3dq8BMSRemnant'"
+   ]
+  },
+  {
+   "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 NRSur3dq8BMSRemnant 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 Fit3dq8BMS in module surfinBH._fit_evaluators.fit_3dq8BMS object:\n",
+      "\n",
+      "class Fit3dq8BMS(surfinBH.surfinBH.SurFinBH)\n",
+      " |  Fit3dq8BMS(name)\n",
+      " |\n",
+      " |  A class for the NRSur3dq8BMSRemnant model presented in Da Re et al.,\n",
+      " |  arxiv:????.?????. This model is referred to as surfinBH3dq8BMS in the paper.\n",
+      " |\n",
+      " |  This model predicts the proper supertransation modes up to ell = 8 and the\n",
+      " |  3 components of the boost velocity of the BMS transformation from the inspiral (PN)\n",
+      " |  BMS frame to the remnant black hole BMS frame. The model was trained on 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",
+      " |  =========================================================================\n",
+      " |  Usage:\n",
+      " |\n",
+      " |  import surfinBH\n",
+      " |\n",
+      " |  # Load the fit\n",
+      " |  fit = surfinBH.LoadFits('NRSur3dq8BMSRemnant')\n",
+      " |\n",
+      " |  #To evaluate the supertranslation parameter alpha and the boost_velocity together with their respective 1-sigma error estimates call:\n",
+      " |  alpha, boost_vel,  alpha_err, boost_vel_err = fit.all(q, chiA, chiB, **kwargs)\n",
+      " |\n",
+      " |  # NOTE: the modes with ell=0,1 corresponding to a Poincaré translation, depend on the location of\n",
+      " |    the center-of-mass at the specific mapping times used to fix the BMS frames and thus carry\n",
+      " |    no physical significance. Consequently they are set to be identically zero.\n",
+      " |\n",
+      " |  # alpha is expressed as a complex array of spherical harmonics modes in the order (0,0),(1,-1),(1,0),(1,1),(2,-2),(2,-1),(2,0),...\n",
+      " |    (same convention as the spherical_functions and scri packages)\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",
+      " |      Fit3dq8BMS\n",
+      " |      surfinBH.surfinBH.SurFinBH\n",
+      " |      builtins.object\n",
+      " |\n",
+      " |  Methods defined here:\n",
+      " |\n",
+      " |  __init__(self, name)\n",
+      " |      name: Name of the fit excluding the surfinBH prefix. Ex: 7dq2.\n",
+      " |      soft_param_lims: param limits beyond which to raise a warning.\n",
+      " |      hard_param_lims: param limits beyond which to raise an error.\n",
+      " |      aligned_spin_only: raise an error if given precessing spins.\n",
+      " |      See _fit_evaluators.fit_7dq2.py for an example.\n",
+      " |\n",
+      " |  all(self, *args, **kwargs)\n",
+      " |      Evaluates fit and 1-sigma error estimate for supertranslation parameter alpha, and boost velocity\n",
+      " |      of the BMS transformation from the inspiral BMS frame to the remnant BMS frame\n",
+      " |      Returns:\n",
+      " |          alpha, boost_vel,  alpha_err, boost_vel_err\n",
+      " |\n",
+      " |  chif(self, *args, **kwargs)\n",
+      " |      chif is not implemented in this model. Will return (None, None),\n",
+      " |\n",
+      " |  mf(self, *args, **kwargs)\n",
+      " |      mf is not implemented in this model. Will return (None, None),\n",
+      " |\n",
+      " |  vf(self, *args, **kwargs)\n",
+      " |      vf is not implemented in this model. Will return (None, None),\n",
+      " |\n",
+      " |  ----------------------------------------------------------------------\n",
+      " |  Data descriptors inherited from surfinBH.surfinBH.SurFinBH:\n",
+      " |\n",
+      " |  __dict__\n",
+      " |      dictionary for instance variables\n",
+      " |\n",
+      " |  __weakref__\n",
+      " |      list of weak references to the object\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "help(fit)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Evaluate the fits"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(0.011456326974619718+0j)"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "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",
+    "#this model fits the supertranslation parameter alpha and the boost \n",
+    "#velocity v associated to the BMS transformation from the PN BMS frame to\n",
+    "#the remnant BMS frame\n",
+    "\n",
+    "# Outputs:\n",
+    "# - supertranslation parameter alpha and 1-sigma error estimate alpha_err\n",
+    "#   NOTE: alpha is a complex array. Each component is a spherical harmonic mode of alpha\n",
+    "#     the order of the modes in the array is (0,0),(1,-1),(1,0),(1,1),(2,-2),(2,-1),(2,0),(2,1),(2,2),...\n",
+    "#     (same order used in spherical_functions and scri package)\n",
+    "# - boost velocity and 1-sigma error estimate boost_vel_err\n",
+    "\n",
+    "alpha, boost_vel, alpha_err, boost_vel_err = fit.all(q, chiA, chiB)\n",
+    "\n",
+    "# to get a specific supertranslation mode from alpha you can use the spherical_function package\n",
+    "import spherical_functions as sf\n",
+    "\n",
+    "#20 mode, the last index in LM_index indicates that the lowest ell mode is ell=0\n",
+    "alpha[sf.LM_index(2,0,0)]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "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.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

surfinBH/_fit_evaluators/__init__.py

@@ -3,3 +3,4 @@
 from .fit_7dq4 import Fit7dq4
 from .fit_7dq4Emri import Fit7dq4Emri
 from .fit_3dq8_RD import Fit3dq8_RD
+from .fit_3dq8BMS import Fit3dq8BMS