Ideal Half Wave Plate#

The rotation of the polarization angle induced by a HWP can be included in the returned pointing information by passing an instance of a descendant of the class HWP to the method Simulation.set_hwp(). Here is an example:

import litebird_sim as lbs

sim = lbs.Simulation(
    start_time=0,
    duration_s=100.0,
    random_seed=12345,
)

sim.set_scanning_strategy(
    lbs.SpinningScanningStrategy(
        spin_sun_angle_rad=0.785_398_163_397_448_3,
        precession_rate_hz=8.664_850_513_998_931e-05,
        spin_rate_hz=0.000_833_333_333_333_333_4,
        start_time=sim.start_time,
    ),
    delta_time_s=60,
)

sim.set_instrument(
    instrument = lbs.InstrumentInfo(
        boresight_rotangle_rad=0.0,
        spin_boresight_angle_rad=0.872_664_625_997_164_8,
        spin_rotangle_rad=3.141_592_653_589_793,
    )
)

sim.set_hwp(
    lbs.IdealHWP(ang_speed_radpsec=4.084_070_449_666_731),
)

det = lbs.DetectorInfo(
    name="Boresight_detector",
    sampling_rate_hz=1.0,
    quat=[0.0, 0.0, 0.0, 1.0],
)
obs, = sim.create_observations(detectors=[det])

sim.prepare_pointings()

pointing, hwp_angle = sim.observations[0].get_pointings()

This example uses the IdealHWP, which represents an ideal spinning HWP. The method get_pointings() returns both pointing and hwp angle on the fly. As shown before a similar syntax allow to precompute the pointing and the hwp angle:

sim.prepare_pointings()
sim.precompute_pointings()

sim.observations[0].pointing_matrix.shape
sim.observations[0].hwp_angle.shape

This fills the fields pointing_matrix and hwp_angle for all the observations in the current simulation.

API reference#

class litebird_sim.hwp.HWP#

Bases: object

Abstract class that represents a generic HWP

Being an abstract class, you should never instantiate it. It is used to signal the type of parameters to some functions (e.g., get_pointings()).

If you need to use a HWP object, you should better use derived classes like IdealHWP.

add_hwp_angle(pointing_buffer, start_time_s: float, delta_time_s: float) → None#

Modify pointings so that they include the effect of the HWP

This method must be redefined in derived classes. The parameter pointing_buffer must be a D×N×3 matrix representing the three angles (colatitude, longitude, orientation) for D detectors and N measurements. The function only alters orientation and returns nothing.

The parameters start_time_s and delta_time_s specify the time of the first sample in pointings and must be floating-point values; this means that you should already have converted any AstroPy time to a plain scalar before calling this method.

Warning: this changes the interpretation of the ψ variable in the pointings! You should better use get_hwp_angle() and keep ψ and the α angle of the HWP separate. This method is going to be deprecated in a future release of the LiteBIRD Simulation Framework.

apply_hwp_to_pointings(start_time_s: float, delta_time_s: float, bore2ecl_quaternions_inout: ndarray[Any, dtype[_ScalarType_co]], hwp_angle_out: ndarray[Any, dtype[_ScalarType_co]]) → None#

Simulates the presence of a HWP on the pointings and the HWP angle

This method must be redefined in derived classes. The parameter start_time_s specifies the time of the first sample in pointings and must be a floating-point value; this means that you should already have converted any AstroPy time to a plain scalar before calling this method. The parameter delta_time_s is the inverse of the sampling frequency and must be expressed in seconds.

The result is saved in the NumPy array hwp_angle_out, which must have already been allocated with the appropriate number of samples. However, if the HWP is not ideal, it is possible that the bore2ecl_quaternions_inout matrix, whose shape is (N, 4) and contains N quaternions, is changed by this method, typically via a multiplication with a rotation simulating a wobbling effect. (Multiplying a quaternion on the left of bore2ecl_quaternions_inout means that you are adding a rotation at the end of the chain of transformations, i.e., after the conversion to the Ecliptic reference frame. Multiplying a quaternion on the right means that you are introducing a new rotation between the reference frame of the detector and of the boresight of the focal plane.)

Parameters:

  • start_time_s

  • delta_time_s

  • bore2ecl_quaternions_inout

  • hwp_angle_out

Returns:

get_hwp_angle(output_buffer, start_time_s: float, delta_time_s: float) → None#

Calculate the rotation angle of the HWP

This method must be redefined in derived classes. The parameter start_time_s specifies the time of the first sample in pointings and must be a floating-point value; this means that you should already have converted any AstroPy time to a plain scalar before calling this method. The parameter delta_time_s is the inverse of the sampling frequency and must be expressed in seconds.

The result will be saved in output_buffer, which must have already been allocated with the appropriate number of samples.

read_from_hdf5(input_dataset: Dataset) → None#
write_to_hdf5(output_file: File, field_name: str, compression: str | None = None) → Dataset#

Write the definition of the HWP into a HDF5 file

You should never call this function directly. It is used to save Observation objects to disk.

class litebird_sim.hwp.IdealHWP(ang_speed_radpsec: float, start_angle_rad=0.0)#

Bases: HWP

A ideal half-wave plate that spins regularly

This class represents a perfect HWP that spins with constant angular velocity. The constructor accepts the angular speed, expressed in rad/sec, and the start angle (in radians). The latter should be referred to the first time sample in the simulation, i.e., the earliest sample simulated in any of the MPI processes used for the simulation.

Given a polarization angle \(\psi\), this class turns it into \(\psi + \psi_\text{hwp,0} + 2 \omega_\text{hwp} t\), where \(\psi_\text{hwp,0}\) is the start angle specified in the constructor and \(\omega_\text{hwp}\) is the angular speed of the HWP.

add_hwp_angle(pointing_buffer, start_time_s: float, delta_time_s: float) → None#

Modify pointings so that they include the effect of the HWP

This method must be redefined in derived classes. The parameter pointing_buffer must be a D×N×3 matrix representing the three angles (colatitude, longitude, orientation) for D detectors and N measurements. The function only alters orientation and returns nothing.

The parameters start_time_s and delta_time_s specify the time of the first sample in pointings and must be floating-point values; this means that you should already have converted any AstroPy time to a plain scalar before calling this method.

Warning: this changes the interpretation of the ψ variable in the pointings! You should better use get_hwp_angle() and keep ψ and the α angle of the HWP separate. This method is going to be deprecated in a future release of the LiteBIRD Simulation Framework.

apply_hwp_to_pointings(start_time_s: float, delta_time_s: float, bore2ecl_quaternions_inout: ndarray[Any, dtype[_ScalarType_co]], hwp_angle_out: ndarray[Any, dtype[_ScalarType_co]]) → None#

Simulates the presence of a HWP on the pointings and the HWP angle

This method must be redefined in derived classes. The parameter start_time_s specifies the time of the first sample in pointings and must be a floating-point value; this means that you should already have converted any AstroPy time to a plain scalar before calling this method. The parameter delta_time_s is the inverse of the sampling frequency and must be expressed in seconds.

The result is saved in the NumPy array hwp_angle_out, which must have already been allocated with the appropriate number of samples. However, if the HWP is not ideal, it is possible that the bore2ecl_quaternions_inout matrix, whose shape is (N, 4) and contains N quaternions, is changed by this method, typically via a multiplication with a rotation simulating a wobbling effect. (Multiplying a quaternion on the left of bore2ecl_quaternions_inout means that you are adding a rotation at the end of the chain of transformations, i.e., after the conversion to the Ecliptic reference frame. Multiplying a quaternion on the right means that you are introducing a new rotation between the reference frame of the detector and of the boresight of the focal plane.)

Parameters:

  • start_time_s

  • delta_time_s

  • bore2ecl_quaternions_inout

  • hwp_angle_out

Returns:

get_hwp_angle(output_buffer, start_time_s: float, delta_time_s: float) → None#

Calculate the rotation angle of the HWP

This method must be redefined in derived classes. The parameter start_time_s specifies the time of the first sample in pointings and must be a floating-point value; this means that you should already have converted any AstroPy time to a plain scalar before calling this method. The parameter delta_time_s is the inverse of the sampling frequency and must be expressed in seconds.

The result will be saved in output_buffer, which must have already been allocated with the appropriate number of samples.

read_from_hdf5(input_dataset: Dataset) → None#
write_to_hdf5(output_file: File, field_name: str, compression: str | None = None) → Dataset#

Write the definition of the HWP into a HDF5 file

You should never call this function directly. It is used to save Observation objects to disk.

litebird_sim.hwp.read_hwp_from_hdf5(input_file: File, field_name: str) → HWP#