docs: Restructure documentation to reflect package decomposition into subpackages and methods

docs/DataVector.rst

@@ -1,6 +1,9 @@
 DataVector class
 ================
 
+The :py:mod:`flip.data_vector` module provides data vector classes for handling velocity, density, and joint data.
+This is a common module shared across all methods in the package.
+
 FLIP includes a :py:class:`~flip.data_vector.basic.DataVector` abstract class that is used to build different classes 
 to easily handle the data you want to use and to pass them to one of the different likelihood 
 implemented in the :py:mod:`flip.covariance.likelihood` module.

docs/conf.py

@@ -48,7 +48,7 @@
 extensions.append('autoapi.extension')
 
 # Auto-API config
-autoapi_dirs = ['../flip', '../flip/covariance']
+autoapi_dirs = ['../flip', '../flip/covariance', '../flip/data_vector', '../flip/power_spectra', '../flip/data', '../flip/simulation']
 
 def skip_util_classes(app, what, name, obj, skip, options):
     if name == "__init__":

docs/covariance_method.rst

@@ -0,0 +1,86 @@
+Covariance method
+=================
+
+The covariance method is the core approach implemented in **flip**. It is a likelihood-based field-level inference method
+for fitting the growth rate of structures based on velocity and density fields. The full description is given in
+`Ravoux et al. 2025 <https://arxiv.org/abs/2501.16852>`_.
+
+Overview
+--------
+
+The method works in three steps:
+
+1. **Covariance matrix computation**: A model covariance matrix is computed from a model power spectrum and the
+   considered object coordinates. This part is generalized to work for any linear power spectrum model, both for
+   velocities, densities, and cross-terms. It is optimized with Hankel transforms for any model.
+
+2. **Likelihood construction**: The covariance is used to build a likelihood by combining it with velocity or density
+   data vectors. See `Likelihoods <likelihoods.html>`_.
+
+3. **Parameter fitting**: The package includes integrated fitters such as Minuit and MCMC (with emcee) to fit the
+   growth rate of structures.
+
+
+Subpackage contents
+-------------------
+
+The :py:mod:`flip.covariance` subpackage contains:
+
+- :py:mod:`flip.covariance.covariance` — The :py:class:`~flip.covariance.covariance.CovMatrix` class for building and manipulating covariance matrices.
+- :py:mod:`flip.covariance.likelihood` — Likelihood functions (multivariate Gaussian with various inversion methods).
+- :py:mod:`flip.covariance.fitter` — Fitter classes wrapping Minuit and MCMC samplers.
+- :py:mod:`flip.covariance.fisher` — Fisher matrix computation from covariance derivatives.
+- :py:mod:`flip.covariance.analytical` — Analytical covariance models (e.g., Adams & Blake 2017, Carreres 2023, Lai 2022, RCRK 2024).
+- :py:mod:`flip.covariance.emulators` — Covariance emulators using Gaussian processes and neural networks.
+- :py:mod:`flip.covariance.generator` — Covariance matrix generation utilities.
+- :py:mod:`flip.covariance.symbolic` — Symbolic computation of covariance terms.
+
+Analytical models
+~~~~~~~~~~~~~~~~~
+
+Several analytical covariance models are available:
+
+- **adamsblake17** / **adamsblake17plane**: Adams & Blake 2017 models.
+- **adamsblake20**: Adams & Blake 2020 model.
+- **carreres23**: Carreres et al. 2023 model.
+- **lai22**: Lai et al. 2022 model.
+- **rcrk24**: RCRK 2024 model.
+- **genericzdep**: Generic redshift-dependent model.
+- **ravouxcarreres**, **ravouxnoanchor25**, **ravouxqin26**: Additional models.
+
+Usage
+-----
+
+The typical workflow involves:
+
+1. Computing or loading power spectra (see `Power Spectra <power_spectra.html>`_).
+2. Building data vectors (see `Data Vectors <DataVector.html>`_).
+3. Computing the covariance matrix using :py:class:`~flip.covariance.covariance.CovMatrix`.
+4. Running the fitter to constrain cosmological parameters.
+
+A minimal example:
+
+.. code-block:: python
+
+    from flip import covariance, data_vector, power_spectra
+
+    # 1. Load or compute power spectra
+    power_spectrum_dict = ...
+
+    # 2. Build the data vector
+    data = data_vector.DirectVel(velocity_data)
+
+    # 3. Compute covariance matrix
+    cov = data.compute_covariance(
+        model_name="carreres23",
+        power_spectrum_dict=power_spectrum_dict,
+    )
+
+    # 4. Fit using Minuit
+    fitter = covariance.fitter.MinuitFitter.init_from_covariance(
+        covariance=cov,
+        data=data,
+    )
+    result = fitter.minimize(parameter_dict)
+
+For complete examples, see `Getting started <basicusage.html>`_.

docs/field_comparison.rst

@@ -0,0 +1,21 @@
+Field comparison method
+=======================
+
+The field comparison method provides a direct comparison approach for velocity and density fields.
+
+.. note::
+
+   This method is **not yet implemented**. It is planned for a future release of the package.
+
+Overview
+--------
+
+The field comparison method will offer an alternative approach to the covariance-based likelihood inference
+and the forward modeling simulation. It will enable direct comparison of observed fields with theoretical
+predictions.
+
+Like the other methods, the field comparison approach will share the common modules of the **flip** package:
+
+- :py:mod:`flip.power_spectra` for power spectrum computation.
+- :py:mod:`flip.data_vector` for data vector handling.
+- :py:mod:`flip.data` for test data.

docs/index.rst

@@ -4,12 +4,28 @@ Welcome to flip's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Getting started:
 
    installation.rst
    basicusage.rst
+   overview.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Common modules:
+
+   power_spectra.rst
    DataVector.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Methods:
+
+   covariance_method.rst
+   likelihoods.rst
    vel_estimators.rst
+   simulation.rst
+   field_comparison.rst
 
 .. toctree::
    :hidden:

docs/likelihoods.rst

@@ -1,17 +1,33 @@
 Likelihoods
 ===========
 
+The likelihoods are implemented as part of the `covariance method <covariance_method.html>`_
+in the :py:mod:`flip.covariance.likelihood` module.
+
+
 Velocity alone
 --------------
 
 Standard velocity likelihood:
 
 .. math::
-    
-    `\mathcal{L} = (2\pi)^\frac{N}{2}|C|^\frac{1}{2} \exp\left[\frac{1}{2} \mathbf{v}^T C^{-1}\mathbf{v}\right]` 
+
+    \mathcal{L} = (2\pi)^{-\frac{N}{2}}|C|^{-\frac{1}{2}} \exp\left[-\frac{1}{2} \mathbf{v}^T C^{-1}\mathbf{v}\right]
 
 where :math:`C` is such that:
 
 .. math::
 
-    `C = C_\mathrm{vv} + \sigma_v^2 \mathbb{I}_n`
+    C = C_\mathrm{vv} + \sigma_v^2 \mathbb{I}_n
+
+
+Inversion methods
+-----------------
+
+Several methods are available for computing the log-likelihood, differing in how the covariance matrix is inverted:
+
+- **inverse** — Explicit matrix inversion.
+- **solve** — Linear solver (avoids explicit inversion).
+- **cholesky** — Cholesky decomposition.
+- **cholesky_regularized** — Regularized Cholesky decomposition.
+- **cholesky_inverse** — Cholesky-based inversion.

docs/overview.rst

@@ -0,0 +1,49 @@
+Package overview
+================
+
+**flip** (Field Level Inference Package) is a Python package designed for the analysis of velocity and density fields in cosmology.
+The package provides tools for fitting the growth rate of structures using different methodological approaches.
+
+The full description of the core concepts of this package is given in `Ravoux et al. 2025 <https://arxiv.org/abs/2501.16852>`_.
+
+Package structure
+-----------------
+
+The package is decomposed into several subpackages. Some are **common modules** shared across all methods,
+while others implement specific **methodological approaches** to deal with velocity and density fields.
+
+Common modules
+~~~~~~~~~~~~~~
+
+These modules are shared across all methods:
+
+- :py:mod:`flip.power_spectra` — Power spectrum generation using various Boltzmann solver engines (CLASS, cosmoprimo, pyccl).
+  See `Power Spectra <power_spectra.html>`_.
+
+- :py:mod:`flip.data_vector` — Data vector classes for handling velocity, density, and joint data.
+  See `Data Vectors <DataVector.html>`_.
+
+- :py:mod:`flip.data` — Built-in test data and loading utilities.
+
+
+Methods
+~~~~~~~
+
+The package currently supports or plans to support the following approaches:
+
+1. **Likelihood-based field-level inference** (:py:mod:`flip.covariance`) — The core method of the package, using covariance matrices
+   built from model power spectra and object coordinates. See `Covariance method <covariance_method.html>`_.
+
+2. **Forward modeling simulation** (:py:mod:`flip.simulation`) — A simulation-based approach currently under construction.
+   See `Simulation method <simulation.html>`_.
+
+3. **Field comparison** — A direct field comparison method, not yet implemented.
+   See `Field comparison method <field_comparison.html>`_.
+
+
+How to cite
+-----------
+
+The full description of the core concepts of this package is given in `Ravoux et al. 2025 <https://arxiv.org/abs/2501.16852>`_.
+This package was started on the previous work of `Carreres et al. 2023 <https://arxiv.org/abs/2303.01198>`_.
+Please cite both papers when using the package.

docs/power_spectra.rst

@@ -1,20 +1,51 @@
 Power Spectra Generator
 =======================
 
-You can use the `flip.power_spectra` module to compute your power spectra using the `flip.power_spectra.compute_power_spectra` function:
-
-```
-k, pdd, pdt, ptt = compute_power_spectra(
-                        power_spectrum_engine,
-                        power_spectrum_settings,
-                        redshift,
-                        minimal_wavenumber,
-                        maximal_wavenumber,
-                        number_points,
-                        logspace=True,
-                        normalize_power_spectrum=True,
-                        power_spectrum_non_linear_model=None,
-                        power_spectrum_model="linearbel",
-                        save_path=None,
-)
-python```
+The :py:mod:`flip.power_spectra` module provides tools to compute matter, momentum, and velocity power spectra
+using various Boltzmann solver engines. This is a common module shared across all methods in the package.
+
+
+Computing power spectra
+-----------------------
+
+You can use the :py:func:`flip.power_spectra.compute_power_spectra` function to compute power spectra:
+
+.. code-block:: python
+
+    from flip.power_spectra import compute_power_spectra
+
+    k, pk_dict = compute_power_spectra(
+        power_spectrum_engine,
+        power_spectrum_settings,
+        redshift,
+        minimal_wavenumber,
+        maximal_wavenumber,
+        number_points,
+        logspace=True,
+        normalize_power_spectrum=True,
+        power_spectrum_non_linear_model=None,
+        power_spectrum_model="linearbel",
+        save_path=None,
+    )
+
+
+Available engines
+-----------------
+
+The following Boltzmann solver engines are supported:
+
+- **cosmoprimo** — via :py:mod:`flip.power_spectra.cosmoprimo_engine`
+- **CLASS** — via :py:mod:`flip.power_spectra.class_engine`
+- **pyccl** — via :py:mod:`flip.power_spectra.pyccl_engine`
+
+
+Power spectrum models
+---------------------
+
+Several models are available for decomposing the matter power spectrum into velocity-related components:
+
+- **linearbel** — Linear power spectrum with BEL damping model applied to compute :math:`P_{m\theta}(k)` and :math:`P_{\theta\theta}(k)` from the linear :math:`P_{mm}(k)`.
+- **nonlinearbel** — Uses an external non-linear :math:`P_{mm}(k)` combined with BEL damping for :math:`P_{m\theta}(k)` and :math:`P_{\theta\theta}(k)`.
+- **linear** — Direct linear power spectrum without BEL correction.
+
+The BEL model coefficients are parameterized as a function of :math:`\sigma_8` following Bel et al.

docs/simulation.rst

@@ -0,0 +1,34 @@
+Simulation method
+=================
+
+The simulation method implements a forward modeling approach for velocity and density fields.
+This method is part of the :py:mod:`flip.simulation` subpackage.
+
+.. note::
+
+   This method is currently **under construction**. The subpackage structure is in place but the
+   implementation is being developed in collaboration with other contributors.
+
+Overview
+--------
+
+The forward modeling simulation approach provides an alternative to the covariance-based method
+by directly simulating velocity and density fields. This allows for more flexible modeling of
+non-linear effects and complex survey geometries.
+
+The simulation method shares the common modules of the **flip** package:
+
+- :py:mod:`flip.power_spectra` for power spectrum computation.
+- :py:mod:`flip.data_vector` for data vector handling.
+- :py:mod:`flip.data` for test data.
+
+Optional dependencies
+---------------------
+
+The simulation method requires additional dependencies that can be installed via:
+
+.. code-block:: bash
+
+   pip install flipcosmo[simulation]
+
+This installs JAX, JAXpm, JAXopt, jax-cosmo, and diffrax for differentiable simulation support.