pygwtf.response.orbits
======================

.. py:module:: pygwtf.response.orbits


Functions
---------

.. autoapisummary::

   pygwtf.response.orbits.Orbit
   pygwtf.response.orbits.get_analytic_orbits
   pygwtf.response.orbits.read_in_mojito_orbit
   pygwtf.response.orbits.read_in_mojito_ltts
   pygwtf.response.orbits.generate_mojito_orbit_splines_resample
   pygwtf.response.orbits.get_analytic_ltts


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

.. py:function:: Orbit(t: numpy.ndarray, initial_ecliptic_longitude: float, e: float, n: int, initial_orientation_of_constellation: float = 0) -> numpy.ndarray

   Function to calculate the position of the spacecrafts in the constellation as a function of time.

   Reference: https://arxiv.org/pdf/gr-qc/0311069

   Args:
       t (jax.numpy.array): Time array
       initial_ecliptic_longitude (float): Initial ecliptic longitude of the constellation
       e (float): Eccentricity of the orbit
       n (int): Spacecraft number
       initial_orientation_of_constellation (float): Initial orientation of the constellation

   Returns:
       pos (jax.numpy.array): Position of the spacecraft as a function of time



.. py:function:: get_analytic_orbits(t_tranche: numpy.ndarray) -> numpy.ndarray

   '
   Get analytic orbits for the 3 spacecrafts in the constellation as a function of time.

   Args: 
       t_tranche (numpy.array): Time array for the tranche of data being analyzed. Shape (nT,)

   Returns:
       orbits (numpy.array): Array of shape (nT, 3, 3) containing the positions of the 3 spacecraft as a function of time.


.. py:function:: read_in_mojito_orbit(filepath: str) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Plugin for reading in Mojito orbit files for LISA spacecraft positions.
   NOTE: Should really be deprecated by the mojito package, but this is a quick and dirty way to get the orbits in for now.
   NOTE: This is *not* compatible with the
       additional trim that is needed to get rid of the low frequency noise that comes from the high pass
       filter of mojito data...
   NOTE: Hardcoded to the times-shifts needed for the 0.4Hz downsampled data for now.

   Args:
       filepath (str): Path to the Mojito orbit file
   Returns:
       pos_sc1 (numpy.array): Array of shape (3,N_times_orbital) containing the positions of spacecraft 1 as a function of time.
       pos_sc2 (numpy.array): Array of shape (3,N_times_orbital) containing the positions of spacecraft 2 as a function of time.
       pos_sc3 (numpy.array): Array of shape (3,N_times_orbital) containing the positions of spacecraft 3 as a function of time.
       orbital_times_shifted (numpy.array): Array of shape (N_times_orbital,) containing the shifted orbital times corresponding to the positions.


.. py:function:: read_in_mojito_ltts(filepath: str) -> tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Read in mojito LTT file. 
   Should really do this in a better way, currently requires a unique LTT file which contains the LTTs for each link (assuming symmetric LTTs for now). 
   Following same time conventions as the orbit file mojito. (Assuming that the LTT times are already subset to the data collection time in preprocessing.)

   Only extracts: {12, 23, 31} links for now.

   NOTE/WARNING: In seconds not metres, need to be converted to metres to match transfer function conventions!!! 

   Args:
       filepath (str): Path to the Mojito LTT file
   Returns:
        L12 (numpy.array): Array of shape (N_times_LTT,) containing the LTTs for link 12 as a function of time.
        L23 (numpy.array): Array of shape (N_times_LTT,) containing the LTTs for link 23 as a function of time.
        L31 (numpy.array): Array of shape (N_times_LTT,) containing the LTTs for link 31 as a function of time.
        LTT_times_shifted (numpy.array): Array of shape (N_times_LTT,) containing the shifted LTT times corresponding to the LTTs.        


.. py:function:: generate_mojito_orbit_splines_resample(mojito_orbit_filepath: str, mojito_ltt_filepath: str, t_tranches: numpy.ndarray) -> tuple[numpy.ndarray, numpy.ndarray]

   Generates orbit splines from a mojito orbit file. Then evaluate them on SFT time grid.

   Args:
       mojito_orbit_filepath (str): Path to the Mojito orbit file
       mojito_ltt_filepath (str): Path to the Mojito LTT file (assumes npz file)
       t_tranches (numpy.array): Time array for the SFT midpoints, shape (nT,)
   Returns:
       p_fine (numpy.array): Array of shape (nT, 3, 3) containing the positions of the 3 spacecraft as a function of time.
       LTTs_fine (numpy.array): Array of shape (nT, 3) containing the LTTs for the 3 links (12, 23, 31) as a function of time.



.. py:function:: get_analytic_ltts(spacecraft_orbits: numpy.ndarray) -> numpy.ndarray

   Get analytic link lengths for each arm from spacecraft positions.

   Despite the historical function name, the transfer-function code expects
   arm lengths in meters, not light-travel times in seconds.

   Args:
       spacecraft_orbits (numpy.array): Array of shape (nT, 3, 3) containing the positions of the 3 spacecraft as a function of time.

   Returns:
       ltts (numpy.array): Array of shape (nT, 3) containing the link
           lengths in meters for links (12, 23, 31) as a function of time.