GWForge.fisher.antenna_derivatives
==================================

.. py:module:: GWForge.fisher.antenna_derivatives

.. autoapi-nested-parse::

   Closed-form derivatives of the detector response geometry.

   ``ra``, ``dec`` and ``psi`` reach the strain only through the detector
   projection, never through the waveform, so their derivatives can be written down
   exactly. This module differentiates the same expressions
   :func:`GWForge.ifo.antenna.antenna_response` evaluates -- the ``u``, ``v``, ``m``
   and ``n`` triad, the propagation direction, the finite-size arm transfer
   function and the vertex delay -- with respect to the internal angles
   :math:`(\phi, \theta, \psi)`, and chain-rules them onto the source parameters.

   That holds under the frequency-dependent, Earth-rotating response too, which
   changes only *how* :math:`F_{+,\times}` and :math:`\tau` are built. Freezing the
   polarizations and differencing the response alone reproduces the full derivative
   bit-identically; ``tests/test_fisher.py`` asserts exactly that.

   The work is done on scalars rather than on :math:`3\times3\times n`
   polarization tensors: contracting an arm with the polarization basis reduces to
   :math:`(\hat a\cdot m)` and :math:`(\hat a\cdot n)`, so only those and their
   derivatives are ever needed.



Classes
-------

.. autoapisummary::

   GWForge.fisher.antenna_derivatives.AntennaDerivatives


Module Contents
---------------

.. py:class:: AntennaDerivatives(interferometer, ra, dec, geocent_time, psi, frequencies, start_time, times_to_coalescence=None, earth_rotation=True, finite_size=True)

   Exact derivatives of :math:`F_+`, :math:`F_\times` and :math:`\tau`.

   Differentiates the same expressions
   :func:`GWForge.ifo.antenna.antenna_response` evaluates, with respect to the
   internal angles :math:`(\phi, \theta, \psi)`, then chain-rules those onto the
   source parameters ``ra``, ``dec``, ``psi`` and ``geocent_time``:

   .. math::

      \frac{\partial}{\partial\alpha} = \frac{\partial}{\partial\phi},
      \qquad
      \frac{\partial}{\partial\delta} = -\frac{\partial}{\partial\theta},
      \qquad
      \frac{\partial}{\partial t_c} \supset
          -\dot{\mathrm{gmst}}\,\frac{\partial}{\partial\phi},

   the last because :math:`\phi = \alpha - \mathrm{gmst}(t_c)`. So the
   Earth-rotation part of the ``geocent_time`` derivative comes free from the
   sky partials. ``geocent_time`` additionally enters :math:`\tau` explicitly
   with unit derivative, which is the dominant :math:`-2\pi i f h` term.

   :ivar plus, cross: :math:`F_+` and :math:`F_\times` and their derivatives, keyed by source
                      parameter name (``"ra"``) or sorted pair (``("dec", "ra")``).
   :vartype plus, cross: dict
   :ivar delay: Same for :math:`\tau`.

   :vartype delay: dict


   .. py:attribute:: sidereal_rate