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

imap_processing/ialirt/l0/mag_l0_ialirt_data.py

@@ -0,0 +1,155 @@
+"""Classes for Level 0 MAG I-ALiRT data."""
+
+# Science samples are split across 4 sequential packets so
+# several packets need to be processed before a single science
+# sample can be processed. The packets are as follows:
+
+from __future__ import annotations
+
+
+class Packet0:
+    """
+    Class for packet 0.
+
+    Parameters
+    ----------
+    status : int
+        24-bit integer value.
+
+    Notes
+    -----
+    Bits 23-22 → Packet Number (2-bit value)
+    Bits 21-17 → hk1v5_warn, hk1v5_danger, hk1v5c_warn, hk1v5c_danger,
+    hk1v8_warn (5-bit value)
+    Bits 16-13 → hk1v8_danger, hk1v8c_warn, hk1v8c_danger (4-bit value)
+    Bit  5 → fob_saturated (1-bit value)
+    Bit  4 → fib_saturated (1-bit value)
+    Bits 3-0 → mode (4-bit value)
+    Bits 12-6 → icu_temp (7-bit value)
+    """
+
+    def __init__(self, status: int) -> None:
+        # +1.5v voltage warning flag raised
+        self.hk1v5_warn = (status >> 20) & 0x01
+        # +1.5v voltage danger flag raised
+        self.hk1v5_danger = (status >> 19) & 0x01
+        # +1.5v current warning flag raised
+        self.hk1v5c_warn = (status >> 18) & 0x01
+        # +1.5v current danger flag raised
+        self.hk1v5c_danger = (status >> 17) & 0x01
+        # +1.8v voltage warning flag raised
+        self.hk1v8_warn = (status >> 16) & 0x01
+        # +1.8v voltage danger flag raised
+        self.hk1v8_danger = (status >> 15) & 0x01
+        # +1.8v current warning flag raised
+        self.hk1v8c_warn = (status >> 14) & 0x01
+        # +1.8v current danger flag raised
+        self.hk1v8c_danger = (status >> 13) & 0x01
+        # Outboard (MAGo) sensor is saturated (danger)
+        self.fob_saturated = (status >> 5) & 0x01
+        # Inboard (MAGi) sensor is saturated (danger)
+        self.fib_saturated = (status >> 4) & 0x01
+        # Instrument mode
+        self.mode = (status >> 0) & 0x0F
+        # instrument control unit temperature (top 7/16 bits, eng. units)
+        self.icu_temp = ((status >> 6) & 0x7F) << 5
+
+
+class Packet1:
+    """
+    Class for packet 1.
+
+    Parameters
+    ----------
+    status : int
+        24-bit integer value.
+
+    Notes
+    -----
+    Bit  5 → pri_isvalid (1-bit value)
+    Bits 4-1 → hk2v5_warn, hk2v5_danger, hk2v5c_warn, hk2v5c_danger (4-bit value)
+    Bits 16-9 → hk3v3 (8-bit value)
+    Bits 8-0 → hk3v3_current (9-bit value)
+    """
+
+    def __init__(self, status: int) -> None:
+        # +2.5v voltage warning flag raised
+        self.hk2v5_warn = (status >> 20) & 0x01
+        # +2.5v voltage danger flag raised
+        self.hk2v5_danger = (status >> 19) & 0x01
+        # +2.5v current warning flag raised
+        self.hk2v5c_warn = (status >> 18) & 0x01
+        # +2.5v current warning flag raised
+        self.hk2v5c_danger = (status >> 17) & 0x01
+        # +3.3v voltage (top 8/16 bits, in eng. units)
+        self.hk3v3 = ((status >> 9) & 0xFF) << 4
+        # +3.3v current (top 9/16 bits, in eng. units)
+        self.hk3v3_current = ((status >> 0) & 0x1FF) << 3
+        # Primary sensor (typically MAGo) science data is valid
+        self.pri_isvalid = (status >> 21) & 0x01
+
+
+class Packet2:
+    """
+    Class for packet 2.
+
+    Parameters
+    ----------
+    status : int
+        24-bit integer value.
+
+    Notes
+    -----
+    Bits 23-22 → Packet Number (2-bit value)
+    Bits 21-17 → Various warning/danger flags (5-bit value)
+    Bits 16-9 → hkn8v5 (8-bit value)
+    Bits 8-0 → hkn8v5_current (9-bit value)
+    """
+
+    def __init__(self, status: int) -> None:
+        # +8.5v voltage warning flag raised
+        self.hkp8v5_warn = (status >> 20) & 0x01
+        # +8.5v voltage danger flag raised
+        self.hkp8v5_danger = (status >> 19) & 0x01
+        # +8.5v current warning flag raised
+        self.hkp8v5c_warn = (status >> 18) & 0x01
+        # +8.5v current danger flag raised
+        self.hkp8v5c_danger = (status >> 17) & 0x01
+        # -8.5v voltage (top 8/16 bits, in eng. units)
+        self.hkn8v5 = ((status >> 9) & 0xFF) << 4
+        # -8.5v current (top 9/16 bits, in eng. units)
+        self.hkn8v5_current = ((status >> 0) & 0x1FF) << 3
+
+
+class Packet3:
+    """
+    Class for packet 3.
+
+    Parameters
+    ----------
+    status : int
+        24-bit integer value.
+
+    Notes
+    -----
+    Bits 20-13 → fob_temp (8-bit value, shifted left by 4)
+    Bits 12-5 → fib_temp (8-bit value, shifted left by 4)
+    Bits 4-3 → fob_range (2-bit value)
+    Bits 2-1 → fib_range (2-bit value)
+    Bit 0 → multbit_errs (1-bit value)
+    Bit 5 → sec_isvalid (1-bit value, overlapping with fib_temp extraction)
+    """
+
+    def __init__(self, status: int) -> None:
+        # Temp of outboard (MAGo) sensor (top 8/16 bits, in eng. units)
+        self.fob_temp = ((status >> 13) & 0xFF) << 4
+        # Temp of outboard (MAGo) sensor (top 8/16 bits, in eng. units)
+        self.fib_temp = ((status >> 5) & 0xFF) << 4
+        # Outboard (MAGo) sensor range [0-3]
+        self.fob_range = (status >> 3) & 0x03
+        # Inboard (MAGi) sensor range [0-3]
+        self.fib_range = (status >> 1) & 0x03
+        # Multiple (SEU) memory error bits danger flag raised
+        self.multbit_errs = (status >> 0) & 0x01
+        # Secondary sensor (typically MAGi) science data is valid
+        self.sec_isvalid = (status >> 21) & 0x01

imap_processing/ialirt/l0/parse_mag.py

@@ -0,0 +1,246 @@
+"""Functions to support I-ALiRT MAG packet parsing."""
+
+import logging
+
+import numpy as np
+import xarray as xr
+
+from imap_processing.ialirt.l0.mag_l0_ialirt_data import (
+    Packet0,
+    Packet1,
+    Packet2,
+    Packet3,
+)
+from imap_processing.ialirt.utils.grouping import find_groups
+from imap_processing.ialirt.utils.time import calculate_time
+
+logger = logging.getLogger(__name__)
+
+
+def get_pkt_counter(status_values: xr.DataArray) -> xr.DataArray:
+    """
+    Get the packet counters.
+
+    Parameters
+    ----------
+    status_values : xr.DataArray
+        Status data.
+
+    Returns
+    -------
+    pkt_counters : xr.DataArray
+        Packet counters.
+    """
+    # mag_status is a 24 bit unsigned field
+    # The leading 2 bits of STATUS are a 2 bit 0-3 counter
+    pkt_counter = (status_values >> 22) & 0x03
+
+    return pkt_counter
+
+
+def get_status_data(status_values: xr.DataArray, pkt_counters: xr.DataArray) -> dict:
+    """
+    Get the status data.
+
+    Parameters
+    ----------
+    status_values : xr.DataArray
+        Status data.
+    pkt_counters : xr.DataArray
+        Packet counters.
+
+    Returns
+    -------
+    combined_packets : dict
+        Decoded packets.
+    """
+    decoders = {
+        0: Packet0,
+        1: Packet1,
+        2: Packet2,
+        3: Packet3,
+    }
+
+    combined_packets = {}
+
+    for pkt_num, decoder in decoders.items():
+        status_subset = status_values[pkt_counters == pkt_num]
+        decoded_packet = decoder(int(status_subset))
+        combined_packets.update(vars(decoded_packet))
+
+    return combined_packets
+
+
+def get_bytes(val: int) -> list[int]:
+    """
+    Extract three bytes from a 24-bit integer.
+
+    Parameters
+    ----------
+    val : int
+        24-bit integer value.
+
+    Returns
+    -------
+    list[int]
+        List of three extracted bytes.
+    """
+    return [
+        (val >> 16) & 0xFF,  # Most significant byte (Byte2)
+        (val >> 8) & 0xFF,  # Middle byte (Byte1)
+        (val >> 0) & 0xFF,  # Least significant byte (Byte0)
+    ]
+
+
+def extract_magnetic_vectors(science_values: xr.DataArray) -> dict:
+    """
+    Extract the magnetic vectors.
+
+    Parameters
+    ----------
+    science_values : xr.DataArray
+        Science data.
+
+    Returns
+    -------
+    vectors : dict
+        Magnetic vectors.
+    """
+    # Primary sensor:
+    pri_x = (int(science_values[0]) >> 8) & 0xFFFF
+    pri_y = ((int(science_values[0]) << 8) & 0xFF00) | (
+        (int(science_values[1]) >> 16) & 0xFF
+    )
+    pri_z = int(science_values[1]) & 0xFFFF
+
+    # Secondary sensor:
+    sec_x = (int(science_values[2]) >> 8) & 0xFFFF
+    sec_y = ((int(science_values[2]) << 8) & 0xFF00) | (
+        (int(science_values[3]) >> 16) & 0xFF
+    )
+    sec_z = int(science_values[3]) & 0xFFFF
+
+    vectors = {
+        "pri_x": pri_x,
+        "pri_y": pri_y,
+        "pri_z": pri_z,
+        "sec_x": sec_x,
+        "sec_y": sec_y,
+        "sec_z": sec_z,
+    }
+
+    return vectors
+
+
+def get_time(grouped_data: xr.Dataset, group: int, pkt_counter: xr.DataArray) -> dict:
+    """
+    Get the time for the grouped data.
+
+    Parameters
+    ----------
+    grouped_data : xr.Dataset
+        Grouped data.
+    group : int
+        Group number.
+    pkt_counter : xr.DataArray
+        Packet counter.
+
+    Returns
+    -------
+    time_data : dict
+        Coarse and fine time for Primary and Secondary Sensors.
+    """
+    pri_coarsetm = grouped_data["mag_acq_tm_coarse"][
+        (grouped_data["group"] == group).values
+    ][pkt_counter == 0]
+
+    pri_fintm = grouped_data["mag_acq_tm_fine"][
+        (grouped_data["group"] == group).values
+    ][pkt_counter == 0]
+
+    sec_coarsetm = grouped_data["mag_acq_tm_coarse"][
+        (grouped_data["group"] == group).values
+    ][pkt_counter == 2]
+
+    sec_fintm = grouped_data["mag_acq_tm_fine"][
+        (grouped_data["group"] == group).values
+    ][pkt_counter == 2]
+
+    time_data = {
+        "pri_coarsetm": int(pri_coarsetm),
+        "pri_fintm": int(pri_fintm),
+        "sec_coarsetm": int(sec_coarsetm),
+        "sec_fintm": int(sec_fintm),
+    }
+
+    return time_data
+
+
+def parse_packet(accumulated_data: xr.Dataset) -> list[dict]:
+    """
+    Parse the MAG packets.
+
+    Parameters
+    ----------
+    accumulated_data : xr.Dataset
+        Packets dataset accumulated over 1 min.
+
+    Returns
+    -------
+    mag_data : list[dict]
+        Dictionaries of the parsed data product.
+    """
+    logger.info(
+        f"Parsing MAG for time: {accumulated_data['mag_acq_tm_coarse'].min().values} - "
+        f"{accumulated_data['mag_acq_tm_coarse'].max().values}."
+    )
+
+    # Note that the fine time second is split into 65535.
+    time_seconds = calculate_time(
+        accumulated_data["mag_acq_tm_coarse"],
+        accumulated_data["mag_acq_tm_fine"],
+        65535,
+    )
+
+    # Add required parameters.
+    accumulated_data["time_seconds"] = time_seconds
+    sorted_data = accumulated_data.sortby("time_seconds", ascending=True)
+    pkt_counter = get_pkt_counter(sorted_data["mag_status"])
+    sorted_data["pkt_counter"] = pkt_counter
+
+    grouped_data = find_groups(sorted_data, (0, 3), "pkt_counter", "time_seconds")
+
+    unique_groups = np.unique(grouped_data["group"])
+    mag_data = []
+
+    for group in unique_groups:
+        # Get status values for each group.
+        status_values = grouped_data["mag_status"][
+            (grouped_data["group"] == group).values
+        ]
+        pkt_counter = grouped_data["pkt_counter"][
+            (grouped_data["group"] == group).values
+        ]
+
+        if not np.array_equal(pkt_counter, np.arange(4)):
+            logger.warning(
+                f"Group {group} does not contain all values from 0 to "
+                f"3 without duplicates."
+            )
+            continue
+
+        # Get decoded status data.
+        status_data = get_status_data(status_values, pkt_counter)
+
+        # Get science values for each group.
+        science_values = grouped_data["mag_data"][
+            (grouped_data["group"] == group).values
+        ]
+        science_data = extract_magnetic_vectors(science_values)
+
+        # Get time values for each group.
+        time_data = get_time(grouped_data, group, pkt_counter)
+
+        mag_data.append({**status_data, **science_data, **time_data})
+
+    return mag_data

imap_processing/ialirt/l0/process_swe.py

@@ -0,0 +1,252 @@
+"""Functions to support I-ALiRT SWE packet parsing."""
+
+import logging
+
+import numpy as np
+import pandas as pd
+import xarray as xr
+from numpy.typing import NDArray
+
+from imap_processing.ialirt.utils.grouping import find_groups
+from imap_processing.swe.l1a.swe_science import decompressed_counts
+from imap_processing.swe.l1b.swe_l1b_science import (
+    deadtime_correction,
+    read_in_flight_cal_data,
+)
+from imap_processing.swe.utils.swe_constants import (
+    ESA_VOLTAGE_ROW_INDEX_DICT,
+    GEOMETRIC_FACTORS,
+    N_CEMS,
+)
+from imap_processing.swe.utils.swe_utils import combine_acquisition_time
+
+logger = logging.getLogger(__name__)
+
+
+def decompress_counts(raw_counts: NDArray) -> NDArray:
+    """
+    Perform decompression of raw counts using a predefined decompression table.
+
+    Parameters
+    ----------
+    raw_counts : np.ndarray
+        Array of raw compressed counts with shape (n_energy, n_cem, n_phi).
+
+    Returns
+    -------
+    counts : np.ndarray
+        Array of decompressed counts with the same shape as raw_counts.
+    """
+    decompression_table = np.array([decompressed_counts(i) for i in range(256)])
+
+    # Decompress using the precomputed table
+    counts = decompression_table[raw_counts]
+
+    return counts
+
+
+def phi_to_bin(phi_values: NDArray) -> NDArray:
+    """
+    Convert phi values to corresponding bin indices.
+
+    Parameters
+    ----------
+    phi_values : NDArray
+        Array of phi values.
+
+    Returns
+    -------
+    bin_indices : NDArray
+        Array of bin indices.
+    """
+    # Ensure it wraps correctly within 0-29 bins
+    return ((phi_values - 12) // 12) % 30
+
+
+def prepare_raw_counts(grouped: xr.Dataset, cem_number: int = N_CEMS) -> NDArray:
+    """
+    Reformat raw counts into a 3D array binned by phi.
+
+    Parameters
+    ----------
+    grouped : xr.Dataset
+        Dataset containing grouped i-ALiRT packet data for 30 seconds.
+    cem_number : int
+        Number of CEMs (default 7).
+
+    Returns
+    -------
+    raw_counts : NDArray
+        Raw counts with shape (8, 7, 30).
+
+    Notes
+    -----
+    Array of raw counts with shape (n_energy, n_cem, n_phi), where:
+        - 8 corresponds to the 8 energy steps.
+        - 7 corresponds to the 7 CEM detectors.
+        - 30 corresponds to the 30 phi bins.
+    """
+    raw_counts = np.zeros((8, cem_number, 30), dtype=np.uint8)
+
+    # Compute phi values and their corresponding bins
+    # Example: energy steps 0-1 have the same phi;
+    # energy steps 2-3 have the same phi, etc.
+    # A depiction of this is shown in Figure 7 of the SWE Algorithm Document.
+    phi_values = np.array(
+        [
+            (12 + 24 * grouped["swe_seq"].values) % 360,  # Energy steps 0 and 1
+            (24 + 24 * grouped["swe_seq"].values) % 360,  # Energy steps 2 and 3
+        ]
+    )
+    phi_bins = phi_to_bin(phi_values).astype(int)  # Get phi bin indices
+
+    # Energy bin lookup table (indexed by quarter cycle)
+    energy_bins = np.array(
+        [
+            [1, 5, 7, 3],  # 0-14 (first quarter cycle)
+            [2, 6, 4, 0],  # 15-29 (second quarter cycle)
+            [3, 7, 5, 1],  # 30-44 (third quarter cycle)
+            [0, 4, 6, 2],  # 45-59 (fourth quarter cycle)
+        ]
+    )
+
+    # The first 15 seconds is the first quarter cycle, etc.
+    quarter_cycles = np.floor(grouped["swe_seq"] / 15).astype(int)
+    e_bins = energy_bins[quarter_cycles]
+
+    # Populate raw_counts
+    for cem in range(1, cem_number + 1):  # 7 CEMs
+        e1 = grouped[f"swe_cem{cem}_e1"].values
+        e2 = grouped[f"swe_cem{cem}_e2"].values
+        e3 = grouped[f"swe_cem{cem}_e3"].values
+        e4 = grouped[f"swe_cem{cem}_e4"].values
+
+        # Phi bins 0, 2...(12, 36, ...)
+        raw_counts[e_bins[:, 0], cem - 1, phi_bins[0]] = e1
+        raw_counts[e_bins[:, 1], cem - 1, phi_bins[0]] = e2
+        # Phi bins 1, 3...(24, 48, ...)
+        raw_counts[e_bins[:, 2], cem - 1, phi_bins[1]] = e3
+        raw_counts[e_bins[:, 3], cem - 1, phi_bins[1]] = e4
+
+    return raw_counts
+
+
+def get_ialirt_energies() -> list:
+    """
+    Get the ESA voltages for I-ALiRT.
+
+    Returns
+    -------
+    energy : list
+        List of ESA voltage for I-ALiRT.
+
+    Notes
+    -----
+    This is a subset of the ESA_VOLTAGE_ROW_INDEX_DICT.
+    """
+    energy = [k for k, v in ESA_VOLTAGE_ROW_INDEX_DICT.items() if 11 <= v <= 18]
+
+    return energy
+
+
+def normalize_counts(counts: NDArray, latest_cal: pd.Series) -> NDArray:
+    """
+    Normalize the counts using the latest calibration factor.
+
+    Parameters
+    ----------
+    counts : np.ndarray
+        Array of counts.
+    latest_cal : pd.Series
+        Array of latest calibration factors.
+
+    Returns
+    -------
+    norm_counts : np.ndarray
+        Array of normalized counts.
+    """
+    latest_cal = latest_cal.to_numpy()
+
+    # Norm counts where counts are non-negative
+    # TODO: confirm fv is counts with Ruth
+    norm_counts = counts * (latest_cal / GEOMETRIC_FACTORS)[:, np.newaxis]
+    norm_counts[norm_counts < 0] = 0
+
+    return norm_counts
+
+
+def process_swe(accumulated_data: xr.Dataset) -> list[dict]:
+    """
+    Create L1 data dictionary..
+
+    Parameters
+    ----------
+    accumulated_data : xr.Dataset
+        Packets dataset accumulated over 1 min.
+
+    Returns
+    -------
+    swe_data : list[dict]
+        Dictionaries of the parsed data product.
+    """
+    logger.info("Processing SWE.")
+
+    # Calculate time in seconds
+    time_seconds = combine_acquisition_time(
+        accumulated_data["swe_acq_sec"], accumulated_data["swe_acq_sub"]
+    )
+    accumulated_data["time_seconds"] = time_seconds
+
+    # Get total full cycle data available for processing.
+    # There are 60 packets in a set so (0, 59) is the range.
+    grouped_data = find_groups(accumulated_data, (0, 59), "swe_seq", "time_seconds")
+    unique_groups = np.unique(grouped_data["group"])
+    swe_data: list[dict] = []
+
+    for group in unique_groups:
+        # Sequence values for the group should be 0-59 with no duplicates.
+        seq_values = grouped_data["swe_seq"][(grouped_data["group"] == group).values]
+
+        # Ensure no duplicates and all values from 0 to 59 are present
+        if not np.array_equal(seq_values, np.arange(60)):
+            logger.warning(
+                f"Group {group} does not contain all values from 0 to "
+                f"59 without duplicates."
+            )
+            continue
+        # Prepare raw counts array just for this group
+        # (8 energy steps, 7 CEMs, 30 phi bins)
+        group_mask = grouped_data["group"] == group
+        grouped = grouped_data.sel(epoch=group_mask)
+
+        # Split into Q1 & Q2 (swe_seq 0-29) and Q3 & Q4 (swe_seq 30-59)
+        first_half = grouped.where(grouped["swe_seq"] < 30, drop=True)
+        second_half = grouped.where(grouped["swe_seq"] >= 30, drop=True)
+
+        # Prepare raw counts separately for both halves
+        raw_counts_first_half = prepare_raw_counts(first_half)
+        raw_counts_second_half = prepare_raw_counts(second_half)
+
+        # Decompress the raw counts
+        counts_first_half = decompress_counts(raw_counts_first_half)
+        counts_second_half = decompress_counts(raw_counts_second_half)
+
+        # Apply the deadtime correction
+        # acq_duration = 80 milliseconds
+        corrected_first_half = deadtime_correction(counts_first_half, 80 * 10**3)
+        corrected_second_half = deadtime_correction(counts_second_half, 80 * 10**3)
+
+        # Grab the latest calibration factor
+        in_flight_cal_df = read_in_flight_cal_data()
+        latest_cal = in_flight_cal_df.sort_values("met_time").iloc[-1][1::]
+
+        normalized_first_half = normalize_counts(corrected_first_half, latest_cal)
+        normalized_second_half = normalize_counts(corrected_second_half, latest_cal)
+
+        # Sum over the 7 detectors
+        summed_first_half = np.sum(normalized_first_half, axis=1)  # noqa: F841
+        summed_second_half = np.sum(normalized_second_half, axis=1)  # noqa: F841
+
+        # TODO: will continue here
+
+    return swe_data

imap_processing/ialirt/packet_definitions/ialirt.xml

@@ -428,8 +428,11 @@
 			</xtce:Parameter>
 			<!-- SWE -->
 			<!-- MAG -->
-			<xtce:Parameter name="MAG_ACQ" parameterTypeRef="uint48">
-				<xtce:LongDescription>MAG Acquisition Time</xtce:LongDescription>
+			<xtce:Parameter name="MAG_ACQ_TM_COARSE" parameterTypeRef="uint32">
+				<xtce:LongDescription>MAG Coarse Acquisition Time</xtce:LongDescription>
+			</xtce:Parameter>
+			<xtce:Parameter name="MAG_ACQ_TM_FINE" parameterTypeRef="uint16">
+				<xtce:LongDescription>MAG Fine Acquisition Time</xtce:LongDescription>
 			</xtce:Parameter>
 			<xtce:Parameter name="MAG_STATUS" parameterTypeRef="uint24">
 				<xtce:LongDescription>MAG Status</xtce:LongDescription>
@@ -674,7 +677,8 @@
 					<xtce:ParameterRefEntry parameterRef="SC_SPARE_3"/>
 					<!-- Spacecraft -->
 					<!-- MAG -->
-					<xtce:ParameterRefEntry parameterRef="MAG_ACQ"/>
+					<xtce:ParameterRefEntry parameterRef="MAG_ACQ_TM_COARSE"/>
+					<xtce:ParameterRefEntry parameterRef="MAG_ACQ_TM_FINE"/>
 					<xtce:ParameterRefEntry parameterRef="MAG_STATUS"/>
 					<xtce:ParameterRefEntry parameterRef="MAG_DATA"/>
 					<!-- MAG -->