ImmutableFieldTimeStampedCache.java

  1. /* Copyright 2002-2023 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.utils;

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

  25. import org.hipparchus.CalculusFieldElement;
  26. import org.hipparchus.Field;
  27. import org.hipparchus.exception.LocalizedCoreFormats;
  28. import org.hipparchus.util.FastMath;
  29. import org.orekit.errors.OrekitIllegalArgumentException;
  30. import org.orekit.errors.OrekitIllegalStateException;
  31. import org.orekit.errors.OrekitMessages;
  32. import org.orekit.errors.TimeStampedCacheException;
  33. import org.orekit.time.FieldAbsoluteDate;
  34. import org.orekit.time.FieldChronologicalComparator;
  35. import org.orekit.time.FieldTimeStamped;
  36. import org.orekit.time.TimeStamped;

  38. /**
  39.  * A cache of {@link TimeStamped} data that provides concurrency through immutability. This strategy is suitable when all the
  40.  * cached data is stored in memory. (For example, {@link org.orekit.time.UTCScale UTCScale}) This class then provides
  41.  * convenient methods for accessing the data.
  42.  *
  43.  * @param <T> the type of data
  44.  * @param <KK> the type the field element
  45.  *
  46.  * @author Evan Ward
  47.  * @author Vincent Cucchietti
  48.  */
  49. public class ImmutableFieldTimeStampedCache<T extends FieldTimeStamped<KK>, KK extends CalculusFieldElement<KK>>
  50.         implements FieldTimeStampedCache<T, KK> {

  52.     /**
  53.      * the cached data. Be careful not to modify it after the constructor, or return a reference that allows mutating this
  54.      * list.
  55.      */
  56.     private final List<T> data;

  58.     /** the size list to return from {@link #getNeighbors(FieldAbsoluteDate)}. */
  59.     private final int neighborsSize;

  61.     /** Earliest date.
  62.      * @since 12.0
  63.      */
  64.     private final FieldAbsoluteDate<KK> earliestDate;

  66.     /** Latest date.
  67.      * @since 12.0
  68.      */
  69.     private final FieldAbsoluteDate<KK> latestDate;

  71.     /**
  72.      * Create a new cache with the given neighbors size and data.
  73.      *
  74.      * @param neighborsSize the size of the list returned from {@link #getNeighbors(FieldAbsoluteDate)}. Must be less than or
  75.      * equal to {@code data.size()}.
  76.      * @param data the backing data for this cache. The list will be copied to ensure immutability. To guarantee immutability
  77.      * the entries in {@code data} must be immutable themselves. There must be more data than {@code neighborsSize}.
  78.      *
  79.      * @throws IllegalArgumentException if {@code neighborsSize > data.size()} or if {@code neighborsSize} is negative
  80.      */
  81.     public ImmutableFieldTimeStampedCache(final int neighborsSize,
  82.                                           final Collection<? extends T> data) {
  83.         // Parameter check
  84.         if (neighborsSize > data.size()) {
  85.             throw new OrekitIllegalArgumentException(OrekitMessages.NOT_ENOUGH_CACHED_NEIGHBORS,
  86.                                                      data.size(), neighborsSize);
  87.         }
  88.         if (neighborsSize < 1) {
  89.             throw new OrekitIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
  90.                                                      neighborsSize, 0);
  91.         }

  93.         // Assign instance variables
  94.         this.neighborsSize = neighborsSize;

  96.         // Sort and copy data first
  97.         this.data = new ArrayList<>(data);
  98.         Collections.sort(this.data, new FieldChronologicalComparator<>());

  100.         this.earliestDate = this.data.get(0).getDate();
  101.         this.latestDate   = this.data.get(this.data.size() - 1).getDate();

  103.     }

  105.     /**
  106.      * private constructor for {@link #EMPTY_CACHE}.
  107.      * @param field field to which the elements belong
  108.      */
  109.     private ImmutableFieldTimeStampedCache(final Field<KK> field) {
  110.         this.data          = null;
  111.         this.neighborsSize = 0;
  112.         this.earliestDate  = FieldAbsoluteDate.getArbitraryEpoch(field);
  113.         this.latestDate    = FieldAbsoluteDate.getArbitraryEpoch(field);
  114.     }

  116.     /**
  117.      * Get an empty immutable cache, cast to the correct type.
  118.      *
  119.      * @param <TS> the type of data
  120.      * @param <CFE> the type of the calculus field element
  121.      * @param field field to which the elements belong
  122.      * @return an empty {@link ImmutableTimeStampedCache}.
  123.      */
  124.     public static <TS extends FieldTimeStamped<CFE>, CFE extends CalculusFieldElement<CFE>>
  125.         ImmutableFieldTimeStampedCache<TS, CFE> emptyCache(final Field<CFE> field) {
  126.         return new EmptyFieldTimeStampedCache<>(field);
  127.     }

  129.     /** {@inheritDoc} */
  130.     public Stream<T> getNeighbors(final FieldAbsoluteDate<KK> central) {

  132.         // Find central index
  133.         final int i = findIndex(central);

  135.         // Check index in the range of the data
  136.         if (i < 0) {
  137.             final FieldAbsoluteDate<KK> earliest = this.getEarliest().getDate();
  138.             throw new TimeStampedCacheException(OrekitMessages.UNABLE_TO_GENERATE_NEW_DATA_BEFORE,
  139.                                                 earliest, central, earliest.durationFrom(central).getReal());
  140.         }
  141.         else if (i >= this.data.size()) {
  142.             final FieldAbsoluteDate<KK> latest = this.getLatest().getDate();
  143.             throw new TimeStampedCacheException(OrekitMessages.UNABLE_TO_GENERATE_NEW_DATA_AFTER,
  144.                                                 latest, central, central.durationFrom(latest).getReal());
  145.         }

  147.         // Force unbalanced range if necessary
  148.         int start = FastMath.max(0, i - (this.neighborsSize - 1) / 2);
  149.         final int end = FastMath.min(this.data.size(), start +
  150.                 this.neighborsSize);
  151.         start = end - this.neighborsSize;

  153.         // Return list without copying
  154.         return this.data.subList(start, end).stream();
  155.     }

  157.     /** {@inheritDoc} */
  158.     public int getNeighborsSize() {
  159.         return this.neighborsSize;
  160.     }

  162.     /** {@inheritDoc} */
  163.     public T getEarliest() {
  164.         return this.data.get(0);
  165.     }

  167.     /** {@inheritDoc} */
  168.     public T getLatest() {
  169.         return this.data.get(this.data.size() - 1);
  170.     }

  172.     /**
  173.      * Get all the data in this cache.
  174.      *
  175.      * @return a sorted collection of all data passed in the
  176.      * {@link #ImmutableFieldTimeStampedCache(int, Collection) constructor}.
  177.      */
  178.     public List<T> getAll() {
  179.         return Collections.unmodifiableList(this.data);
  180.     }

  182.     /** {@inheritDoc} */
  183.     @Override
  184.     public String toString() {
  185.         return "Immutable cache with " + this.data.size() + " entries";
  186.     }

  188.     /**
  189.      * Find the index, i, to {@link #data} such that {@code data[i] <= t} and {@code data[i+1] > t} if {@code data[i+1]}
  190.      * exists.
  191.      *
  192.      * @param t the time
  193.      *
  194.      * @return the index of the data at or just before {@code t}, {@code -1} if {@code t} is before the first entry, or
  195.      * {@code data.size()} if {@code t} is after the last entry.
  196.      */
  197.     private int findIndex(final FieldAbsoluteDate<KK> t) {
  198.         // left bracket of search algorithm
  199.         int iInf  = 0;
  200.         KK  dtInf = t.durationFrom(earliestDate);
  201.         if (dtInf.getReal() < 0) {
  202.             // before first entry
  203.             return -1;
  204.         }

  206.         // right bracket of search algorithm
  207.         int iSup  = data.size() - 1;
  208.         KK  dtSup = t.durationFrom(latestDate);
  209.         if (dtSup.getReal() > 0) {
  210.             // after last entry
  211.             return data.size();
  212.         }

  214.         // search entries, using linear interpolation
  215.         // this should take only 2 iterations for near linear entries (most frequent use case)
  216.         // regardless of the number of entries
  217.         // this is much faster than binary search for large number of entries
  218.         while (iSup - iInf > 1) {
  219.             final int iInterp = (int) FastMath.rint(dtSup.multiply(iInf).subtract(dtInf.multiply(iSup)).divide(dtSup.subtract(dtInf)).getReal());
  220.             final int iMed    = FastMath.max(iInf + 1, FastMath.min(iInterp, iSup - 1));
  221.             final KK  dtMed   = t.durationFrom(data.get(iMed).getDate());
  222.             if (dtMed.getReal() < 0) {
  223.                 iSup  = iMed;
  224.                 dtSup = dtMed;
  225.             } else {
  226.                 iInf  = iMed;
  227.                 dtInf = dtMed;
  228.             }
  229.         }

  231.         return iInf;
  232.     }

  234.     /** An empty immutable cache that always throws an exception on attempted access. */
  235.     private static class EmptyFieldTimeStampedCache<T extends FieldTimeStamped<KK>, KK extends CalculusFieldElement<KK>>
  236.             extends ImmutableFieldTimeStampedCache<T, KK> {

  238.         /** Simple constructor.
  239.          * @param field field to which elements belong
  240.          */
  241.         EmptyFieldTimeStampedCache(final Field<KK> field) {
  242.             super(field);
  243.         }

  245.         /** {@inheritDoc} */
  246.         @Override
  247.         public Stream<T> getNeighbors(final FieldAbsoluteDate<KK> central) {
  248.             throw new TimeStampedCacheException(OrekitMessages.NO_CACHED_ENTRIES);
  249.         }

  251.         /** {@inheritDoc} */
  252.         @Override
  253.         public int getNeighborsSize() {
  254.             return 0;
  255.         }

  257.         /** {@inheritDoc} */
  258.         @Override
  259.         public T getEarliest() {
  260.             throw new OrekitIllegalStateException(OrekitMessages.NO_CACHED_ENTRIES);
  261.         }

  263.         /** {@inheritDoc} */
  264.         @Override
  265.         public T getLatest() {
  266.             throw new OrekitIllegalStateException(OrekitMessages.NO_CACHED_ENTRIES);
  267.         }

  269.         /** {@inheritDoc} */
  270.         @Override
  271.         public List<T> getAll() {
  272.             return Collections.emptyList();
  273.         }

  275.         /** {@inheritDoc} */
  276.         @Override
  277.         public String toString() {
  278.             return "Empty immutable cache";
  279.         }

  281.     }

  283. }
Created with JaCoCo 0.8.11.202310140853