.. _lifeinterpif:

LIFE Interpolation Interface
============================

We have developed a C++ package to provide a  fast implementation of the windowed sinc interpolation of the
LIFE interferometer data. It is developed in a package **lifeinterif**

Installation
------------

The lifeinterpif package can be installed on 64 bits Windows, Python 3.7 using a pre-built wheel located on the **arg**
server::

   pip install --upgrade lifeinterpif -f https://arg.usask.ca/wheels/

A setup.py script is provided so users can build the the wheel for other operating systems, eg `python setup.py bdist_wheel`

.. note::

   The variables `include_dirs` and `library_dirs` inside setup.py script will need to be modified on different systems.
   `include_dirs` must specify the path to the C++ boost installation as wells as the numpy include files inside python.
   `library_dirs` must specify the path to the C++ boost libraries. You may aslo have to explicitly include the boost
   libraries in the `libraries` variable.

Usage
-----

The **lifeinterpif** package is a shallow swig wrapper for the C++ code and has been developed for development convenience
rather than user ergonomics. It is recommended that another layer of wrapper code be placed around the package if ergonomic interfaces are desired.
An example of usage is as follows::

    >>> import lifeinterpif.lifeinterpif
    >>> ok,Ginterp = lifeinterpif.lifeinterpif.windowed_sinc_resample(  tnew,  G, Gt, Fs, num_sinc, len_Ginterp)

.. py:function:: windowed_sinc_resample(  tnew,  G, Gt, Fs, num_sinc, len_Ginterp)

    Performs the *windowed sinc resampling* algorithm to the LIFE interferometer data.

    :param numpy.ndarray(float) tnew:
        An array of unevenly spaced times at which interpolated signals are required.  The array must be in ascending order.
        For atmospheric measurements this array is typically around 7840 elements. Read-only.

    :param numpy.ndarray(float) G:
        The array of evenly spaced samples for either one pixel or 8 pixels. These are the values interpolated by the code.
        If processing one pixel it will have a size around 177,000 and will be the same size as `Gt`.  If processing 8 pixels
        it will be exactly 8 times the size of `Gt`. The 8 samples for the 8 pixels at one instant in time must be ordered
        consecutively in memory. Read-only.

    :param numpy.ndarray(float) Gt:
        The array of times of the evenly spaced samples. It is typically around 177,000 elements in size. It muts be in ascending order. (read only).

    :param float Fs: The frequency scaling (Hz) to be applied to time measurements. Typically around 78125.0

    :param int num_sinc:
        The total number of points from the evenly sampled data to be included in the windowed sinc interpolation.
        Typically half the points are to the left of each unevenly spaced time point and half are to the right

    :param int len_Ginterp:
        The length of the sampled output array returned to the user. This will either be the same as the size of array `tnew`
        or 8 times the size of array `tnew` if 8 pixels are processed.

    :return:
        Returns a two element tuple. The first element is a boolean indicating success of failure. The second element is
        a 1-D numpy array of size len_Ginterp containing the data interpolated to the unevenly sampled time points in `tnew`.
        It will either be the same size as `tnew` or it will be 8 times the size of `tnew` if 8 pixels are simultaneously
        processed. The output array is undefined and may contain garbage if the first element of the returned tuple is not true.
         
    :rtype: Tuple[ bool, nnumpy.ndarray(float)]