SWAPI: add L3A alpha and proton velocity vectors in GSE, GSM, and HAE-J2000 coordinates

[leowerneck]

Change Summary

Closes #21

Overview

Add SWAPI L3A proton and alpha velocity vectors, covariance matrices, and uncertainties in GSE, GSM, and HAE-J2000 coordinates.

File changes

• Add generic RTN vector and covariance transformations using SPICE frames.
• Generate all target-frame products for proton and alpha processing.
• Add the corresponding CDF models, metadata, labels, and documentation.
• Extend existing tests and add one focused transformation test.

Testing

• 32 affected unit tests pass.
• SPICE-backed integration tests were not run because usable Git LFS kernel files are unavailable locally.

[leowerneck]

@jtniehof @hafarooki — Could you please review if this is the intended approach? I followed @hafarooki's suggestion and rotated the alpha and proton velocity vectors from the RTN frame. For now, I focused on adding these only to SWAPI.

[hafarooki]

Looks good. Some minor things: a comment would help in the code for the einsum. And the test cases should perhaps flip around signs and axes instead of added 300 to all components…

[hafarooki]

@jtniehof requested for review of metadata aspects

[leowerneck]

Looks good. Some minor things: a comment would help in the code for the einsum. And the test cases should perhaps flip around signs and axes instead of added 300 to all components…

@hafarooki That's a good point. I updated the tests to add rotations.

[Copilot]

Pull request overview

Adds SWAPI L3A proton and alpha velocity products in GSE, GSM, and HAE-J2000 coordinates.

Changes:

• Adds SPICE-based vector and covariance transformations.
• Extends CDF models, metadata, labels, and documentation.
• Updates processor and model tests for new products.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
imap_l3_processing/swapi/swapi_processor.py	Generates target-frame products.
imap_l3_processing/swapi/l3a/utils.py	Implements coordinate transformations.
imap_l3_processing/swapi/l3a/models.py	Exposes new CDF variables and labels.
imap_l3_processing/cdf/config/imap_swapi_l3a_variable_attrs.yaml	Defines variable metadata.
docs/swapi/proton-sw.md	Documents proton outputs.
docs/swapi/alpha-sw.md	Documents alpha outputs.
tests/test_utils.py	Updates model fixtures.
tests/swapi/test_swapi_processor.py	Tests processor integration.
tests/swapi/l3a/test_utils.py	Tests transformation mathematics.
tests/swapi/l3a/test_models.py	Tests new model variables.
tests/swapi/l3a/test_chunk_fits.py	Isolates target-frame processing in existing tests.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

imap_l3_processing/swapi/swapi_processor.py:68

• Each call computes TT-to-ET and the same RTN-to-target rotation matrix, and this function repeats that work for the Sun-relative vector and covariance at every epoch and frame. That causes three SPICE frame lookups per output frame per record. Compute the rotation once per epoch/frame (or batch a frame and fall back per epoch only on a SPICE coverage error), then apply it to both vectors and the covariance.

    velocity = convert_velocity_rtn_to_frame(
        epoch_slice,
        result[f"{prefix}_rtn"][index : index + 1],
        target_frame,
    )[0]

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (1)

imap_l3_processing/swapi/swapi_processor.py:65

• Each epoch/frame computes the same timestamp conversion and SPICE rotation three times: once for each velocity and once for the covariance. At the one-minute product cadence, this adds 9 SPICE rotations per record (12,960 per day/product) although only 3 unique rotations are needed. Compute one rotation matrix per epoch/frame and apply it to both vectors and the covariance, or pass that matrix into the conversion helpers.

    velocity = convert_velocity_rtn_to_frame(