Non-linearity injection#

Non-linearity is the effect of a non-ideal TES detector response, where the responsivity \(S\) is not constant as the optical power varies. The LiteBIRD Simulation Framework provides a non-linearity simulation module to simulate the effect of non-linearity on TODs.

The framework provides the simplest case, which is quadratic non-linearity. This case is described in Micheli+2024, where the effect of non-linearity is propagated to the estimation of the tensor-to-scalar ratio.

Considering a first order correction of the usual linear gain, a TOD \(d(t)\) is modified according to:

\[d(t) = [1+g_1 d(t)] d(t)\]

where \(g_1\) is the detector non-linearity factor in units of \(K^{-1}\).

Examples#

To simulate a quadratic non-linearity, one can use the method of Simulation class Simulation.apply_quadratic_nonlin(), or any of the low-level functions: apply_quadratic_nonlin_to_observations(), apply_quadratic_nonlin_for_one_detector().

The examples below skip the simulation and observation creation for brevity. If needed, the implementation for those parts is explained in other sections of the docs.

(... importing modules, creating simulation, setting scanning strategy, instrument, etc...)

# creating the detectors (two mock detectors here)
dets = [
     lbs.DetectorInfo(name="det_A", sampling_rate_hz=sampling_hz),
     lbs.DetectorInfo(name="det_B", sampling_rate_hz=sampling_hz),
 ]

(obs,) = sim.create_observations(
   detectors=dets,
)

sim.prepare_pointings()

(... fill your TOD scanning a map, or add dipole, noise, etc...)

# Define nonlinearity amplitude distribution for the detectors, in 1/K units.
# The value is randomized for each detector, using either a user-provided seed or a list of
# pre-initialized RNGs.

nl_params = lbs.NonLinParams(sampling_gaussian_loc=-1.0, sampling_gaussian_scale=0.01)

# Applying nonlinearity using the `Simulation` class method with a required user seed
# By default, it modifies the ``Observation.tod``. If you want to apply it to some
# other field of the :class:`.Observation` class, use `component`

sim.apply_quadratic_nonlin(nl_params = nl_params, user_seed = 1234)

API reference#

class litebird_sim.non_linearity.NonLinParams(sampling_gaussian_loc: float = 0.0, sampling_gaussian_scale: float = 0.1)#

Bases: object

A class to store the non-lineairty injection parameters.

  • sampling_gaussian_loc (float): Mean of the Gaussian distribution.

  • sampling_gaussian_scale (float): Standard deviation of the Gaussian distribution.

sampling_gaussian_loc: float = 0.0#
sampling_gaussian_scale: float = 0.1#
litebird_sim.non_linearity.apply_quadratic_nonlin(tod: ndarray, bandcenter_ghz: ndarray, bandwidth_ghz: ndarray, nl_params: NonLinParams | None = None, dets_random: list[Generator] | None = None, conv_K_CMB_to_MJy_over_sr: bool = False)#

Apply a quadratic nonlinearity to some time-ordered data

This functions modifies the values in tod by adding a parabolic function of the TOD itself.

litebird_sim.non_linearity.apply_quadratic_nonlin_for_one_detector(tod_det, det_bandcenter_ghz: float64 | None = None, det_bandwidth_ghz: float64 | None = None, nl_params: NonLinParams | None = None, random: Generator | None = None, conv_K_CMB_to_MJy_over_sr: bool = False)#

This function applies the quadratic non-linearity on the TOD corresponding to only one detector.

Parameters:

  • tod_det (np.ndarray) – The TOD array corresponding to only one detector.

  • nl_params (NonLinParams, optional) – The non-linearity injection parameters object. Defaults to None.

  • random (np.random.Generator, optional) – A random number generator. Defaults to None.

  • conv_K_CMB_to_MJy_over_sr (bool, optional) – Flag for temperature to spectral radiance units conversion. Defaults to False.

  • det_freq_ghz (np.float64, optional) – Detector central frequency in GHz. Used in the K to SR conversion. Defaults to None.

  • det_bandwidth_ghz (np.float64, optional) – Detector bandwidth in GHz. Used in the K to SR conversion. Defaults to None.

litebird_sim.non_linearity.apply_quadratic_nonlin_for_one_sample(data, det_name: str | None = None, nl_params: NonLinParams | None = None, g_one_over_k: float | None = None, random: Generator | None = None)#
litebird_sim.non_linearity.apply_quadratic_nonlin_to_observations(observations: Observation | list[Observation], nl_params: NonLinParams | None = None, component: str = 'tod', user_seed: int | None = None, conv_K_CMB_to_MJy_over_sr: bool = False)#

Apply a quadratic nonlinearity to some time-ordered data

This is a wrapper around the apply_quadratic_nonlin() function that applies to the TOD stored in observations, which can either be one Observation instance or a list of observations. It ensures proper setup of per-detector random number generators using either a user-provided seed or a list of pre-initialized RNGs.

By default, the modified TOD is Observation.tod. If you want to modify some other field of the Observation class, use component:

for cur_obs in sim.observations:
# Allocate a new TOD for the nonlinear TOD alone
cur_obs.nl_tod = np.zeros_like(cur_obs.tod)

# Ask `apply_quadratic_nonlin_to_observations` to store the nonlinear TOD
# in `observations.nl_tod`
apply_quadratic_nonlin_to_observations(sim.observations, component="nl_tod", user_seed=1234)
Parameters:

  • observations (Observation or list of Observation) – A single Observation instance or a list of them.

  • nl_params (NonLinParams, optional) – Parameters defining the quadratic non-linearity model. If not provided, a default configuration is used.

  • component (str, optional) – Name of the TOD attribute to modify. Defaults to “tod”.

  • user_seed (int or None) – Base seed to build the RNG hierarchy and generate samples of the detector non-linearity factor, independently of the MPI distribution across detectors and time. The user is required to set this parameter.

  • (bool (conv_K_CMB_to_MJy_over_sr) – units conversion. Defaults to False.

  • optional) (Flag for temperature to spectral radiance) – units conversion. Defaults to False.

Raises:

  • TypeError – If observations is neither an Observation nor a list of them.

  • ValueError – If user_seed is not provided.

  • AssertionError – If the number of random generators does not match the number of detectors.