1019 calculate instrument spin phase

imap_processing/spice/geometry.py

@@ -235,6 +235,74 @@ def get_spacecraft_spin_phase(
     return spin_phases
 
 
+def get_instrument_spin_phase(
+    query_met_times: Union[float, npt.NDArray],
+    instrument: SpiceFrame,
+) -> Union[float, npt.NDArray]:
+    """
+    Get the instrument spin phase for the input query times.
+
+    Formula to calculate spin phase:
+        instrument_spin_phase = (spacecraft_spin_phase + instrument_spin_offset) % 1
+
+    Parameters
+    ----------
+    query_met_times : float or np.ndarray
+        Query times in Mission Elapsed Time (MET).
+    instrument : SpiceFrame
+        Instrument frame to calculate spin phase for.
+
+    Returns
+    -------
+    spin_phase : float or np.ndarray
+        Instrument spin phase for the input query times. Spin phase is a
+        floating point number in the range [0, 1) corresponding to the
+        spin angle / 360.
+    """
+    spacecraft_spin_phase = get_spacecraft_spin_phase(query_met_times)
+    instrument_spin_phase_offset = get_spacecraft_to_instrument_spin_phase_offset(
+        instrument
+    )
+    return (spacecraft_spin_phase + instrument_spin_phase_offset) % 1
+
+
+def get_spacecraft_to_instrument_spin_phase_offset(instrument: SpiceFrame) -> float:
+    """
+    Get the spin phase offset from the spacecraft to the instrument.
+
+    For now, the offset is a fixed lookup based on `Table 1: Nominal Instrument
+    to S/C CS Transformations` in document `7516-0011_drw.pdf`. These fixed
+    values will need to be updated based on calibration data or retrieved using
+    SPICE and the latest IMAP frame kernel.
+
+    Parameters
+    ----------
+    instrument : SpiceFrame
+        Instrument to get the spin phase offset for.
+
+    Returns
+    -------
+    spacecraft_to_instrument_spin_phase_offset : float
+        The spin phase offset from the spacecraft to the instrument.
+    """
+    # TODO: Implement retrieval from SPICE?
+    offset_lookup = {
+        SpiceFrame.IMAP_LO: 330 / 360,
+        SpiceFrame.IMAP_HI_45: 255 / 360,
+        SpiceFrame.IMAP_HI_90: 285 / 360,
+        SpiceFrame.IMAP_ULTRA_45: 33 / 360,
+        SpiceFrame.IMAP_ULTRA_90: 210 / 360,
+        SpiceFrame.IMAP_SWAPI: 168 / 360,
+        SpiceFrame.IMAP_IDEX: 90 / 360,
+        SpiceFrame.IMAP_CODICE: 136 / 360,
+        SpiceFrame.IMAP_HIT: 30 / 360,
+        SpiceFrame.IMAP_SWE: 153 / 360,
+        SpiceFrame.IMAP_GLOWS: 127 / 360,
+        SpiceFrame.IMAP_MAG: 0 / 360,
+    }
+    return offset_lookup[instrument]
+
+
 @typing.no_type_check
 @ensure_spice
 def frame_transform(

imap_processing/tests/spice/test_geometry.py

@@ -9,8 +9,10 @@
     SpiceBody,
     SpiceFrame,
     frame_transform,
+    get_instrument_spin_phase,
     get_rotation_matrix,
     get_spacecraft_spin_phase,
+    get_spacecraft_to_instrument_spin_phase_offset,
     get_spin_data,
     imap_state,
     instrument_pointing,
@@ -122,6 +124,58 @@ def test_get_spin_data():
     }, "Spin data must have the specified fields."
 
 
+@pytest.mark.parametrize(
+    "instrument",
+    [
+        SpiceFrame.IMAP_LO,
+        SpiceFrame.IMAP_HI_45,
+        SpiceFrame.IMAP_HI_90,
+        SpiceFrame.IMAP_ULTRA_45,
+        SpiceFrame.IMAP_ULTRA_90,
+        SpiceFrame.IMAP_SWAPI,
+        SpiceFrame.IMAP_IDEX,
+        SpiceFrame.IMAP_CODICE,
+        SpiceFrame.IMAP_HIT,
+        SpiceFrame.IMAP_SWE,
+        SpiceFrame.IMAP_GLOWS,
+        SpiceFrame.IMAP_MAG,
+    ],
+)
+def test_get_instrument_spin_phase(instrument, fake_spin_data):
+    """Test coverage for get_instrument_spin_phase()"""
+    met_times = np.array([7.5, 30, 61, 75, 106, 121, 136])
+    expected_nan_mask = np.array([False, False, True, False, True, True, False])
+    inst_phase = get_instrument_spin_phase(met_times, instrument)
+    assert inst_phase.shape == met_times.shape
+    np.testing.assert_array_equal(np.isnan(inst_phase), expected_nan_mask)
+    assert np.logical_and(
+        0 <= inst_phase[~expected_nan_mask], inst_phase[~expected_nan_mask] < 1
+    ).all()
+
+
+@pytest.mark.parametrize(
+    "instrument, expected_offset",
+    [
+        (SpiceFrame.IMAP_LO, 330 / 360),
+        (SpiceFrame.IMAP_HI_45, 255 / 360),
+        (SpiceFrame.IMAP_HI_90, 285 / 360),
+        (SpiceFrame.IMAP_ULTRA_45, 33 / 360),
+        (SpiceFrame.IMAP_ULTRA_90, 210 / 360),
+        (SpiceFrame.IMAP_SWAPI, 168 / 360),
+        (SpiceFrame.IMAP_IDEX, 90 / 360),
+        (SpiceFrame.IMAP_CODICE, 136 / 360),
+        (SpiceFrame.IMAP_HIT, 30 / 360),
+        (SpiceFrame.IMAP_SWE, 153 / 360),
+        (SpiceFrame.IMAP_GLOWS, 127 / 360),
+        (SpiceFrame.IMAP_MAG, 0 / 360),
+    ],
+)
+def test_get_spacecraft_to_instrument_spin_phase_offset(instrument, expected_offset):
+    """Test coverage for get_spacecraft_to_instrument_spin_phase_offset()"""
+    result = get_spacecraft_to_instrument_spin_phase_offset(instrument)
+    assert result == expected_offset
+
+
 @pytest.mark.parametrize(
     "et_strings, position, from_frame, to_frame",
     [