Tod effect driver

[paganol]

This pull request introduces several important improvements and documentation updates to the LiteBIRD Simulation Framework. The main highlights include extracting and consolidating shared driver logic for systematic-effect modules, enhancing and standardizing the documentation (including how to cite the framework), and adding new support and documentation for correlated noise models. Several internal refactorings improve code clarity and maintainability by moving utility functions to a dedicated module and updating imports accordingly.

Core refactoring and codebase improvements:

• Extracted a shared driver for systematic-effect modules (for_each_observation, for_each_observation_with_pointings, normalize_observations) and consolidated related helpers into the new observation_utilities.py module. Updated all relevant imports and references to use this new module, replacing the previous pointings_in_obs.py. This change centralizes normalization, per-detector RNG resolution, and TOD-component indirection for noise, gain drift, non-linearity, HWP differential emission, and CMB dipole effects. [1] [2] [3] [4] [5] [6] [7] [8] [9]

New features and documentation:

• Added documentation and examples for correlated noise models, including both a common-mode model (with group-based correlations) and a general Cholesky-based model for arbitrary correlation matrices. This is documented with usage examples and notes on matrix requirements.
• Added the add_correlated_noise function to the public API and updated documentation to reflect its usage. [1] [2]

Documentation and citation updates:

• Added clear instructions on how to cite the LiteBIRD Simulation Framework in both the README.md and the user manual, including a full BibTeX entry and citation key. The main reference is now included in the bibliography (refs.bib). [1] [2] [3]
• Expanded and clarified the introduction and structure of the user manual, including overviews for each major part of the documentation. [1] [2] [3] [4] [5] [6]

API and documentation consistency:

• Improved the documentation for h_maps to use fully qualified references and clarified usage of functions and methods throughout the API documentation. [1] [2] [3] [4]

These changes improve maintainability, user guidance, and scientific reproducibility for the LiteBIRD Simulation Framework.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
litebird_sim
__init__.py
beam_convolution.py
dipole.py
gaindrifts.py					549
hwp_diff_emiss.py
io.py
madam.py
mpi.py
noise.py
non_linearity.py					203
observation_utilities.py
scan_map.py
simulations.py
litebird_sim/hwp_harmonics
hwp_harmonics.py
litebird_sim/mapmaking
binner.py
brahmap_gls.py
common.py
destriper.py
h_maps.py
pair_differencing.py
Project Total

This report was generated by python-coverage-comment-action

[paganol]

This PR triggers an error with BrahMap in brahmap/lbsim/lbsim_process_time_samples.py seen in test/test_brahmap.py. This is caused by having renamed pointings_in_obs.py as observation_utilities.py. If we want to keep this new name we need to update BrahMap.

[anand-avinash]

I see that the error is happening due to the circular dependency. LBS imports BrahMap to provide high level interface for map-making in simulation class, whereas BrahMap imports LBS to consume pointings and TODs in map-making directly. The current released version of LBS is compatible with BrahMap as it is. In order to accommodate the upcoming changes related to this PR in BrahMap, I can make it compatible with both the current release of LBS as well as this PR. This will resolve the current issue.