Proposal: Encounter-based Mascon Perturbation Module for LLO Analysis: Scope-check before opening an issue

[KayAerospace]

Hi Christopher,

I've read CONTRIBUTING.md and the quality guidelines, and I want to scope-check with you here before opening a formal issue and assigning myself. Wanted to make sure the capability is one Nyx would want before committing to the process.

The work: I've developed and validated an encounter-based framework that decomposes lunar mascon perturbations on Low Lunar Orbits into discrete gravitational encounters, maps per-encounter eccentricity-vector increments via Gauss variation of parameters, and quantifies natural cancellation between successive encounters along the trajectory. It's built on GRAIL GRGM900C and validated against full spherical-harmonic truth propagation. The underlying application is mascon surfing, a station-keeping strategy that acts only on non-cancelling encounters rather than treating the mascon field as a diffuse background.

Preprint: https://doi.org/10.5281/zenodo.21740514
Reference implementation (Jupyter notebooks, CC0): https://github.com/KayAerospace/Per-Encounter-Quantification-of-Mascon-Effects-on-LLO-Altitude-Drift

Why Nyx?
Nyx already handles high-fidelity gravity via spherical harmonics; the encounter-decomposition layer sits on top of that, using existing propagation and gravity infrastructure rather than replacing it. Given Nyx's flight heritage on Blue Ghost and its focus on lunar and cislunar mission design, I think this capability lands in-scope, though you're the right person to judge.

What I'd like your view on before I open the issue.

1. Does encounter-based perturbation decomposition fit Nyx's roadmap, or is it further from the library's current direction than I'm reading?
2. If it fits, would the natural entry point be the Rust core, or the Python bindings? My reference implementation is in Python/Jupyter, so a Rust port would be a substantial translation task. I want to be honest about that rather than promise a drop-in.
3. On validation: CONTRIBUTING.md asks for a GMAT script alongside the Rust test case for dynamics changes. I'm comfortable building that, just flagging that I'd plan for it in the timeline.

Happy to iterate on scope, and grateful for any steer, including if the answer is "not the right fit for Nyx." Not looking to force a contribution that doesn't belong here.

Best,
Ambrose Osadugba
GitHub: @KayAerospace

[ChristopherRabotin]

Hi Ambrose,

Thank you for reaching out. I read parts of your preprint: your approach is frankly remarkable. Your approach is novel compared to the methods we used on the missions I've worked on.

Nyx focuses entirely on providing the tools for engineers and researchers to solve hard astrodynamic problems without worrying about the intricacies of force model implementations. While I've only recently revived the Python bindings, I think your work would fit best as a Python example of the kinds of hard problems Nyx can help solve. It would also show whether the Python bindings for mission design are currently sufficient to solve these: not everything available in Rust is currently exported to Python, but I'm working on it. To highlight your work for people browsing the repo, you might want to create a new top-level folder called examples and then a subfolder there with your code, and a readme that links to your preprint.

I'd be glad to support your work where I can. I'm currently on a rush to export a lot of functionality in Nyx to Python, but I can make some time for direct support on Github.

Thanks again for considering Nyx, I look forward to seeing how it plays out.
Best,
Chris

[KayAerospace]

Hi Chris,

Thank you. That's genuinely encouraging to hear, and the examples-folder framing is one I hadn't considered but it fits well. Happy to shape the contribution that way.

Concretely, I'm proposing to:

1. Fork nyx-space/nyx, add examples/mascon-encounter-analysis/ at the top level, and populate it with a Python-bindings port of the analysis pipeline; orbit propagation via Nyx, encounter detection and per-encounter eccentricity-vector accounting layered on top.
2. Include a README in that subfolder explaining the technique, linking to the preprint and to the original Jupyter reference implementation, so anyone browsing can trace the mapping between the paper and the code.
3. As I port, keep notes on Nyx APIs I need but that aren't yet exposed in Python. I'll be happy to feed those back as a separate list so you have concrete signal for what to prioritise when you're exporting more of the Rust surface. If it's useful, I can raise these as individual issues; if you'd prefer a single running list somewhere, tell me where.

A couple of practical questions before I start:

1. Any preference on Python version target, or should I follow whatever the current bindings support?
2. For the README, is there an existing example structure in the repo I should mirror for consistency, or is this the first examples/ entry?

I'll aim to open a draft PR once the first pass is working end-to-end, targeting roughly three weeks from now. No rush from your side; I know you're deep in the Python export work. I'll keep the PR self-contained so it doesn't block on anything you're doing in parallel.

Thanks again for the read and the steer.

Best,
Ambrose.

[ChristopherRabotin]

Hi Ambrose,

All of these points look good to me! This will be the first examples directory in the nyx_space repo itself! I'll let you organize that as you see fit, I'm sure it'll be just fine given that your other repo is pretty clean and clear.

When you encounter a functionality that is either poorly documented (very likely) or not exposed (also likely but less so), the best place is probably to ask me here in the discussion comments directly. Nyx supports Python 3.11 and up, so the choice is yours, it should execute all the same no matter the version.

A single self-contained PR is perfect as well.

Thanks again !

[KayAerospace]

Hi Chris,

Perfect. Thank you for the quick confirmation on all points. Great to know this will be the first examples directory in the repo; I'll make sure it sets a good standard.

I'll go with Python 3.11. I'm starting with the environment setup this week and will work through the notebooks in order. I'll come back to the discussion thread as soon as I hit any API gaps or documentation questions. Aiming to have a draft PR ready in roughly 3 weeks.

Thanks again for the support.

Best,
Ambrose.

[KayAerospace]

Hi Chris,

Quick update: Nyx is set up locally, the Python bindings build cleanly, and I've completed a mapping pass across all 11 notebooks of the analysis pipeline onto Nyx's Python API. The good news is that essentially everything I need is already exposed; the port will be mostly mechanical translation rather than new capability. Thank you for reviving the bindings when you did; the timing worked out well.

Two things I couldn't resolve from the docstrings alone. Both are precise enough that they should each take one or two lines to answer:

Q1. Frame convention for Propagator.accel_km_s2.
The docstring reads "instantaneous equations of motion." Is the returned acceleration expressed in the spacecraft's inertial state frame (e.g., Moon J2000 for a lunar orbiter), in the central body's body-fixed frame, or in whatever frame the Dynamics object was configured with? My use case is projecting the acceleration into the orbital RTN frame at each sample along a nominal Keplerian reference, so knowing the source frame precisely determines whether I rotate first or project directly.

Q2. Obtaining a FrameUid for the Moon Principal Axis frame in Python.
GravityFieldConfig takes a frame: FrameUid argument. nyx_space.anise.constants.Frames exposes MOON_J2000, but I don't see a MOON_PA (or MOON_PA_DE440) equivalent under the same namespace. GRGM900C is defined in the Moon PA frame, so I need
a FrameUid that resolves to the PA frame Nyx already loads from moon_pa_de440_200625.bpc. What's the intended way to construct it?

Everything else I can either discover from help() or figure out at implementation time. I'll keep a running list of anything that surfaces during
the porting itself and batch it into a follow-up here rather than one-off pings.

Thanks again for the steer on the examples-folder approach. It's shaping up well.

Best,
Ambrose.

[ChristopherRabotin]

Hi Ambrose,

I apologize for my late answer.

To answer your first question, the accel_km_s2 function evaluates the accelerations in the state's frame. If the state is defined in Earth J2000 for example, then it'll be the accelerations in the Earth center J2000 frame. To rotate this acceleration in the RTN frame (which is defined exactly like the RIC frame), you can call dcm3x3_from_rcn_to_inertial on the Orbit class to compute the DCM that rotates from RCN to the inertial frame. The overall code will look something like the following:

import numpy as np 

my_orbit = Orbit(x_km, y_km, ..., epoch, earth_j2000)
my_spacecraft = Spacecraft(my_orbit)
accel_km_s2_in_j2000 = my_previously_defined_dynamics.accel_km_s2(my_spacecraft)
dcm_rcn_to_inertial = my_orbit.dcm3x3_from_rcn_to_inertial()
accel_km_s2_rcn = np.dot(dcm_rcn_to_inertial.T, my_orbit.cartesian_pos_vel())

As for question 2, yes, sorry, that's a bit of a confusing set up. ANISE offers both a Frame and a FrameUid. The Frame class stores the IDs of the center object and the orientation (e.g. Earth J2000 has a center ID of 399 and an orientation of 0), but also the gravitational parameter, the central object shape. This allows computing orbital elements without fetching the information from the Almanac again. On the other hand, FrameUid only contains the IDs of the center and orientation, so it can only be used as a simple storage of this data.

I hope this helps. Jumping to your next answer now, sorry for the delay.

Best,
Chris.

[KayAerospace]

Hi Chris,

Quick follow-up: I was able to resolve both questions empirically before starting the port.

Q2: Frames.MOON_PA_DE440_FRAME gives a Frame; .to_frameuid() returns the FrameUid that GravityFieldConfig accepts. Working cleanly.

Q1: Verified via direct comparison at a known point that Propagator.accel_km_s2 returns the acceleration in the spacecraft's inertial state frame (Moon J2000 in my case). Residual against -μr/r³ in J2000 was 2.2e-7 km/s², right in the range my paper reports for the disturbing acceleration at 50 km altitude in Section 6.1, while the equivalent comparison in the body-fixed PA frame was ~10⁴× larger. Unambiguous.

Also learned that Nyx doesn't expose DOP853. I'll use DormandPrince78 and note the substitution in the example README (numerically equivalent at the tolerances involved). No blocker.

Starting the port itself now. Will surface any further questions in a batched follow-up rather than one-off pings.

Thanks,
Ambrose

[ChristopherRabotin]

Hi Ambrose,

Glad to hear your figured it out! That small difference in the acceleration might be due to a difference in the gravitational parameters. By default, Nyx uses the data defined by NASA NAIF, which I know to be slightly different than the numbers in GMAT for example.

The DormandPrince78 integrator is really great: it's much faster than the RungeKutta89, and achieves very similar results. Nyx defaults the RungeKutta89 only because it's the industry default for reasons I don't know (probably historical).

Let me know if you have further questions, and I'll try to answer more promptly.

Best,
Chris

[KayAerospace]

Hi Chris,

No apology needed. Thank you for the thorough answers. Both align with what I found empirically before starting the port, and your notes clarified two things I'd been unsure about:

• The equivalence of your RCN and my RTN convention. My port kept a manual (r̂, t̂, n̂) construction from (r, v) partly because I was cautious about column ordering; good to know dcm3x3_from_rcn_to_inertial() returns the same frame under a different name. I'll note the equivalence in the example's design-decisions section.
• The DormandPrince78 recommendation is helpful context. The port uses DP78 (as the closest analog to my paper's DOP853), and your note that it's faster than RK89 with similar results confirms it's a good default for this kind of work. I've mentioned the substitution in the README already.

I've opened a draft PR (#598) with the full example. No rush on review, I know you're deep in other work, and I'll be responsive to whatever you flag whenever you get to it.

Best,
Ambrose.

[KayAerospace]

Hi Chris,

Just leaving a reminder here concerning the PR (#598). I surely understand your quite busy schedule, so no rushes certainly.
I'll be responsive to whatever you point out whenever you get to it.

Best,
Ambrose.