calc_f_kerr
===========

.. py:function:: luminet.black_hole_math.calc_f_kerr(bh_mass, a, r)

   Calculate the :math:`f`-function from :cite:t:`Page_1974` (Equation 12)

   The :math:`f`-function is used when calculating the relationship between intrinsic flux and radius for an accretion disk:

   .. math::

      F_s(r) = \frac{\dot{M}_0}{4\pi}e^{-(\nu + \psi + \mu)}f

   Here, :math:`\nu`, :math:`\psi` and :math:`\mu` are metric coefficients (functions of :math:`r`) of the Kerr metric. :math:`\dot{M}_0` is the radius-independent, time-averaged rate at which mass flows inward. Defining the innermost stable orbit as :math:`r_{ms}`, :math:`x=\sqrt{r/M}=\sqrt{r^*}`, :math:`x_0=\sqrt{r_{ms}/M}` and :math:`a^*=a/M`, the :math:`f`-function is defined as:

   .. math::

      \begin{align*}
       f = &\frac{3}{2M}\frac{1}{x^2(x^3 - 3x + 2a^*)}\Bigg[ x - x_0 - \frac{3}{2}a^*\ln\left(\frac{x}{x_0}\right) \\
        &- \frac{3(x_1 - a^*)^2}{x_1(x_1-x_2)(x_1-x_3)}\ln\left(\frac{x-x_1}{x_0-x_1}\right) \\
        &- \frac{3(x_2 - a^*)^2}{x_2(x_2-x_1)(x_2-x_3)}\ln\left(\frac{x-x_2}{x_0-x_2}\right) \\
        &- \frac{3(x_3 - a^*)^2}{x_3(x_3-x_1)(x_3-x_2)}\ln\left(\frac{x-x_3}{x_0-x_3}\right) \Bigg]
       \end{align*}

   , where

   .. math::

      \begin{align*}
      x_1 &= 2\cos(\frac{1}{3}\cos^{-1}(a_*) - \frac{\pi}{3}) \\
      x_2 &= 2\cos(\frac{1}{3}\cos^{-1}(a_*) + \frac{\pi}{3}) \\
      x_3 &= -2\cos(\frac{1}{3}\cos^{-1}(a_*)) \\
      \end{align*}

   For a Swarzschild black hole, :math:`a=0` and these simplify to:

   .. math::

      \begin{align*}
      x_1 &= \sqrt{3} \\
      x_2 &= 0 \\
      x_3 &= - \sqrt{3} \\
      f &= \frac{3}{2M}\frac{1}{{r^{*}}^{1.5}(r^*-3)}\left[x - x_0 + \frac{\sqrt{3}}{2}\ln\left( \frac{(\sqrt{6} - \sqrt{3})(\sqrt{r^*}+\sqrt{3})}{(\sqrt{6} + \sqrt{3})(\sqrt{r^*} - \sqrt{3})}  \right)  \right]
      \end{align*}

   :Parameters: * **bh_mass** (*float*) -- Mass of the black hole.
                * **a** (*float*) -- Specific angular momentum of the black hole. Should always be between :math:`-1` and :math:`1`. :math:`a > 0` if the accretion disk orbits in the same direction as the hole rotates; :math:`a < 0` if it orbits in the opposite direction.
                * **r** (*float*) -- Radius of the orbit

   .. attention:: :cite:t:`Luminet_1979` has a mistake in Equation 15. The factor in fromt of the :math:`log` should be :math:`\sqrt{3}/2` instead of :math:`\sqrt{3}/3`. This can be verified by solving :cite:t:`Page_1974` Equation 15n.  The resulting images of the paper are correct though.

   .. seealso:: :cite:t:`Page_1974` for more information.

   .. seealso:: :meth:`calc_flux_intrinsic_kerr` for the calculation of the intrinsic flux.

   .. seealso:: :meth:`calc_innermost_stable_orbit` for the calculation of :math:`r_{ms}`