imap-processing 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

imap_processing/spacecraft/quaternions.py

@@ -0,0 +1,121 @@
+"""Spacecraft quaternion processing."""
+
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.cdf.imap_cdf_manager import ImapCdfAttributes
+from imap_processing.spice.time import met_to_ttj2000ns
+from imap_processing.utils import packet_file_to_datasets
+
+
+def load_quaternion_packets(packet_file: Path | str) -> xr.Dataset:
+    """
+    Load the raw quaternion packets from the packet file.
+
+    Parameters
+    ----------
+    packet_file : Path
+        Path to the packet file containing the quaternions in apid 594.
+
+    Returns
+    -------
+    xarray.Dataset
+        Dataset containing the raw quaternion packets.
+    """
+    xtce_packet_definition = Path(__file__).parent / "packet_definitions/scid_x252.xml"
+    datasets_by_apid = packet_file_to_datasets(
+        packet_file=packet_file, xtce_packet_definition=xtce_packet_definition
+    )
+    return datasets_by_apid[0x252]
+
+
+def assemble_quaternions(ds: xr.Dataset) -> xr.Dataset:
+    """
+    Assemble quaternions from the l1a dataset.
+
+    The quaternions are stored in separate variables for each component (x, y, z, s)
+    and for each 10 Hz sample of the 1s packet. i.e. there are 4 * 10 = 40 variables
+    in the initial dataset that we want to turn into 4 variables with a continuous
+    10 Hz sampling period.
+
+    The output dataset will have a single dimension "epoch" that will be the time
+    associated with each of the 10 Hz samples. There are 4 data variables: "quat_x",
+    "quat_y", "quat_z", "quat_s".
+
+    Parameters
+    ----------
+    ds : xarray.Dataset
+        Input dataset containing the 10Hz quaternions from packet 0x252 (APID 594).
+
+    Returns
+    -------
+    xarray.Dataset
+        Output dataset with the quaternions assembled into 4 variables with a
+        continuous 10 Hz sampling period.
+    """
+    # Our time is only given for the first timestamp
+    # We then add to it 0.1 increments and ravel the array to associate a specific time
+    # with each of the 10 samples
+    time = (
+        ds["SCIENCEDATA1HZ_QUAT_10_HZ_TIME".lower()].values[:, np.newaxis]
+        + np.arange(0, 1, 0.1)
+    ).ravel()
+    output_ds = xr.Dataset(coords={"epoch": time})
+    base_name = "FSW_ACS_QUAT_10_HZ_BUFFERED".lower()
+    for quat_i, label in enumerate(["x", "y", "z", "s"]):
+        # 0, 1, 2, .. 9 // 10, 11, 12, .. 19 // 20, 21, 22, .. 29 // 30, 31, 32, .. 39
+        names = [f"{base_name}_{i + quat_i * 10}" for i in range(10)]
+        quat = np.stack([ds[name] for name in names], axis=1).ravel()
+        output_ds[f"quat_{label}"] = ("epoch", quat)
+    return output_ds
+
+
+def process_quaternions(packet_file: Path | str) -> tuple[xr.Dataset, xr.Dataset]:
+    """
+    Generate l1a and l1b datasets from a packet file containing the raw quaternions.
+
+    This produces two CDF files: one for the l1a quaternions and one for the l1b
+    quaternions. The l1b quaternions are assembled into 4 variables: "quat_x",
+    "quat_y", "quat_z", "quat_s".
+
+    Parameters
+    ----------
+    packet_file : Path
+        Path to the packet file containing the quaternions in apid 594.
+
+    Returns
+    -------
+    xarray.Dataset
+        Dataset containing the l1a quaternions.
+    xarray.Dataset
+        Dataset containing the l1b quaternions.
+    """
+    l1a_ds = load_quaternion_packets(packet_file)
+
+    # Assemble the quaternions into the correct components
+    l1b_ds = assemble_quaternions(l1a_ds)
+
+    # Update dataset global attributes
+    attr_mgr = ImapCdfAttributes()
+    attr_mgr.add_instrument_global_attrs("spacecraft")
+    attr_mgr.add_instrument_variable_attrs(instrument="spacecraft", level=None)
+
+    l1a_ds.attrs.update(
+        attr_mgr.get_global_attributes("imap_spacecraft_l1a_quaternions")
+    )
+    l1b_ds.attrs.update(
+        attr_mgr.get_global_attributes("imap_spacecraft_l1b_quaternions")
+    )
+
+    # Update the epoch attribute
+    l1b_ds["epoch"] = met_to_ttj2000ns(l1b_ds["epoch"])
+    # check_schema=False keeps DEPEND_0 = '' from being auto added
+    epoch_attrs = attr_mgr.get_variable_attributes("epoch", check_schema=False)
+    l1b_ds["epoch"].attrs.update(epoch_attrs)
+
+    for var in ["quat_x", "quat_y", "quat_z", "quat_s"]:
+        l1b_ds[var].attrs.update(attr_mgr.get_variable_attributes(var))
+
+    return l1a_ds, l1b_ds

imap_processing/spice/geometry.py

@@ -63,7 +63,7 @@ class SpiceFrame(IntEnum):
 
 
 BORESIGHT_LOOKUP = {
-    SpiceFrame.IMAP_LO: np.array([0, -1, 0]),
+    SpiceFrame.IMAP_LO_BASE: np.array([0, -1, 0]),
     SpiceFrame.IMAP_HI_45: np.array([0, 1, 0]),
     SpiceFrame.IMAP_HI_90: np.array([0, 1, 0]),
     SpiceFrame.IMAP_ULTRA_45: np.array([0, 0, 1]),
@@ -136,7 +136,7 @@ def get_spacecraft_to_instrument_spin_phase_offset(instrument: SpiceFrame) -> fl
     """
     # TODO: Implement retrieval from SPICE?
     offset_lookup = {
-        SpiceFrame.IMAP_LO: 330 / 360,
+        SpiceFrame.IMAP_LO_BASE: 330 / 360,
         SpiceFrame.IMAP_HI_45: 255 / 360,
         SpiceFrame.IMAP_HI_90: 285 / 360,
         SpiceFrame.IMAP_ULTRA_45: 33 / 360,
@@ -268,7 +268,7 @@ def frame_transform_az_el(
     spherical_coords_in = np.array(
         [np.ones_like(az_el[..., 0]), az_el[..., 0], az_el[..., 1]]
     ).T
-    from_frame_cartesian = spherical_to_cartesian(spherical_coords_in, degrees=degrees)
+    from_frame_cartesian = spherical_to_cartesian(spherical_coords_in)
     # Transform to to_frame
     to_frame_cartesian = frame_transform(et, from_frame_cartesian, from_frame, to_frame)
     # Convert to spherical and extract azimuth/elevation
@@ -325,7 +325,7 @@ def instrument_pointing(
     """
     Compute the instrument pointing at the specified times.
 
-    By default, the coordinates returned are Latitude/Longitude coordinates in
+    By default, the coordinates returned are (Longitude, Latitude) coordinates in
     the reference frame `to_frame`. Cartesian coordinates can be returned if
     desired by setting `cartesian=True`.
 
@@ -425,14 +425,14 @@ def cartesian_to_spherical(
         - r : Distance of the point from the origin.
         - azimuth : angle in the xy-plane
           In degrees if degrees parameter is True (by default):
-          output range=[0, 360],
+          output range=[0, 360) degrees,
           otherwise in radians if degrees parameter is False:
-          output range=[0, 2*pi].
+          output range=[0, 2*pi) radians.
         - elevation : angle from the xy-plane
           In degrees if degrees parameter is True (by default):
-          output range=[0, 180],
+          output range=[-90, 90) degrees,
           otherwise in radians if degrees parameter is False:
-          output range=[-pi/2, pi/2].
+          output range=[-pi/2, pi/2) radians.
     """
     # Magnitude of the velocity vector
     magnitude_v = np.linalg.norm(v, axis=-1, keepdims=True)
@@ -457,9 +457,9 @@ def cartesian_to_spherical(
     return spherical_coords
 
 
-def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) -> NDArray:
+def spherical_to_cartesian(spherical_coords: NDArray) -> NDArray:
     """
-    Convert spherical coordinates to Cartesian coordinates.
+    Convert spherical coordinates (angles in degrees) to Cartesian coordinates.
 
     Parameters
     ----------
@@ -468,11 +468,8 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
         the spherical coordinates (r, azimuth, elevation):
 
         - r : Distance of the point from the origin.
-        - azimuth : angle in the xy-plane in radians [0, 2*pi].
-        - elevation : angle from the xy-plane in radians [-pi/2, pi/2].
-    degrees : bool
-        Set to True if input azimuth and elevation angles are in degrees.
-        Defaults to False.
+        - azimuth : angle in the xy-plane in degrees. Range is [0, 360) degrees.
+        - elevation : angle from the xy-plane in degrees. Range is [-90, 90) degrees.
 
     Returns
     -------
@@ -483,9 +480,9 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
     azimuth = spherical_coords[..., 1]
     elevation = spherical_coords[..., 2]
 
-    if degrees:
-        azimuth = np.radians(azimuth)
-        elevation = np.radians(elevation)
+    # Convert to radians for numpy trigonometric operations
+    azimuth = np.deg2rad(azimuth)
+    elevation = np.deg2rad(elevation)
 
     x = r * np.cos(elevation) * np.cos(azimuth)
     y = r * np.cos(elevation) * np.sin(azimuth)
@@ -496,7 +493,7 @@ def spherical_to_cartesian(spherical_coords: NDArray, degrees: bool = False) ->
     return cartesian_coords
 
 
-def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
+def cartesian_to_latitudinal(coords: NDArray, degrees: bool = True) -> NDArray:
     """
     Convert cartesian coordinates to latitudinal coordinates in radians.
 
@@ -511,7 +508,7 @@ def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
         with x, y, z-components.
     degrees : bool
         If True, the longitude and latitude coords are returned in degrees.
-        Defaults to False.
+        Defaults to True.
 
     Returns
     -------
@@ -532,7 +529,7 @@ def cartesian_to_latitudinal(coords: NDArray, degrees: bool = False) -> NDArray:
 
 def solar_longitude(
     et: Union[np.ndarray, float],
-    degrees: bool = False,
+    degrees: bool = True,
 ) -> Union[float, npt.NDArray]:
     """
     Compute the solar longitude of the Imap Spacecraft.
@@ -543,7 +540,7 @@ def solar_longitude(
         Ephemeris time(s) to at which to compute solar longitude.
     degrees : bool
         If True, the longitude is returned in degrees.
-        Defaults to False.
+        Defaults to True.
 
     Returns
     -------

imap_processing/spice/kernels.py

@@ -3,14 +3,9 @@
 import functools
 import logging
 import os
-from collections.abc import Generator
-from contextlib import contextmanager
-from pathlib import Path
 from typing import Any, Callable, Optional, Union, overload
 
-import numpy as np
 import spiceypy
-from numpy.typing import NDArray
 from spiceypy.utils.exceptions import SpiceyError
 
 from imap_processing import imap_module_directory
@@ -181,277 +176,6 @@ def ensure_spice(
         return _decorator
 
 
-@contextmanager
-def open_spice_ck_file(pointing_frame_path: Path) -> Generator[int, None, None]:
-    """
-    Context manager for handling SPICE CK files.
-
-    Parameters
-    ----------
-    pointing_frame_path : str
-        Path to the CK file.
-
-    Yields
-    ------
-    handle : int
-        Handle to the opened CK file.
-    """
-    # TODO: We will need to figure out if ck kernel changes
-    # and how that will affect appending to the pointing
-    # frame kernel.
-    if pointing_frame_path.exists():
-        handle = spiceypy.dafopw(str(pointing_frame_path))
-    else:
-        handle = spiceypy.ckopn(str(pointing_frame_path), "CK", 0)
-    try:
-        yield handle
-    finally:
-        spiceypy.ckcls(handle)
-
-
-@ensure_spice
-def create_pointing_frame(pointing_frame_path: Path, ck_path: Path) -> None:
-    """
-    Create the pointing frame.
-
-    Parameters
-    ----------
-    pointing_frame_path : pathlib.Path
-        Location of pointing frame kernel.
-    ck_path : pathlib.Path
-        Location of the CK kernel.
-
-    Notes
-    -----
-    Kernels required to be furnished:
-    "imap_science_0001.tf",
-    "imap_sclk_0000.tsc",
-    "imap_sim_ck_2hr_2secsampling_with_nutation.bc" or
-    "sim_1yr_imap_attitude.bc",
-    "imap_wkcp.tf",
-    "naif0012.tls"
-
-    Assumptions:
-    - The MOC has removed timeframe in which nutation/procession are present.
-    TODO: We may come back and have a check for this.
-    - We will continue to append to the pointing frame kernel.
-    TODO: Figure out how we want to handle the file size becoming too large.
-    - For now we can only furnish a single ck kernel.
-    TODO: This will not be the case once we add the ability to query the .csv.
-
-    References
-    ----------
-    https://numpydoc.readthedocs.io/en/latest/format.html#references
-    """
-    # Get IDs.
-    # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.gipool
-    id_imap_dps = spiceypy.gipool("FRAME_IMAP_DPS", 0, 1)
-    id_imap_sclk = spiceypy.gipool("CK_-43000_SCLK", 0, 1)
-
-    # Verify that only ck_path kernel is loaded.
-    count = spiceypy.ktotal("ck")
-    loaded_ck_kernel, _, _, _ = spiceypy.kdata(count - 1, "ck")
-
-    if count != 1 or str(ck_path) != loaded_ck_kernel:
-        raise ValueError(f"Error: Expected CK kernel {ck_path}")
-
-    # If the pointing frame kernel already exists, find the last time.
-    if pointing_frame_path.exists():
-        # Get the last time in the pointing frame kernel.
-        pointing_cover = spiceypy.ckcov(
-            str(pointing_frame_path), int(id_imap_dps), True, "SEGMENT", 0, "TDB"
-        )
-        num_segments = spiceypy.wncard(pointing_cover)
-        _, et_end_pointing_frame = spiceypy.wnfetd(pointing_cover, num_segments - 1)
-    else:
-        et_end_pointing_frame = None
-
-    # TODO: Query for .csv file to get the pointing start and end times.
-    # TODO: Remove next four lines once query is added.
-    id_imap_spacecraft = spiceypy.gipool("FRAME_IMAP_SPACECRAFT", 0, 1)
-    ck_cover = spiceypy.ckcov(
-        str(ck_path), int(id_imap_spacecraft), True, "INTERVAL", 0, "TDB"
-    )
-    num_intervals = spiceypy.wncard(ck_cover)
-
-    with open_spice_ck_file(pointing_frame_path) as handle:
-        # TODO: this will change to the number of pointings.
-        for i in range(num_intervals):
-            # Get the coverage window
-            # TODO: this will change to pointing start and end time.
-            et_start, et_end = spiceypy.wnfetd(ck_cover, i)
-            et_times = _get_et_times(et_start, et_end)
-
-            # TODO: remove after query is added.
-            if (
-                et_end_pointing_frame is not None
-                and et_times[0] < et_end_pointing_frame
-            ):
-                break
-
-            # Create a rotation matrix
-            rotation_matrix = _create_rotation_matrix(et_times)
-
-            # Convert the rotation matrix to a quaternion.
-            # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.m2q
-            q_avg = spiceypy.m2q(rotation_matrix)
-
-            # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.sce2c
-            # Convert start and end times to SCLK.
-            sclk_begtim = spiceypy.sce2c(int(id_imap_sclk), et_times[0])
-            sclk_endtim = spiceypy.sce2c(int(id_imap_sclk), et_times[-1])
-
-            # Create the pointing frame kernel.
-            # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.ckw02
-            spiceypy.ckw02(
-                # Handle of an open CK file.
-                handle,
-                # Start time of the segment.
-                sclk_begtim,
-                # End time of the segment.
-                sclk_endtim,
-                # Pointing frame ID.
-                int(id_imap_dps),
-                # Reference frame.
-                "ECLIPJ2000",  # Reference frame
-                # Identifier.
-                "IMAP_DPS",
-                # Number of pointing intervals.
-                1,
-                # Start times of individual pointing records within segment.
-                # Since there is only a single record this is equal to sclk_begtim.
-                np.array([sclk_begtim]),
-                # End times of individual pointing records within segment.
-                # Since there is only a single record this is equal to sclk_endtim.
-                np.array([sclk_endtim]),  # Single stop time
-                # Average quaternion.
-                q_avg,
-                # 0.0 Angular rotation terms.
-                np.array([0.0, 0.0, 0.0]),
-                # Rates (seconds per tick) at which the quaternion and
-                # angular velocity change.
-                np.array([1.0]),
-            )
-
-
-def _get_et_times(et_start: float, et_end: float) -> NDArray[np.float64]:
-    """
-    Get times for pointing start and stop.
-
-    Parameters
-    ----------
-    et_start : float
-        Pointing start time.
-    et_end : float
-        Pointing end time.
-
-    Returns
-    -------
-    et_times : numpy.ndarray
-        Array of times between et_start and et_end.
-    """
-    # TODO: Queried pointing start and stop times here.
-    # TODO removing the @ensure_spice decorator when using the repointing table.
-
-    # 1 spin/15 seconds; 10 quaternions / spin.
-    num_samples = (et_end - et_start) / 15 * 10
-    # There were rounding errors when using spiceypy.pxform so np.ceil and np.floor
-    # were used to ensure the start and end times were included in the array.
-    et_times = np.linspace(
-        np.ceil(et_start * 1e6) / 1e6, np.floor(et_end * 1e6) / 1e6, int(num_samples)
-    )
-
-    return et_times
-
-
-@ensure_spice
-def _average_quaternions(et_times: np.ndarray) -> NDArray:
-    """
-    Average the quaternions.
-
-    Parameters
-    ----------
-    et_times : numpy.ndarray
-        Array of times between et_start and et_end.
-
-    Returns
-    -------
-    q_avg : np.ndarray
-        Average quaternion.
-    """
-    aggregate = np.zeros((4, 4))
-    for tdb in et_times:
-        # we use a quick and dirty method here for grabbing the quaternions
-        # from the attitude kernel.  Depending on how well the kernel input
-        # data is built and sampled, there may or may not be aliasing with this
-        # approach.  If it turns out that we need to pull the quaternions
-        # directly from the CK there are several routines that exist to do this
-        # but it's not straight forward.  We'll revisit this if needed.
-
-        # Rotation matrix from IMAP spacecraft frame to ECLIPJ2000.
-        # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.pxform
-        body_rots = spiceypy.pxform("IMAP_SPACECRAFT", "ECLIPJ2000", tdb)
-        # Convert rotation matrix to quaternion.
-        # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.m2q
-        body_quat = spiceypy.m2q(body_rots)
-
-        # Standardize the quaternion so that they may be compared.
-        body_quat = body_quat * np.sign(body_quat[0])
-        # Aggregate quaternions into a single matrix.
-        aggregate += np.outer(body_quat, body_quat)
-
-    # Reference: "On Averaging Rotations".
-    # Link: https://link.springer.com/content/pdf/10.1023/A:1011129215388.pdf
-    aggregate /= len(et_times)
-
-    # Compute eigen values and vectors of the matrix A
-    # Eigenvalues tell you how much "influence" each
-    # direction (eigenvector) has.
-    # The largest eigenvalue corresponds to the direction
-    # that has the most influence.
-    # The eigenvector corresponding to the largest
-    # eigenvalue points in the direction that has the most
-    # combined rotation influence.
-    eigvals, eigvecs = np.linalg.eig(aggregate)
-    # q0: The scalar part of the quaternion.
-    # q1, q2, q3: The vector part of the quaternion.
-    q_avg = eigvecs[:, np.argmax(eigvals)]
-
-    return q_avg
-
-
-def _create_rotation_matrix(et_times: np.ndarray) -> NDArray:
-    """
-    Create a rotation matrix.
-
-    Parameters
-    ----------
-    et_times : numpy.ndarray
-        Array of times between et_start and et_end.
-
-    Returns
-    -------
-    rotation_matrix : np.ndarray
-        Rotation matrix.
-    """
-    # Averaged quaternions.
-    q_avg = _average_quaternions(et_times)
-
-    # Converts the averaged quaternion (q_avg) into a rotation matrix
-    # and get inertial z axis.
-    # https://spiceypy.readthedocs.io/en/main/documentation.html#spiceypy.spiceypy.q2m
-    z_avg = spiceypy.q2m(list(q_avg))[:, 2]
-    # y_avg is perpendicular to both z_avg and the standard Z-axis.
-    y_avg = np.cross(z_avg, [0, 0, 1])
-    # x_avg is perpendicular to y_avg and z_avg.
-    x_avg = np.cross(y_avg, z_avg)
-
-    # Construct the rotation matrix from x_avg, y_avg, z_avg
-    rotation_matrix = np.asarray([x_avg, y_avg, z_avg])
-
-    return rotation_matrix
-
-
 def furnish_time_kernel() -> None:
     """Furnish the time kernels."""
     spice_test_data_path = imap_module_directory / "tests/spice/test_data"