CoDICE Lo 3D distribution: update to new algorithms (Phase D deferred)

[jtniehof]

Summary

The 3d distribution algorithms have changed. The new algorithm is described in the latest algorithm document from January 2026, R3C0 (page 60, "3D VDF"). The version on galaxy is up to date even though the document headers say R2C0 and the title page says Oct 2025.

This is ready to estimate but not yet implement.

Requirements

Follow the algorithm document; the first comment on this issue has some clarifications and notes from discussion of the document.

Three possible approaches:

1. Implement the entire algorithm from scratch as described in the algorithm document.
2. After step 3 in the algorithm document, in theory each species' data array is very similar to the sectored rates array as used in level 2. So it may be possible to call the L2 code at this point.
3. It may make more sense to split the difference and reimplement most of the algorithm, but use the level 2 code to do the geometric factor lookup for the RGFO. This allows us to benefit from any L2 improvements to the lookup (as does option 2).

This should be estimated assuming option 3, but the estimate should include some time for evaluating the feasibility of options 2 and 3. Okay to re-estimate after that assessment (e.g. hopefully reduce estimate if 2 works, or increase it if we have to go to 1).

Once this is completed, the l1a priorities are no longer needed as an input, because the new variables from #54 contain that information.

Related tickets

#54

[jtniehof]

3D VDF algo R3C0 pg 60. Fairly new algorithm.

We can simplify our dependencies and not have the l1a priorities as input to the 3D VDF, since we have the normalization_per_event.

1. Use lo-mass-species-bin-lookup (JTN will upload new version)
2. Remember positions are reported 1-24 but indexed 0-23. In a, use energy_step not energy_per_charge. c is just where to put the result from b.
3. At this point, this is essentially equivalent to the level 2 angular product (not the species). For following steps, could potentially take the code from level 2 to apply the RGFO algorithm, which is fairly involved.
4. t_acquire is the acquisition_time_per_esa_step appropriately indexed for epoch and esa step, and it is in seconds.
5. G calculation is fairly involved. Even if don't use L2 code for all the intensity, can potentially use the L2 code for the G lookup. E/q is actual energy_per_charge. For 3D VDF, always use sw in efficiency lookup (sw and nsw are the same).
6. These are all IDL-style indexing (last index is inclusive), not Python. The SW/NSW does not affect the 3D VDF, because we have already combined into the full direct events. Again, positions are 1-base, but indexed 0-23 in our arrays. l are ESA step indexing. A is esa steps acquired during even half-spins, see half_spin_per_esa_step (mod 2, if 0 that's A, if 1 it's B). So lA is iterate over all ESA steps where half_spin_per_esa_step is even.

Physical spin angle gives us the bin center of the 7.5 degree wide bins.

Elevation angle, position 1 is 0-7.5 (center is 3.75); position 2/24 is 7.5-22.5 (center 15), etc. i.e. position 1 and 13 are half-width.

In RGFO "current", if half_spin < RGFO_half_spin, use full.

Because rgfo_half_spin, etc. are populated in the new L1a even before the FSW change, should be able to calculate this for whole mission.