Proposal to Extend JPLEphemeridesLoader to Support Libration Data

xzguo · December 3, 2025, 8:36am

The org.orekit.bodies.JPLEphemeridesLoader provides methods to load ephemerides of major planets and is available in the default data context, offering a convenient option for Orekit users. However, JPLEphemeridesLoader currently ignores the libration data records in the JPL DE ephemeris series. Given that the loader already supports reading, retrieving, and interpolating planetary ephemerides, extending it to also support libration data should be feasible.

While libration can be loaded from a separate bpc file, and I have noted the excellent MR issue-1681 from @Rafa which adds support for general PCK/SPK operations, I believe adding a dedicated method such as loadLibration in JPLEphemeridesLoader would be a good alternative. It would provide full support for the JPL DE ephemeris files within the same loader, ensuring a more integrated and user-friendly experience.

luc · December 3, 2025, 8:44am

I agree with you.
Note there is also the old issue 778 about IAU working group on pole.
Could you open a new issue, and perhaps mention issue 778 too?

xzguo · December 4, 2025, 4:27am

i just tried to login gitlab.orekit.org with my github account, but received a message of “Your account is pending approval …”. So, i will open a new issue when i get the approval, then perhaps a simple patch to JPLEphemeridesLoader.

issue 778 seems required a update of PredefinedIAUPoles.java according to WGCCRE 2015 and its Correction. Right? That would be a tricky task and a lot of changes.

BTW, is there further update version of WGCCRE report after 2015?

sdinot · December 4, 2025, 7:53am

@xzguo, in the meantime, an administrator has validated your account on GitLab. You can log in now.

xzguo · December 4, 2025, 8:47am

thank you, @sdinot, i just post my issue.

xzguo · December 8, 2025, 7:01am

hi, @luc ,
i am trying to modify JPLEphemeridesLoader.java to directly expose a method like loadLibration. Here are my confusions, maybe you and other developers can give valuable advises on the coding convention,

there is public CelestialBody loadCelestialBody(final String name) method in JPLEphemeridesLoader.java for the planets right now. A new loadLibration method is quite self-explained, so the paramter name seems redundant, and could be omitted, that result a method signature like loadLibration().
JPL DE ephemeris can provide the libration by phi, theta, psi and their rate. While theloadCelestialBody method return a JPLCelestialBody object, how about a new JPLLibration class to wrap the result from loadLibration(), i.e., ‘public JPLLibration loadLibration()’?
Can my planed modification be a patch? So, i branches from release 13.1.2 other than thedevelop .

luc · December 8, 2025, 7:23am

A new JPLLibrationobject would be fine for direct use, but I think it should also directly be used within the Celestial body when building its body frame, that would contain both the regular rotation and the librario too. What do you think?

I am not sure about a patch release. Indeed, we are working on a 14.0 release, so the develop branch is already quite evolved, it would be better to start from there rather than to start from an older branch and postpone the merging later on. Doing this wor right from the beginning would be less work overall.

xzguo · December 8, 2025, 8:20am

thanks, @luc

i am not sure about what you mean the regular rotation of the moon.

Actually in the JPL DE ephemeris(at least DE430 and DE440), there is only a lunar centered version of GCRF, maybe named LCRF, which is just a translation involved to move the origin from earth centered to lunar centered. Then, the libration is directly applied to rotate the LCRF to moon body-fixed frame, which is specifically defined as Moon principal axis ¶ frame. So, there is no more appropriate IAUPole existed to define lunar self rotation. A JPLLibration seems enough.

there is a relevant discussion on Propagation of GRAIL-A on the lunar frames.

Moreover, the getBodyOrientedFrame in JPLCelestialBody.java is based on WGCCRE report, and the returned body-fixed frame is more suitable for cartographic usage. if we continue what is the orekit’s choice now, another version of body fixed frame as lunar mean Earth (ME) is really what we needed, for which more rotations should be applied besides JPL libration.

luc · December 8, 2025, 8:21am

OK then, thanks for the clarification

Rafa · December 8, 2025, 8:32am

In case it’s somehow useful, as far as I know JPL DE ephemerides provide just phi, theta and psi angles, and their derivatives would be obtained with evaluation of Chebyshev polynomials derivatives with Clenshaw algorithm (the DE specs anticipate having lunar mantle angular velocity coefficients but the number of coefficients for these is set to 0 in DE 440 and DE 441 headers).
But note that I guess this means what you can get from current JPL DE is the derivatives of the Euler angles required for the rotation to transform LCRF ←→ moon body-fixed frame, not the body-fixed axes rotation rates, which are I believe what is required to build a complete transform with rotation rate (and possibly even rotation acceleration).
It’s similar to the situation with PCK kernels of type 2 vs type 3. I have some code in my issue-1681 MR to calculate the rotation rate and acceleration vectors for the complete transform from the angle derivatives in case it’s useful

xzguo · December 8, 2025, 8:42am

hi, @Rafa

if what we need is to define MoonPA, the derivatives could be safely ignored in the transformation, right? more specifically, will the derivatives affect HolmesFeatherstoneAttractionModel?

Rafa · December 9, 2025, 1:48am

@xzguo I guess it depends on the application, for accurate conversion of full state vectors (including velocity and acceleration) between frames I guess it would be necessary to have rotation rates and accelerations as well?

xzguo · December 9, 2025, 6:29am

hi, @luc
sorry for my bothering again. i just have very limited experience in git, and not familiar with orekit CI process.

i just pushed my commit for issue-1865, i.e. adding a new loadLibration method in JPLEphemeridesLoader. Right now, there is problems in Build->Pipelines of my repo.

Can i mage a MR now? i hope my commit will not break things Do you mind and have time to make a check? or perhaps help me to merge the commit?

thanks again. i will go on with the issue 778 update.

luc · December 9, 2025, 6:44am

I have assigned a runner to your project so it is allowed to be built by our CI.
I hope it will be picked up by a runner soon (it may take some time).
If it doesn’t start, you may try to cancel and retry the build.

xzguo · December 10, 2025, 4:59am

well, i messed up my repo, and destroyed it. Now, i committed a issue-1865 fix on a fully new fork, and it stuck in the CI pipeline, because the runner is also lost. But my commit passed the previous CI process, so i decide make a MR anyway.

BTW, any suggestion on how to properly setup CI pipelines in gitlab.orekit.org if all the checks can be done online. And maybe some hints in contributing.md for newbies like me.

thanks

MaximeJ · December 10, 2025, 1:39pm

Hi @xzguo,

Thanks for your contribution!

I’ve added your fork to the runners and the pipeline passed with warnings.
You need to configure SonarQube for it to work completely though.
(also, I opened an issue on how to ask to setup CI pipelines in the “contributing” guide).

Since it’s an enhancement or a new feature, it does not qualify for a patch (only bugs are allowed to be fixed for patches).

Finally, we will need a Contributor License Agreement from you before merging your work.
The form is here, extracted from the Orekit governance model. Once completed, you can send it to cla@orekit.org.

Cheers,
Maxime

xzguo · December 11, 2025, 2:10am

thanks @MaximeJ , i must missed something in the guideline,

while i am logging in gitlab.orekit.org, i managed logging sonar.orekit.org, and there was no notification for generate tokens, so i go to My Account → Security.
there are options for token types, i chose user token.
back to gitlab.orekit.org, i set up key&value for SONAR_TOKEN/SONAR_HOST_URL in my repo’s Settings → CI/CD → Variables
i retried pipeplines and still it could not find the sonarQube

should i in the first step create a project in sonarQube? and which one of the token types should i generate?

thanks again for your kindness help for my trivial questions.

MaximeJ · December 11, 2025, 9:44am

Hi,

Your questions are not trivial. I don’t have an answer for them. @sdinot, do you have any idea why the procedure in the contributing guide didn’t work for @xzguo ?
I think a user token is fine.

sdinot · December 11, 2025, 2:15pm

Dear @xzguo,

I think you are facing a “Project key” issue. Here is what I usually do:

Once you have logged in to SonarQube, go to the Projects page.

There, click on the “Create Project” button at the top right:

(Choose the “GitLab” option)

On the new page, search for xiaozhongguo/orekit ⁣project.

Then click on

On the new page, click on

Then, select “Maven”, and “Continue”.

Then, click on

Choose the default name or another, and “No expiration”. Then, click on

Copy the token (i.e. the value like sqp_b860..1e9e). Be sure to store it in your digital vault, as you will not be able to view it again later.

Then click on “Continue” button.

Then click on “Continue” button (the new one ).

Then click on “Finish this tutorial”.

Copy this token into the SONAR_TOKEN variable in your GitLab project.

Contrary to appearances, you cannot run the analysis yet because:

* SonarQube has generated a random key.

* Our CI/CD pipeline generates a deterministic key based on the namespace and project name.

You must therefore modify the “Project key” in SonarQube. To do this, click on (top right), then on “Update key” and set the project key as follow: xiaozhongguo:orekit (like the project path xiaozhongguo/orekit, but with a “:” instead of a “/”). Then, click on “Update” button and confirm the update.

You can now run your CI/CD pipeline.

(I think we do indeed have two or three points to clarify in the contribution guide )

xzguo · December 12, 2025, 1:17am

hi, @sdinot

i followed your instructions, which are very detailed and convenient.(i also suggest orekit add them all to contributing guide!)

Everything works, until Then click on “Finish this tutorial”, then sonarQube shows You're all set! as of step 4. And i am stuck here . there is no Projcet Settings on the top right, and only a project information for me, in which it displays a Project Key but can not be modified.