[Feature]: Support for lunar, Martian, and potentially interplanetary numerical orbit propagation

[Mtrya]

Pre-submission Checklist

• I have searched existing issues to ensure this feature hasn't already been requested
• I have checked the documentation to confirm this feature doesn't already exist

Description

I would like to see support for numerical orbit propagation around celestial bodies other than Earth, specifically:

1. Lunar orbit propagation
2. Martian orbit propagation
3. Interplanetary trajectory propagation
   The feature should support the following force models: gravity (point mass, spherical harmonic; third body perturbation); solar radiation pressure and atmospheric drag.

Use Case

How I Would Use It

1. Lunar orbit propagation: Propagate a spacecraft in low lunar orbit (LLO) with GRAIL-derived gravity (e.g., GRGM1200A), Earth and Sun as third-body perturbers, and SRP.

2. Mars orbit propagation: Propagate a Mars reconnaissance orbiter with GMM-3 gravity, Sun perturbations, SRP, and simplified Mars atmospheric drag.

3. Interplanetary cruise: Propagate a heliocentric trajectory with Sun as the central body and planetary perturbations, then switch central bodies at sphere-of-influence crossings.

Example API Usage (Conceptual)

import brahe as bh

# Lunar orbit example
lunar_config = bh.ForceModelConfig.for_body(
    central_body=bh.CentralBody.Moon,
    gravity=bh.GravityConfiguration.SphericalHarmonic(
        model=bh.GravityModelType.GRGM1200A,  # or GRAIL gravity
        degree=50,
        order=50,
    ),
    third_body=bh.ThirdBodyConfiguration(
        bodies=[bh.ThirdBody.Earth, bh.ThirdBody.Sun],
        ephemeris_source=bh.EphemerisSource.DE440s,
    ),
    srp=bh.SolarRadiationPressureConfiguration(
        eclipse_model=bh.EclipseModel.Conical,  # Moon as occulting body
        ...
    ),
    drag=None,  # Negligible lunar atmosphere
)

prop = bh.DNumericalOrbitPropagator.new(
    epoch=epoch,
    state=lunar_state_mci,  # Moon-Centered Inertial
    force_config=lunar_config,
    ...
)

Proposed Solution

1. Introduce a CentralBody Abstraction, add a new enum (or struct) to encapsulate body-specific physical constants and frame definitions:
2. Extend ForceModelConfig with Central Body
3. Modify compute_dynamics() to Use Central Body
4. Generalize Body-Specific Components
5. Add Lunar and Martian Gravity Models
6. Add Body-Specific Reference Frames

Impact on Existing API

Minor changes to existing functions

Impact Details

Backward Compatibility

This feature can be implemented in a fully backward-compatible manner:

Scenario	Impact
Existing ForceModelConfig::default()	✅ No change needed — defaults to CentralBody::Earth
Existing ForceModelConfig::earth_gravity()	✅ No change needed
Existing ForceModelConfig::leo_default()	✅ No change needed
Existing ForceModelConfig::geo_default()	✅ No change needed
Existing DNumericalOrbitPropagator::new()	✅ No signature change

New API Additions (Non-Breaking)

New Item	Description
CentralBody enum	New type for body selection
ForceModelConfig.central_body field	New field with default CentralBody::Earth
ForceModelConfig::for_body()	New constructor
ForceModelConfig::lunar_default()	New convenience constructor
ForceModelConfig::mars_default()	New convenience constructor
accel_relativity(state, gm)	Add gm parameter (or deprecate old signature)
GravityModelType::GRGM1200A, etc.	New gravity model variants

Functions Requiring Internal Modification

These functions use hardcoded Earth constants and would need updates to read from CentralBody:

File	Function/Location	Change Required
dnumerical_orbit_propagator.rs:915	compute_dynamics() point-mass	Use central_body.gm()
dnumerical_orbit_propagator.rs:985	Exponential atmosphere altitude	Use central_body.radius()
relativity.rs:48-49	accel_relativity()	Add gm parameter
solar_radiation_pressure.rs	Eclipse functions	Use central_body.radius()
frames/*.rs	Frame transformations	Add body-specific rotation rates

Python Bindings

The Python bindings (via PyO3) would need updates to expose:

• CentralBody enum
• New ForceModelConfig constructors
• New gravity model types

Contribution

• I can provide test data or validation cases
• I am willing to contribute to the implementation
• I can provide reference material (papers, algorithms, existing implementations)

[duncaneddy]

Hi there!

Thanks for your raising this feature request, detailed planning, and willingness to help with the implementation! Adding lunar and martian propagation is something I've wanted to add for a while, but haven't had the time.

I like the approach and agree with it, but I have some thoughts to share before proceeding:

1. I think it will be a large total body of change, so I'd like to do it in multiple smaller PRs to make them each manageable to review and test. I'd recommend in breaking it up into:
2. Moon reference frame transformations added in src/frames/lunar.rs (and python bindings)
3. Mars reference frame transformations added in src/frames/mars.rs (and python bindings)
4. Add lunar and mars gravity models (potentially adding, list/download methods if needed)
5. Introduce CentralBody abstraction, modify ForceModelConfig, and modify compute_dynamics()` to support the moon.
6. Introduce CentralBody abstraction, modify ForceModelConfig, and modify compute_dynamics()` to support Mars. (
7. There is a 10MB size limit on the total crate size. Right now we include two Earth-gravity models for ease of use, but they take up room. I'm not sure the package can handle also including (in the package distribution directly) lunar and martian gravity models. This might necessitate implementing a download_gravity_model (and ideally list_earth_gravity_models() / list_lunar_gravity_models()
8. For short hand frame references, I'd prefer to use lci for Lunar-Centered Inertial and mci for Mars-Centered Inertial. This allows us to extend to other planetary bodies following common conventions and avoid the ambiguity of is m for Mars or Moon.
9. It would be a nice-to-have to also add an additional Central-Body for the Earth-Moon barycenter (EMB) to enable cis-lunar computation. This should be relatively easy to add since Anise which provides the third-body DE ephemerides also supports the calculation of the EMB position.
10. As part of the new reference frame transformations, we should not just implement state_lci_to_lclf and state_lclf_to_lci (lunar) and state_mci_to_mcmf and state_mcmf_to_mci (Mars), but also state_eci_to_lci, state_lci_to_eci state_eci_to_mci, state_mci_to_eci to support translation between these frames.
11. I like bh.ForceModelConfig.for_body to enable the change to be non-breaking as well as keep the default as the "most common" option of performing LEO propagation.
12. Because a NumericalOrrbitPropagator is a DOrbitStatePropagator it must implement functions like state_eci, these should be updated to handle different central bodies to return the state in the correct frame even if the central body is different, so that 1) the package doesn't have functionality that is partially supported or throws errors in odd configurations, 2) so people can actually access these conversions easily which would be helpful in Earth-based tracking / comms applications
13. From colleagues I was recommended Astrodynamics Convention and Modeling Reference for Lunar, Cislunar, and Libration Point Orbits as the best resource for lunar reference frame transformations, so that can serve as a reference for that.
14. I can dig up a good reference for the Mars frame transformations.
15. It would be a nice-to-have to add Phobos/Deimos third-body ephemerides for Mars propagation as well as a Mars atmospheric model (I wouldn't require it for this PR, just writing it down for planning).

If that plan sounds good to you, I think we can start proceeding. I'm traveling currently so my availability to help and review PRs will be a little limited for the next couple weeks, but I'll do my best to respond if you are able to post any PRs.

[Mtrya]

Hi Duncan,

Thank you so much for the detailed guidance and roadmap! This is incredibly helpful.

I fully agree that breaking this into multiple smaller PRs is the right approach—it will make each change more manageable to review and test. The recommended order (lunar frames → Mars frames → gravity models → Moon propagation → Mars propagation) makes sense for incremental validation. Thanks for the reference on lunar frame transformations; I'll use that as my primary resource for the lunar frame implementations.

Gravity Model Distribution

Given the 10MB crate size limit (and the current gravity models already taking ~8MB), I lean toward the auto-download with caching approach, similar to how PyTorch/HuggingFace handle large model files:

• On first use of a gravity model (e.g., GravityModelType::GRGM1200A), automatically download from a source and cache to ~/.cache/brahe/gravity_models/
• Provide explicit functions like download_gravity_model(), list_lunar_gravity_models(), list_mars_gravity_models() for users who want to pre-download or inspect available options
• The existing GravityModel::from_file() already supports loading from arbitrary paths, so advanced users can still provide their own models

This keeps the crate lightweight while providing a seamless experience for most users. Happy to hear if you prefer a different approach.

Noted

The lci (Lunar-Centered Inertial) / mci (Mars-Centered Inertial) convention makes sense for avoiding Moon/Mars ambiguity and extensibility to other bodies. I'll follow that pattern in the frame implementations.

I'll keep these in mind but won't block the initial PRs on them:

• EMB (Earth-Moon Barycenter) as a central body for cis-lunar computation
• Phobos/Deimos third-body ephemerides for Mars propagation
• Mars atmospheric model

Proceeding

This plan sounds great. I'll start with the lunar reference frame transformations in src/frames/lunar.rs as the first PR. I'll take a steady pace, and reach out if I run into design questions along the way.

Safe travels, and thank you again for the guidance!

[ChristopherRabotin]

While I can't be of much help on the brahe implementation side since I don't know the framework enough, if you want an auto-downloading system, you could leverage the MetaFile from the ANISE dependency -- example usage in a rust file here. Without changes though, it will download the data in the ~/.local/share/nyx-space/anise folder though, but I'm of course open to a PR to customize that folder. I'm also happy to help in the validation of the implementation in brahe if that would be helpful.

[Mtrya]

Hi Christopher,

Thank you for the MetaFile suggestion and the validation offer!

For the download system, we'll likely stick with the current implementation for now. But I'll leave the decision on migrating to MetaFile to Duncan's discretion as the maintainer.

Regarding validation, that would be fantastic! We're still early in the implementation, working through frame conversions now, with gravity fields and numerical propagation to follow. I'll definitely reach out once we have something concrete worth validating.

Thanks again for the support and for building ANISE!