About Phasing Example in Orekit 10.0

Greetings. I am currently learning Orekit as an astronautical engineering student by following the given tutorials and examples. I am new in both java and orekit library. The library is awesome. Before asking my question I would like to thank to the community and the developers of the library especially Luc Maisonbe for the didactic examples.
My question is about the Phasing example in version 10.0. As far as I understand from this tutorial, we are trying to design sun synchronous and repeating ground track orbit. Somehow I understood the initialGuess and improveEarthPhasing methods, yet I have got stuck on improveSunSynchronization and improveFrozenEccentricity methods. In those methods, SecularAndHarmonic class has called and hence there are terms such as secular degrees and pulsations. For instance, in improveSunSynchronization code the SecularAndHarmonic class is used as follows;
// find all other latitude crossings from regular schedule
SecularAndHarmonic mstModel = new SecularAndHarmonic(2,
2.0 * FastMath.PI / Constants.JULIAN_YEAR,
4.0 * FastMath.PI / Constants.JULIAN_YEAR,
2.0 * FastMath.PI / Constants.JULIAN_DAY,
4.0 * FastMath.PI / Constants.JULIAN_DAY);
So, what should I understand from these evaluations? What are the 2 and 4 pi over julian day and year terms? (namely the pulsations.)

Also in this phasing example there is a comment like this.
// fit the mean solar time to a parabolic plus medium periods model
// we will only use the linear part for the correction
mstModel.fit();
What is the meaning of parabolic plus medium periods model?
In ApiDocs, SecularAndHarmonic class is defined as fitting evaluation of osculating orbital parameters. So, in these examples are we fitting osculating elements to mean or somethingelse ?
In addition, if you guys have any theoratical document about this example or the concept of the example, may I ask the references kindly?

Again, Thank you very much for this spectacular library.

Kind Regards,
Uzay

Hi @uzayt

Thanks for the kind words, it is appreciated.

The pulsation terms correspond to the \omega factor in an evolution model of the form c \cos \omega t + s \in \omega t. The c and s coefficients being the unknowns that will be fitted. In other words, the harmonic part in SecularAndHarmonics fits only the amplitude, not the frequency (or pulsation here) that must be provided by users. This approach has been selected rather than a Fourier transform because:

  1. not all periods are multiple of each others so any sample, dues to its finite duration,
    cannot be periodic for all terms, some will be truncated mid-period which will violate Fourier
    transform hypothesis
  2. the frequencies we want are discrete and not continuous
  3. the frequencies we want are already known and related to identified physical causes

Fixing the pulsation helps fitting correctly the curve even if the sample range is not a whole number of periods. You can even fit something with yearly period on a sample that is only 8 months long for example. Beware, it is not magic! If you attempt to fit, as above, half day, one day, six months and one year and use a sample range limited to one week, you will end up with garbage. The fitting will find the closest model, but this closest model would only fit for this specific week as the least squares engine will most probably affect some part of the evolution to wrong terms, including the polynomial part that adds to this.

So the four pulsations in the phasing example correspond to terms with one year period, one half year period, one day period and one half day period. In space flight dynamics, pulsations are most often related to periods like \tau_p and \tau_p/2 where \tau_p is the period of the generating perturbation p. For example terms linked to Sun (or Earth revolution parameters) have \tau_\text{Sun} equal to one year. Terms linked to Moon third body attraction have \tau_\text{Moon} slightly below one month. Other periods that appear frequently are the day (linked to Earth rotation, mainly due to Earth gravity field) and the period of the satellite itself.

Parabolic plus mean periods means we want to identify an evolution of the form a + bt + ct^2+\sum_k\left(c_k \cos \omega_k t + s_k \sin\omega_k t\right), with \omega_k limited to medium periods (i.e. we want to remove the short periods). A classical way we do that with SecularAndHarmonics is that we first fit the curve with all known (or meaningful wrt. the sample range) terms to make sure we identified correctly all of them, and then either just consider a few terms, deliberately ignoring the extra ones we added just for getting a better fit, or refitting with a new made up sample built from the previous model and with denser sample points. As an example of the last point, we may have an initial sample that can only be one point per orbit (because for example we sample longitudes of nodes crossings), but for the second stage fit we add up new points between the nodes. This use is really expert use (or rather hack use :shushing_face:).

At the end, yes, this class is a workaround to compute mean elements that we set up before we had DSST model, which computes mean elements in a much much more rigorous way. It remains relevant now that we have DSST in cases we want to sort out some harmonics and not others, or when we know one effect is really periodic but with a long period and on a shorter time scale (say less than half its period) we want to model it as a polynomial.

Another point I forgot.

The phasing tutorial is not really good. It was a hack I set up quickly for a study some years ago and I put it there just because it may interest other users, but it is definitely low quality. Not very good educationally speaking, and it fails to converge in many cases.

For the learning part, I think I should write it again, one day, with better explanations.

For the convergence part, I think I should write it again, one day, using a proper multi-dimensional optimization rather than a loop around three fixed-point iterations (one for period, one for inclination, one for eccentricity). Some times, the separate fixed-point methods creates an infinite loop, most probably between changes in semi-major axis and eccentricity.

So if you are using this as an educational tool, take care, it is not a good example and I am not proud of it. It is a hack.