Developer guide
===============

Getting started
---------------

First, clone the repository and install BLIP locally in a virtual environment. Use an
editable installation with all development dependencies (includes tests and
documentation)::

   pip install -e .[gpu] --group dev

Run the test suite::

   pytest

Build the documentation in HTML format::

   cd docs
   make html

General architecture
--------------------

The main pipeline logic is in :mod:`blip.run_blip`.

Data generation is done by an :class:`injection <blip.src.models.Injection>`, while data
analysis is done by a :class:`model <blip.src.models.Model>`. Injections and models are
collections of :class:`submodels <blip.src.submodel.submodel>`.

The model is specified by ``params.model`` in the :ref:`configuration file <config>`,
whereas the injection is specified by ``inj.injection``.

The submodels are uniquely identified by the raw strings used to specify them in the
config file. See the attributes ``components`` and ``component_names`` for an injection
or ``submodels`` and ``submodel_names`` for a model.


Input parameters
----------------

The input parameters given in the :ref:`configuration <config>` by the user are parsed
using :func:`parse_config <blip.config.parse_config>` and passed around in BLIP as the
ubiquitous dictionaries named ``params`` and ``inj``.

.. _devguide-timefreq:

Time-frequency grids
--------------------

In BLIP there are two main time-frequency grids: the one used for data generation, and
the one used for data analysis. Throughout the code, the following convention for names
specifies which one we are talking about:

+----------------------+---------------------------------------------+-----------------------------------+
|                      |                Analysis grid                |          Simulation grid          |
+======================+=============================================+===================================+
| time chunks          | "segments" (default 1e5)                    | "splices" (default 1e4)           |
+----------------------+---------------------------------------------+-----------------------------------+
| time array           | ``tsegmid``                                 | ``tsegmid``                       |
| (mid-segments)       |                                             |                                   |
+----------------------+---------------------------------------------+-----------------------------------+
| size of segment      | ``nperseg``                                 | ``npersplice``                    |
+----------------------+---------------------------------------------+-----------------------------------+
| frequency resolution | higher (``rfftfreq(nperseg)``)              | lower (``rfftfreq(npersplice)``)  |
+----------------------+---------------------------------------------+-----------------------------------+
| frequency range      | between ``fmin`` and ``fmax``               | full range excluding DC           |
+----------------------+---------------------------------------------+-----------------------------------+
| frequency array      | ``fdata``                                   | ``frange``                        |
+----------------------+---------------------------------------------+-----------------------------------+
| implementation       | :meth:`tser2fser                            | ``LISA.makedata`` in ``run_blip`` |
|                      | <blip.src.makeLISAdata.LISAdata.tser2fser>` |                                   |
+----------------------+---------------------------------------------+-----------------------------------+

Moreover, inside the :mod:`blip.src.faster_geometry` module, a sparse time-frequency
grid is used for the response calculation. The sparse grid is generated by
:func:`blip.src.faster_geometry.get_sparse_tf_grid` based on the required dense grid,
which could be either the analysis or the simulation grid.


Response matrices
-----------------

Response matrices are passed around as attributes in submodels. This is the list of
attributes currently used:

1. ``response_mat``: complex array of shape ``(3, 3, nfreqs, ntimes)``, the first two
   dimensions referring to TDI channels. If the submodel has a parametrized spatial
   model, this has an additional dimension in the end which is the number of active
   pixels for pixel models and the number of terms in the spherical harmonic expansion
   for sph model.
2. ``fdata_response_mat``: in injection submodels, this is the same as ``response_mat``,
   but computed on the analysis time-frequency grid rather than on the simulation grid.
   This is used for plotting injections together with analysis results. Using this
   rather than ``response_mat`` is indicated by a function parameter ``plot_flag`` in,
   e.g., :meth:`calculate_response_functions
   <blip.src.fast_geometry.fast_geometry.calculate_response_functions>`.
3. ``unconvolved_response_mat``: deprecated, used ``response_mat`` instead. (Was used for parametrized spatial models, complex array of
   shape ``(3, 3, nfreqs, ntimes, npix or nsph)``).
4. ``unconvolved_fdata_response_mat``: combination of the two above.
5. ``summ_response_mat``: deprecated, use ``response_mat`` instead.
6. ``inj_response_mat``: deprecated, use ``response_mat`` instead.