CachedNormalizedSphericalHarmonicsProvider.java

  1. /* Copyright 2002-2021 CS GROUP
  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.forces.gravity.potential;

  18. import java.util.ArrayList;
  19. import java.util.Collection;
  20. import java.util.Collections;
  21. import java.util.List;
  22. import java.util.stream.Stream;

  23. import org.hipparchus.analysis.interpolation.HermiteInterpolator;
  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.errors.TimeStampedCacheException;
  26. import org.orekit.time.AbsoluteDate;
  27. import org.orekit.time.TimeStamped;
  28. import org.orekit.utils.GenericTimeStampedCache;
  29. import org.orekit.utils.TimeStampedCache;
  30. import org.orekit.utils.TimeStampedGenerator;

  31. /** Caching wrapper for {@link NormalizedSphericalHarmonicsProvider}.
  32.  * <p>
  33.  * This wrapper improves efficiency of {@link NormalizedSphericalHarmonicsProvider}
  34.  * by sampling the values at a user defined rate and using interpolation
  35.  * between samples. This is important with providers that have sub-daily
  36.  * frequencies and are computing intensive, such as tides fields.
  37.  * </p>
  38.  * @see NormalizedSphericalHarmonicsProvider
  39.  * @see org.orekit.forces.gravity.SolidTides
  40.  * @see TimeStampedCache
  41.  * @author Luc Maisonobe
  42.  * @since 6.1
  43.  */
  44. public class CachedNormalizedSphericalHarmonicsProvider implements NormalizedSphericalHarmonicsProvider {

  45.     /** Underlying raw provider. */
  46.     private final NormalizedSphericalHarmonicsProvider rawProvider;

  47.     /** Number of coefficients in C<sub>n, m</sub> and S<sub>n, m</sub> arrays (counted separately). */
  48.     private final int size;

  49.     /** Cache. */
  50.     private final TimeStampedCache<TimeStampedSphericalHarmonics> cache;

  51.     /** Simple constructor.
  52.      * @param rawProvider underlying raw provider
  53.      * @param step time step between sample points for interpolation
  54.      * @param nbPoints number of points to use for interpolation, must be at least 2
  55.      * @param maxSlots maximum number of independent cached time slots
  56.      * @param maxSpan maximum duration span in seconds of one slot
  57.      * (can be set to {@code Double.POSITIVE_INFINITY} if desired)
  58.      * @param newSlotInterval time interval above which a new slot is created
  59.      * instead of extending an existing one
  60.      */
  61.     public CachedNormalizedSphericalHarmonicsProvider(final NormalizedSphericalHarmonicsProvider rawProvider,
  62.                                                       final double step, final int nbPoints,
  63.                                                       final int maxSlots, final double maxSpan,
  64.                                                       final double newSlotInterval) {

  65.         this.rawProvider  = rawProvider;
  66.         final int k       = rawProvider.getMaxDegree() + 1;
  67.         this.size         = (k * (k + 1)) / 2;

  68.         cache = new GenericTimeStampedCache<TimeStampedSphericalHarmonics>(nbPoints, maxSlots, maxSpan,
  69.                                                                            newSlotInterval, new Generator(step));
  70.     }

  71.     /** {@inheritDoc} */
  72.     @Override
  73.     public int getMaxDegree() {
  74.         return rawProvider.getMaxDegree();
  75.     }

  76.     /** {@inheritDoc} */
  77.     @Override
  78.     public int getMaxOrder() {
  79.         return rawProvider.getMaxOrder();
  80.     }

  81.     /** {@inheritDoc} */
  82.     @Override
  83.     public double getMu() {
  84.         return rawProvider.getMu();
  85.     }

  86.     /** {@inheritDoc} */
  87.     @Override
  88.     public double getAe() {
  89.         return rawProvider.getAe();
  90.     }

  91.     /** {@inheritDoc} */
  92.     @Override
  93.     public AbsoluteDate getReferenceDate() {
  94.         return rawProvider.getReferenceDate();
  95.     }

  96.     /** {@inheritDoc} */
  97.     @Override
  98.     public double getOffset(final AbsoluteDate date) {
  99.         return rawProvider.getOffset(date);
  100.     }

  101.     /** {@inheritDoc} */
  102.     @Override
  103.     public TideSystem getTideSystem() {
  104.         return rawProvider.getTideSystem();
  105.     }

  106.     /** {@inheritDoc} */
  107.     @Override
  108.     public NormalizedSphericalHarmonics onDate(final AbsoluteDate date) {
  109.         return TimeStampedSphericalHarmonics.interpolate(date, cache.getNeighbors(date));
  110.     }

  111.     /** Generator for time-stamped spherical harmonics. */
  112.     private class Generator implements TimeStampedGenerator<TimeStampedSphericalHarmonics> {

  113.         /** Time step between generated sets. */
  114.         private final double step;

  115.         /** Simple constructor.
  116.          * @param step time step between generated sets
  117.          */
  118.         Generator(final double step) {
  119.             this.step = step;
  120.         }

  121.         /** {@inheritDoc} */
  122.         @Override
  123.         public List<TimeStampedSphericalHarmonics> generate(final AbsoluteDate existingDate,
  124.                                                             final AbsoluteDate date) {
  125.             try {

  126.                 final List<TimeStampedSphericalHarmonics> generated =
  127.                         new ArrayList<TimeStampedSphericalHarmonics>();
  128.                 final double[] cnmsnm = new double[2 * size];

  129.                 if (existingDate == null) {

  130.                     // no prior existing transforms, just generate a first set
  131.                     for (int i = 0; i < cache.getNeighborsSize(); ++i) {
  132.                         final AbsoluteDate t = date.shiftedBy((i - cache.getNeighborsSize() / 2) * step);
  133.                         fillArray(rawProvider.onDate(t), cnmsnm);
  134.                         generated.add(new TimeStampedSphericalHarmonics(t, cnmsnm));
  135.                     }

  136.                 } else {

  137.                     // some coefficients have already been generated
  138.                     // add the missing ones up to specified date

  139.                     AbsoluteDate t = existingDate;
  140.                     if (date.compareTo(t) > 0) {
  141.                         // forward generation
  142.                         do {
  143.                             t = t.shiftedBy(step);
  144.                             fillArray(rawProvider.onDate(t), cnmsnm);
  145.                             generated.add(new TimeStampedSphericalHarmonics(t, cnmsnm));
  146.                         } while (t.compareTo(date) <= 0);
  147.                     } else {
  148.                         // backward generation
  149.                         do {
  150.                             t = t.shiftedBy(-step);
  151.                             fillArray(rawProvider.onDate(t), cnmsnm);
  152.                             generated.add(new TimeStampedSphericalHarmonics(t, cnmsnm));
  153.                         } while (t.compareTo(date) >= 0);
  154.                         // ensure forward chronological order
  155.                         Collections.reverse(generated);
  156.                     }

  157.                 }

  158.                 // return the generated sample
  159.                 return generated;

  160.             } catch (OrekitException oe) {
  161.                 throw new TimeStampedCacheException(oe);
  162.             }
  163.         }

  164.         /** Fill coefficients array for one entry.
  165.          * @param raw the un-interpolated spherical harmonics
  166.          * @param cnmsnm arrays to fill in
  167.          */
  168.         private void fillArray(final NormalizedSphericalHarmonics raw,
  169.                                final double[] cnmsnm) {
  170.             int index = 0;
  171.             for (int n = 0; n <= rawProvider.getMaxDegree(); ++n) {
  172.                 for (int m = 0; m <= n; ++m) {
  173.                     cnmsnm[index++] = raw.getNormalizedCnm(n, m);
  174.                 }
  175.             }
  176.             for (int n = 0; n <= rawProvider.getMaxDegree(); ++n) {
  177.                 for (int m = 0; m <= n; ++m) {
  178.                     cnmsnm[index++] = raw.getNormalizedSnm(n, m);
  179.                 }
  180.             }
  181.         }

  182.     }

  183.     /**
  184.      * Internal class for time-stamped spherical harmonics. Instances are created using
  185.      * {@link #interpolate(AbsoluteDate, Collection)}
  186.      */
  187.     private static class TimeStampedSphericalHarmonics
  188.             implements TimeStamped, NormalizedSphericalHarmonics {

  189.         /** Current date. */
  190.         private final AbsoluteDate date;

  191.         /** number of C or S coefficients. */
  192.         private final int size;

  193.         /** Flattened array for C<sub>n,m</sub> and S<sub>n,m</sub> coefficients. */
  194.         private final double[] cnmsnm;

  195.         /** Simple constructor.
  196.          * @param date current date
  197.          * @param cnmsnm flattened array for C<sub>n,m</sub> and S<sub>n,m</sub>
  198.          *               coefficients. It is copied.
  199.          */
  200.         private TimeStampedSphericalHarmonics(final AbsoluteDate date,
  201.                                               final double[] cnmsnm) {
  202.             this.date   = date;
  203.             this.cnmsnm = cnmsnm.clone();
  204.             this.size   = cnmsnm.length / 2;
  205.         }

  206.         /** {@inheritDoc} */
  207.         @Override
  208.         public AbsoluteDate getDate() {
  209.             return date;
  210.         }

  211.         /** {@inheritDoc} */
  212.         @Override
  213.         public double getNormalizedCnm(final int n, final int m) {
  214.             return cnmsnm[(n * (n + 1)) / 2 + m];
  215.         }

  216.         /** {@inheritDoc} */
  217.         @Override
  218.         public double getNormalizedSnm(final int n, final int m) {
  219.             return cnmsnm[(n * (n + 1)) / 2 + m + size];
  220.         }

  221.         /** Interpolate spherical harmonics.
  222.          * <p>
  223.          * The interpolated instance is created by polynomial Hermite interpolation.
  224.          * </p>
  225.          * @param date interpolation date
  226.          * @param sample sample points on which interpolation should be done
  227.          * @return a new time-stamped spherical harmonics, interpolated at specified date
  228.          */
  229.         public static TimeStampedSphericalHarmonics interpolate(final AbsoluteDate date,
  230.                                                                 final Stream<TimeStampedSphericalHarmonics> sample) {

  231.             // set up an interpolator taking derivatives into account
  232.             final HermiteInterpolator interpolator = new HermiteInterpolator();

  233.             // add sample points
  234.             sample.forEach(tssh -> interpolator.addSamplePoint(tssh.date.durationFrom(date), tssh.cnmsnm));

  235.             // build a new interpolated instance
  236.             return new TimeStampedSphericalHarmonics(date, interpolator.value(0.0));

  237.         }

  238.     }

  239. }