Implement a Python-only destriper

[ziotom78]

This PR implements a very simple destriper for the framework.

Here is the main highlights:

• It supports Python 3.8, 3.9, 3.10 and 3.11
• Unlike TOAST2 destriper, it supports both 32 and 64-bit floating points, which means that it should use far less memory for the most common simulations
• There is no need to read/write stuff to disk (the Madam destriper requires to write TODs to disk, and the TOAST2 map-maker saves map to disk)
• The implementation is 100% Python and optimized using Numba
• The destriper is ~3 times faster than TOAST2
• Full information about convergence is returned
• The values of the baselines are returned together with the destriped maps, and an error bar for each of them is estimated through the preconditioning matrix
• A companion function, remove_baselines_from_tod, can clean the TODs in Observation objects for the baselines
• It is integrated with the Simulation class and adds information to the report
• The length of the baselines is not required to be constant over time
• It can be used as a binner: in this case, its solution should be identical to make_bin_map
• It is able to add several components within each Observation object (example: sky_signal, dipole, noise…), with no additional memory required
• It can be used with or without MPI
• The test case develops a 100% analytical model and confronts it with the solution of the Conjugate Gradient. In this way, each part of the code can be easily checked, and the code itself should be easier to understand
• The progress callback used to provide a visual clue about the convergence can be customized according to the user's wishes

Pain points:

• It does not support template fitting like TOAST2
• It uses a flat prior for the baselines, while Madam uses a more realistic prior based on the shape of 1/f noise
• It needs testing!
• It does not currently support flagged data
• It introduces breaking changes in the API!

Stuff to do:

• [X] Implement the destriper
• [X] Test the destriper serially
• [X] Test the destriper using MPI
• [X] Implement a simple example that can be solved analytically
• [X] Implement tests that confront the output of the destriper against the analytical solution
• [X] Make the interface more modular and harmonize the API used to call make_bin_map and the TOAST2 destriper
• [X] Implement remove_baselines_from_tod
• [X] Implement docstrings
• [x] Implement a function that saves the result of the destriper to disk (including the map, the baselines, and all the ancillary stuff)
• [x] Implement a function that loads the result of the destriper from disk
• [x] Update the documentation
• [x] Update the notebooks
• [x] Update the CHANGELOG

[ziotom78]

From my point of view, this PR is ready to be reviewed. It introduces a number of breaking changes:

• The interface to make_bin_map has changed: the inverse of the N_obs matrix is always returned, and the result is no longer a map or a tuple (depending on the input parameters) but instead a BinnerResult object. This matches the way make_destriped_map and destripe_with_toast2 work.
• The structure used to pass the parameters to destripe_with_toast2 and save_simulation_for_madam has been renamed ExternalDestriperParameters

• The source files have been organized in a more coherent way: the binner and the destriper are kept in the sub-module litebird.mapmaking, which is however imported in litebird. Thus, the following still works:

  from litebird_sim import make_bin_map

  but now one can write

  from litebird_sim.mapmaking import make_bin_map

• The wrapper to the TOAST2 destriper has been moved in the sub-folder litebird_sim/toast_destriper

Finally, the problems I reported about a strange increase of power at high multipoles has been solved. It was due to an incorrect iteration over the detectors, such that all the detectors shared the same values for the baselines. With this bug fixed, the results of the new destriper agree quite well with TOAST2:

[ziotom78]

After a call with @paganol , I have implemented the following additional changes:

• I renamed make_bin_map into make_binned_map, as this matches make_destriped_map
• The value for NSIDE is no longer passed to make_destriped_map through the class DestriperParameters; instead, it is the very first argument, and this is the case for make_binned_map too (previously, it was the 2nd argument). In this way, the call to the two functions looks more similar.
• The class NobsMatrix implements the method get_invnpp(). It returns the inverse M⁻¹ of the Nobs matrix Ⅿ, which is useful to estimate the error per pixel.

Finally, I checked that when make_destriped_map is called while setting DestriperParameters.samples_per_baseline to None, it returns the very same map as the one produced by make_binned_map. (I only tested this in one case, but it was quite complex and I trust the result.) The same applies to the field BinnerResult.invnpp, which matches DestriperResult.nobs_matrix_cholesky.get_invnpp().

This means that in the future we might think about deprecating the current implementation for make_binned_map and rewrite it as a very tiny wrapper around make_destriped_map.

What's left is to check that the amount of memory used by make_destriped_map matches the expectations, then I believe we can merge this PR and release version 0.11.0.

[marcobortolami]

Hi:) just to let you know, I'm also reviewing the code:) I don't know if it can be seen, I'm using the GitHub review tool for the first time, I'm waiting to check all the files before submitting it, so my review is still "Pending". Anyway, I fully agree to the changes that came out after your call with Luca:)

[marcobortolami]

Thanks for your quick fixes:) for me this is ready to be merged!

[paganol]

Hi there. Thanks a lot!! You can merge for me, as well.

[ziotom78]

Thank you all, especially @marcobortolami : your review was comprehensive and perfect!