Normalized Coordinates/Time Paradigm


I’ve got some more time to work on the dedicated normalized coordinates and time classes, and I have some ideas and questions.

I ask first rather than implement first because suspect I’m missing a lot of context and the reasoning behind previously made design decisions, and because I’m wondering what the core Orekit developers had in mind w.r.t. this task.

So, I have three disparate ideas, expanded upon below:

  1. Create extensions of AbsolutePVCoordinates and AbsoluteDate
  2. Create a separate framework of classes for normalized units
  3. Remove units from JavaDocs

The original thread: Dedicated Normalized Coordinates/Time Classes

The task: Add dedicated classes for normalized coordinates and time in CR3BP model (#877) · Issues · Orekit / Orekit · GitLab


The most obvious solution to me is to simply extend AbsolutePVCoordinates and AbsoluteDate and remove replace references to meters and seconds with normalized distance units and normalized time units/etc. in the JavaDocs.

This would allow the new classes to work in place of AbsolutePVCoordinates and AbsoluteDate where necessary; e.g., SpacecraftState, Propagator, etc., which is very convenient.

Unfortunately, It wouldn’t necessarily improve rates of confusion, because things like SpacecraftState would still specify the original classes as return types, which reference real units, thus resulting in confusion.

I have this done locally, just to see what it’s like, and it’s no big deal. I’ve also got a NormalizationFactory to convert between the two.

Separate framework

As I read the task, I think that this is the intent of the original task.

But that might imply new equivalents of everything from PVCoordinatesProvider to AbsolutePVCoordinates and SpacecraftState, and that would be an incredible amount of duplication.

Unitless JavaDocs

I suspect that this is controversial, and I think I agree. But, there would be no confusion so long as the user knew what there units were when they created instances of the classes.

This would, however, require the fewest code changes.

None of the above?

That’s what I’m thinking, but I’d love to hear what your (the core developers) thoughts are!

Hmmm… a NormalizedDate class is not going to play well with leap seconds.

I’m not sure I follow what you want to achieve.

The initial idea was that in the context of C3RBP, the regular classes, which have dimensions, were used in a non-dimensional context, i.e. outside of their intended scope. So this should be corrected. The unwritten assumption (at least for me) was that if we need dimensionless notions, we need them associated with dimensionless classes.

As I understand your proposal, you seem to try to either find a common basis for both dimensional and non-dimensional concepts, or want to suppress completely dimensions. I fear the first option would be difficult and lead to awkward design. Concerning the second option, suppressing dimensions, I am strongly reluctant to it. In operational systems, we do use values with dimensions, and we try to stick to SI, which works quite well.

Indeed, you are correct. And I agree on both fronts. I’m not completely satisfied with any of my proposed ideas.

But I think that that’s why I’m stuck.

It would be simple enough to write a class that we could use as arguments to CR3BPSystem::getRealAPV and CR3BPSystem::getRealPV, but many other places in the code would still require the creation of dimensionless AbsolutePVCoordinates, AbsoluteDates, etc., thus creating confusion.


  • CR3BPMultipleShooter and CR3BPForceModel::acceleration both take SpacecraftStates that must be created (in this context) with an AbsolutePVCoordinates.
  • CR3BPDifferentialCorrection takes a PVCoordinates

So, my concern is that we can create these new classes that hold dimensionless PVA and time/duration, but we’d still end up having to switch to AbsolutePVCoordinates without re-creating the dimensions.

Does that makes sense?

Yes, thanks for the clarification.
I am leaning towards keeping dimensions everywhere, i.e. redesign CR3BP, perhaps adding some kind of context container in the API so the API has dimensions and the private underlying implementation is dimensionless. Would that be possible?

Hmmm… if I understand correctly, something like a DimensionContext (name TBD) that these various methods would take as an argument which would be used internally to convert from “has dimension” to dimensionless?

That would be a nice solution, I think. You would then only being using AbsPV without units internally, thus hiding the confusion.

A pseudo-example, to see if I understand your proposal:

You would have something like

    public interface DimensionContext {
        AbsolutePVCoordinates toDimensionless(AbsolutePVCoorindates absPV);
        SpacecraftState toDimensionless(SpacecraftState absPV);
        PVCoordinates toDimensionless(PVCoorindates absPV);

and then,

        public CR3BPDifferentialCorrection(final PVCoordinates firstguess,
                                           final CR3BPSystem syst,
                                           final double orbitalPeriod) {
            // etc.

would become

        public CR3BPDifferentialCorrection(final PVCoordinates firstguess,
                                           final CR3BPSystem syst,
                                           final double orbitalPeriod,
                                           final DimensionContext dc) {
            final PVCoordinates dimensionlessPV = dc.toDimensionless(firstGuess);
            // etc.

Is that what you’re thinking?

1 Like

This is even an improvement over what I had in mind!
I only thought about a container that would hold some scaling factors, but having conversion methods is far more elegant, well done!

1 Like

Excellent! I’m glad you think so. I’ll get it done.