SingleParameterFitter.java

  1. /* Copyright 2002-2024 Luc Maisonobe
  2.  * Licensed to CS GROUP (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.frames;

  18. import java.io.Serializable;
  19. import java.util.List;
  20. import java.util.ListIterator;
  21. import java.util.function.ToDoubleFunction;

  22. import org.hipparchus.util.FastMath;
  23. import org.hipparchus.util.MathUtils;
  24. import org.orekit.utils.Constants;
  25. import org.orekit.utils.SecularAndHarmonic;

  26. /** Fitter for one Earth Orientation Parameter.
  27.  * @see PredictedEOPHistory
  28.  * @see EOPFitter
  29.  * @see SecularAndHarmonic
  30.  * @since 12.0
  31.  * @author Luc Maisonobe
  32.  */
  33. public class SingleParameterFitter implements Serializable {

  34.     /** Sun pulsation, one year period. */
  35.     public static final double SUN_PULSATION = MathUtils.TWO_PI / Constants.JULIAN_YEAR;

  36.     /** Moon pulsation (one Moon draconic period). */
  37.     public static final double MOON_DRACONIC_PULSATION = MathUtils.TWO_PI / (27.212221 * Constants.JULIAN_DAY);

  38.     /** Serializable UID. */
  39.     private static final long serialVersionUID = 20230309L;

  40.     /** Time constant of the exponential decay weight. */
  41.     private final double timeConstant;

  42.     /** Convergence on fitted parameter. */
  43.     private final double convergence;

  44.     /** Degree of the polynomial model. */
  45.     private final int degree;

  46.     /** Pulsations of harmonic part (rad/s). */
  47.     private final double[] pulsations;

  48.     /** Simple constructor.
  49.      * @param fittingDuration ignored parameter since 12.0
  50.      * @param timeConstant time constant \(\tau\) of the exponential decay weight, point weight is \(e^{\frac{t-t_0}{\tau}}\),
  51.      * i.e. points far in the past before \(t_0\) have smaller weights
  52.      * @param convergence convergence on fitted parameter
  53.      * @param degree degree of the polynomial model
  54.      * @param pulsations pulsations of harmonic part (rad/s)
  55.      * @see #createDefaultDut1FitterShortTermPrediction()
  56.      * @see #createDefaultDut1FitterLongTermPrediction()
  57.      * @see #createDefaultPoleFitterShortTermPrediction()
  58.      * @see #createDefaultPoleFitterLongTermPrediction()
  59.      * @see #createDefaultNutationFitterShortTermPrediction()
  60.      * @see #createDefaultNutationFitterLongTermPrediction()
  61.      * @see SecularAndHarmonic
  62.      * @deprecated replaced by {@link #SingleParameterFitter(double, double, int, double...)}
  63.      */
  64.     @Deprecated
  65.     public SingleParameterFitter(final double fittingDuration, final double timeConstant, final double convergence,
  66.                                  final int degree, final double... pulsations) {
  67.         this(timeConstant, convergence, degree, pulsations);
  68.     }

  69.     /** Simple constructor.
  70.      * @param timeConstant time constant \(\tau\) of the exponential decay weight, point weight is \(e^{\frac{t-t_0}{\tau}}\),
  71.      * i.e. points far in the past before \(t_0\) have smaller weights
  72.      * @param convergence convergence on fitted parameter
  73.      * @param degree degree of the polynomial model
  74.      * @param pulsations pulsations of harmonic part (rad/s)
  75.      * @see #createDefaultDut1FitterShortTermPrediction()
  76.      * @see #createDefaultDut1FitterLongTermPrediction()
  77.      * @see #createDefaultPoleFitterShortTermPrediction()
  78.      * @see #createDefaultPoleFitterLongTermPrediction()
  79.      * @see #createDefaultNutationFitterShortTermPrediction()
  80.      * @see #createDefaultNutationFitterLongTermPrediction()
  81.      * @see SecularAndHarmonic
  82.      * @since 12.0.1
  83.      */
  84.     public SingleParameterFitter(final double timeConstant, final double convergence,
  85.                                  final int degree, final double... pulsations) {
  86.         this.timeConstant    = timeConstant;
  87.         this.convergence     = convergence;
  88.         this.degree          = degree;
  89.         this.pulsations      = pulsations.clone();
  90.     }

  91.     /** Perform secular and harmonic fitting.
  92.      * @param rawHistory EOP history to fit
  93.      * @param extractor extractor for Earth Orientation Parameter
  94.      * @return configured fitter
  95.      */
  96.     public SecularAndHarmonic fit(final EOPHistory rawHistory, final ToDoubleFunction<EOPEntry> extractor) {

  97.         final List<EOPEntry> rawEntries = rawHistory.getEntries();
  98.         final EOPEntry       last       = rawEntries.get(rawEntries.size() - 1);

  99.         // create fitter
  100.         final SecularAndHarmonic sh = new SecularAndHarmonic(degree, pulsations);

  101.         // set up convergence
  102.         sh.setConvergenceRMS(convergence);

  103.         // set up reference date and initial guess to a constant value
  104.         final double[] initialGuess = new double[degree + 1 + 2 * pulsations.length];
  105.         initialGuess[0] = extractor.applyAsDouble(last);
  106.         sh.resetFitting(last.getDate(), initialGuess);

  107.         // sample history
  108.         final ListIterator<EOPEntry> backwardIterator = rawEntries.listIterator(rawEntries.size());
  109.         while (backwardIterator.hasPrevious()) {
  110.             final EOPEntry entry = backwardIterator.previous();
  111.             sh.addWeightedPoint(entry.getDate(), extractor.applyAsDouble(entry),
  112.                                 FastMath.exp(entry.getDate().durationFrom(last.getDate()) / timeConstant));
  113.         }

  114.         // perform fitting
  115.         sh.fit();

  116.         return sh;

  117.     }

  118.     /** Create fitter with default parameters adapted for fitting orientation parameters dUT1 and LOD
  119.      * for short term prediction.
  120.      * <p>
  121.      * The main difference between these settings and {@link #createDefaultDut1FitterLongTermPrediction()
  122.      * the settings for long prediction} is the much smaller \(\tau\). This means more
  123.      * weight is set to the points at the end of the history, hence forcing the fitted prediction
  124.      * model to be closer to these points, hence the prediction error to be smaller just after
  125.      * raw history end. On the other hand, this implies that the model will diverge on long term.
  126.      * These settings are intended when prediction is used for at most 5 days after raw EOP end.
  127.      * </p>
  128.      * <ul>
  129.      *   <li>time constant \(\tau\) of the exponential decay set to 6 {@link Constants#JULIAN_DAY days}</li>
  130.      *   <li>convergence set to 10⁻¹² s</li>
  131.      *   <li>polynomial part set to degree 3</li>
  132.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  133.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  134.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  135.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  136.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  137.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  138.      * </ul>
  139.      * @return fitter with default configuration for orientation parameters dUT1 and LOD
  140.      * @see #createDefaultDut1FitterShortTermPrediction()
  141.      */
  142.     public static SingleParameterFitter createDefaultDut1FitterShortTermPrediction() {
  143.         return new SingleParameterFitter(6 * Constants.JULIAN_DAY, 1.0e-12, 3,
  144.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  145.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  146.     }

  147.     /** Create fitter with default parameters adapted for fitting orientation parameters dUT1 and LOD
  148.      * for long term prediction.
  149.      * <p>
  150.      * The main difference between these settings and {@link #createDefaultDut1FitterShortTermPrediction()
  151.      * the settings for short prediction} is the much larger \(\tau\). This means weight
  152.      * is spread throughout history, hence forcing the fitted prediction model to be remain very stable
  153.      * on the long term. On the other hand, this implies that the model will start with already a much
  154.      * larger error just after raw history end.
  155.      * These settings are intended when prediction is used for 5 days after raw EOP end or more.
  156.      * </p>
  157.      * <ul>
  158.      *   <li>time constant \(\tau\) of the exponential decay set to 60 {@link Constants#JULIAN_DAY days}</li>
  159.      *   <li>convergence set to 10⁻¹² s</li>
  160.      *   <li>polynomial part set to degree 3</li>
  161.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  162.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  163.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  164.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  165.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  166.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  167.      * </ul>
  168.      * @return fitter with default configuration for orientation parameters dUT1 and LOD
  169.      * @see #createDefaultDut1FitterShortTermPrediction()
  170.      */
  171.     public static SingleParameterFitter createDefaultDut1FitterLongTermPrediction() {
  172.         return new SingleParameterFitter(60 * Constants.JULIAN_DAY, 1.0e-12, 3,
  173.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  174.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  175.     }

  176.     /** Create fitter with default parameters adapted for fitting pole parameters Xp and Yp
  177.      * for long term prediction.
  178.      * <p>
  179.      * The main difference between these settings and {@link #createDefaultPoleFitterLongTermPrediction()
  180.      * the settings for long prediction} is the much smaller \(\tau\). This means more
  181.      * weight is set to the points at the end of the history, hence forcing the fitted prediction
  182.      * model to be closer to these points, hence the prediction error to be smaller just after
  183.      * raw history end. On the other hand, this implies that the model will diverge on long term.
  184.      * These settings are intended when prediction is used for at most 5 days after raw EOP end.
  185.      * </p>
  186.      * <ul>
  187.      *   <li>time constant \(\tau\) of the exponential decay set to 12 {@link Constants#JULIAN_DAY days}</li>
  188.      *   <li>convergence set to 10⁻¹² rad</li>
  189.      *   <li>polynomial part set to degree 3</li>
  190.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  191.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  192.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  193.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  194.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  195.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  196.      * </ul>
  197.      * @return fitter with default configuration for pole parameters Xp and Yp
  198.      */
  199.     public static SingleParameterFitter createDefaultPoleFitterShortTermPrediction() {
  200.         return new SingleParameterFitter(12 * Constants.JULIAN_DAY, 1.0e-12, 3,
  201.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  202.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  203.     }

  204.     /** Create fitter with default parameters adapted for fitting pole parameters Xp and Yp
  205.      * for long term prediction.
  206.      * <p>
  207.      * The main difference between these settings and {@link #createDefaultPoleFitterShortTermPrediction()
  208.      * the settings for short prediction} is the much larger \(\tau\). This means weight
  209.      * is spread throughout history, hence forcing the fitted prediction model to be remain very stable
  210.      * on the long term. On the other hand, this implies that the model will start with already a much
  211.      * larger error just after raw history end.
  212.      * These settings are intended when prediction is used for 5 days after raw EOP end or more.
  213.      * </p>
  214.      * <ul>
  215.      *   <li>time constant \(\tau\) of the exponential decay set to 60 {@link Constants#JULIAN_DAY days}</li>
  216.      *   <li>convergence set to 10⁻¹² rad</li>
  217.      *   <li>polynomial part set to degree 3</li>
  218.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  219.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  220.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  221.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  222.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  223.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  224.      * </ul>
  225.      * @return fitter with default configuration for pole parameters Xp and Yp
  226.      */
  227.     public static SingleParameterFitter createDefaultPoleFitterLongTermPrediction() {
  228.         return new SingleParameterFitter(60 * Constants.JULIAN_DAY, 1.0e-12, 3,
  229.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  230.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  231.     }

  232.     /** Create fitter with default parameters adapted for fitting nutation parameters dx and dy
  233.      * for long term prediction.
  234.      * <p>
  235.      * The main difference between these settings and {@link #createDefaultNutationFitterLongTermPrediction()
  236.      * the settings for long prediction} is the much smaller \(\tau\). This means more
  237.      * weight is set to the points at the end of the history, hence forcing the fitted prediction
  238.      * model to be closer to these points, hence the prediction error to be smaller just after
  239.      * raw history end. On the other hand, this implies that the model will diverge on long term.
  240.      * These settings are intended when prediction is used for at most 5 days after raw EOP end.
  241.      * </p>
  242.      * <ul>
  243.      *   <li>time constant \(\tau\) of the exponential decay set to 12 {@link Constants#JULIAN_DAY days}</li>
  244.      *   <li>convergence set to 10⁻¹² s</li>
  245.      *   <li>polynomial part set to degree 3</li>
  246.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  247.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  248.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  249.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  250.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  251.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  252.      * </ul>
  253.      * @return fitter with default configuration for pole nutation parameters dx and dy
  254.      */
  255.     public static SingleParameterFitter createDefaultNutationFitterShortTermPrediction() {
  256.         return new SingleParameterFitter(12 * Constants.JULIAN_DAY, 1.0e-12, 3,
  257.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  258.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  259.     }

  260.     /** Create fitter with default parameters adapted for fitting nutation parameters dx and dy
  261.      * for long term prediction.
  262.      * <p>
  263.      * The main difference between these settings and {@link #createDefaultNutationFitterShortTermPrediction()
  264.      * the settings for short prediction} is the much larger \(\tau\). This means weight
  265.      * is spread throughout history, hence forcing the fitted prediction model to be remain very stable
  266.      * on the long term. On the other hand, this implies that the model will start with already a much
  267.      * larger error just after raw history end.
  268.      * These settings are intended when prediction is used for 5 days after raw EOP end or more.
  269.      * </p>
  270.      * <ul>
  271.      *   <li>time constant \(\tau\) of the exponential decay set to 60 {@link Constants#JULIAN_DAY days}</li>
  272.      *   <li>convergence set to 10⁻¹² s</li>
  273.      *   <li>polynomial part set to degree 3</li>
  274.      *   <li>one harmonic term at {@link #SUN_PULSATION}}</li>
  275.      *   <li>one harmonic term at 2 times {@link #SUN_PULSATION}}</li>
  276.      *   <li>one harmonic term at 3 times {@link #SUN_PULSATION}}</li>
  277.      *   <li>one harmonic term at {@link #MOON_DRACONIC_PULSATION}}</li>
  278.      *   <li>one harmonic term at 2 times {@link #MOON_DRACONIC_PULSATION}}</li>
  279.      *   <li>one harmonic term at 3 times {@link #MOON_DRACONIC_PULSATION}}</li>
  280.      * </ul>
  281.      * @return fitter with default configuration for pole nutation parameters dx and dy
  282.      */
  283.     public static SingleParameterFitter createDefaultNutationFitterLongTermPrediction() {
  284.         return new SingleParameterFitter(60 * Constants.JULIAN_DAY, 1.0e-12, 3,
  285.                                          SUN_PULSATION, 2 * SUN_PULSATION, 3 * SUN_PULSATION,
  286.                                          MOON_DRACONIC_PULSATION, 2 * MOON_DRACONIC_PULSATION, 3 * MOON_DRACONIC_PULSATION);
  287.     }

  288. }