Package org.orekit.utils

Class FieldTimeSpanMap<T,F extends CalculusFieldElement<F>>

java.lang.Object
org.orekit.utils.FieldTimeSpanMap<T,F>
Type Parameters:
T - Type of the data.
F - type of the date field elements
public class FieldTimeSpanMap<T,F extends CalculusFieldElement<F>> extends Object
Container for objects that apply to spans of time.

Time span maps can be seen either as an ordered collection of time spans or as an ordered collection of transitions. Both views are dual one to each other. A time span extends from one transition to the next one, and a transition separates one time span from the next one. Each time span contains one entry that is valid during the time span; this entry may be null if nothing is valid during this time span.

Typical uses of FieldTimeSpanMap are to hold piecewise data, like for example an orbit count that changes at ascending nodes (in which case the entry would be an Integer), or a visibility status between several objects (in which case the entry would be a Boolean), or a drag coefficient that is expected to be estimated daily or three-hourly.

Time span maps are built progressively. At first, they contain one time span only whose validity extends from past infinity to future infinity. Then new entries are added one at a time, associated with transition dates, in order to build up the complete map. The transition dates can be either the start of validity (when calling addValidAfter(Object, FieldAbsoluteDate, boolean)), or the end of the validity (when calling addValidBefore(Object, FieldAbsoluteDate, boolean)). Entries are often added at one end only (and mainly in chronological order), but this is not required. It is possible for example to first set up a map that covers a large range (say one day), and then to insert intermediate dates using for example propagation and event detectors to carve out some parts. This is akin to the way Binary Space Partitioning Trees work.

Since 13.1, this class is thread-safe

Since:
7.1
Author:
Luc Maisonobe

  • Constructor Details

    • FieldTimeSpanMap

      public FieldTimeSpanMap(T entry, Field<F> field)
      Create a map containing a single object, initially valid throughout the timeline.

      The real validity of this first entry will be truncated as other entries are either added before it or added after it.

      The initial expunge policy is to never expunge any entries, it can be changed afterward by calling configureExpunge(int, double, ExpungePolicy)

      Parameters:
      entry - entry (initially valid throughout the timeline)
      field - field used by default.

  • Method Details

    • configureExpunge

      public void configureExpunge(int newMaxNbSpans, double newMaxRange, ExpungePolicy newExpungePolicy)
      Configure (or reconfigure) expunge policy for later additions.

      When an entry is added to the map (using either addValidBefore(Object, FieldAbsoluteDate, boolean), addValidBetween(Object, FieldAbsoluteDate, FieldAbsoluteDate), or addValidAfter(Object, FieldAbsoluteDate, boolean) that exceeds the allowed capacity in terms of number of time spans or maximum time range between the earliest and the latest transitions, then exceeding data is expunged according to the expungePolicy.

      Note that as the policy depends on the date at which new entries are added, the policy will be enforced only for the next calls to addValidBefore(Object, FieldAbsoluteDate, boolean), addValidBetween(Object, FieldAbsoluteDate, FieldAbsoluteDate), and addValidAfter(Object, FieldAbsoluteDate, boolean), it is not enforce immediately.

      Parameters:
      newMaxNbSpans - maximum number of time spans
      newMaxRange - maximum time range between the earliest and the latest transitions
      newExpungePolicy - expunge policy to apply when capacity is exceeded
      Since:
      13.1

    • getSpansNumber

      public int getSpansNumber()
      Get the number of spans.

      The number of spans is always at least 1. The number of transitions is always 1 lower than the number of spans.

      Returns:
      number of spans
      Since:
      13.1

    • addValidBefore

      @Deprecated public void addValidBefore(T entry, FieldAbsoluteDate<F> latestValidityDate)
      Deprecated.
      as of 13.1, replaced by addValidBefore(Object, FieldAbsoluteDate, boolean)
      Add an entry valid before a limit date.

      This method just calls addValidBefore(entry, latestValidityDate, false).

      Parameters:
      entry - entry to add
      latestValidityDate - date before which the entry is valid

    • addValidBefore

      public FieldTimeSpanMap.Span<T,F> addValidBefore(T entry, FieldAbsoluteDate<F> latestValidityDate, boolean erasesEarlier)
      Add an entry valid before a limit date.

      As an entry is valid, it truncates the validity of the neighboring entries already present in the map.

      If the map already contains transitions that occur earlier than latestValidityDate, the erasesEarlier parameter controls what to do with them. Let's consider the time span [tₖ; tₖ₊₁[ associated with entry eₖ that would have been valid at time latestValidityDate prior to the call to the method (i.e. tₖ < latestValidityDate < tₖ₊₁).

      • if erasesEarlier is true, then all earlier transitions up to and including tₖ are erased, and the entry will be valid from past infinity to latestValidityDate
      • if erasesEarlier is false, then all earlier transitions are preserved, and the entry will be valid from tₖ to latestValidityDate

      In both cases, the existing entry eₖ time span will be truncated and will be valid only from latestValidityDate to tₖ₊₁.

      Parameters:
      entry - entry to add
      latestValidityDate - date before which the entry is valid
      erasesEarlier - if true, the entry erases all existing transitions that are earlier than latestValidityDate
      Returns:
      span with added entry
      Since:
      13.1

    • addValidAfter

      @Deprecated public void addValidAfter(T entry, FieldAbsoluteDate<F> earliestValidityDate)
      Deprecated.
      as of 13.1, replaced by addValidAfter(Object, FieldAbsoluteDate, boolean)
      Add an entry valid after a limit date.

      This method just calls addValidAfter(entry, earliestValidityDate, false).

      Parameters:
      entry - entry to add
      earliestValidityDate - date after which the entry is valid

    • addValidAfter

      public FieldTimeSpanMap.Span<T,F> addValidAfter(T entry, FieldAbsoluteDate<F> earliestValidityDate, boolean erasesLater)
      Add an entry valid after a limit date.

      As an entry is valid, it truncates or overrides the validity of the neighboring entries already present in the map.

      If the map already contains transitions that occur later than earliestValidityDate, the erasesLater parameter controls what to do with them. Let's consider the time span [tₖ; tₖ₊₁[ associated with entry eₖ that would have been valid at time earliestValidityDate prior to the call to the method (i.e. tₖ < earliestValidityDate < tₖ₊₁).

      • if erasesLater is true, then all later transitions from and including tₖ₊₁ are erased, and the entry will be valid from earliestValidityDate to future infinity
      • if erasesLater is false, then all later transitions are preserved, and the entry will be valid from earliestValidityDate to tₖ₊₁

      In both cases, the existing entry eₖ time span will be truncated and will be valid only from tₖ to earliestValidityDate.

      Parameters:
      entry - entry to add
      earliestValidityDate - date after which the entry is valid
      erasesLater - if true, the entry erases all existing transitions that are later than earliestValidityDate
      Returns:
      span with added entry
      Since:
      13.1

    • addValidBetween

      public FieldTimeSpanMap.Span<T,F> addValidBetween(T entry, FieldAbsoluteDate<F> earliestValidityDate, FieldAbsoluteDate<F> latestValidityDate)
      Add an entry valid between two limit dates.

      As an entry is valid, it truncates or overrides the validity of the neighboring entries already present in the map.

      Parameters:
      entry - entry to add
      earliestValidityDate - date after which the entry is valid
      latestValidityDate - date before which the entry is valid
      Returns:
      span with added entry
      Since:
      13.1

    • get

      public T get(FieldAbsoluteDate<F> date)
      Get the entry valid at a specified date.

      The expected complexity is O(1) for successive calls with neighboring dates, which is the more frequent use in propagation or orbit determination applications, and O(n) for random calls.

      Parameters:
      date - date at which the entry must be valid
      Returns:
      valid entry at specified date
      See Also:

    • getSpan

      public FieldTimeSpanMap.Span<T,F> getSpan(FieldAbsoluteDate<F> date)
      Get the time span containing a specified date.

      The expected complexity is O(1) for successive calls with neighboring dates, which is the more frequent use in propagation or orbit determination applications, and O(n) for random calls.

      Parameters:
      date - date belonging to the desired time span
      Returns:
      time span containing the specified date
      Since:
      13.1

    • getFirstTransition

      public FieldTimeSpanMap.Transition<T,F> getFirstTransition()
      Get the first (earliest) transition.
      Returns:
      first (earliest) transition, or null if there are no transitions
      Since:
      13.1

    • getLastTransition

      public FieldTimeSpanMap.Transition<T,F> getLastTransition()
      Get the last (latest) transition.
      Returns:
      last (latest) transition, or null if there are no transitions
      Since:
      13.1

    • getFirstSpan

      public FieldTimeSpanMap.Span<T,F> getFirstSpan()
      Get the first (earliest) span.
      Returns:
      first (earliest) span
      Since:
      13.1

    • getFirstNonNullSpan

      public FieldTimeSpanMap.Span<T,F> getFirstNonNullSpan()
      Get the first (earliest) span with non-null data.
      Returns:
      first (earliest) span with non-null data
      Since:
      13.1

    • getLastSpan

      public FieldTimeSpanMap.Span<T,F> getLastSpan()
      Get the last (latest) span.
      Returns:
      last (latest) span
      Since:
      13.1

    • getLastNonNullSpan

      public FieldTimeSpanMap.Span<T,F> getLastNonNullSpan()
      Get the last (latest) span with non-null data.
      Returns:
      last (latest) span with non-null data
      Since:
      13.1

    • extractRange

      public FieldTimeSpanMap<T,F> extractRange(FieldAbsoluteDate<F> start, FieldAbsoluteDate<F> end)
      Extract a range of the map.

      The object returned will be a new independent instance that will contain only the transitions that lie in the specified range.

      Consider, for example, a map containing objects O₀ valid before t₁, O₁ valid between t₁ and t₂, O₂ valid between t₂ and t₃, O₃ valid between t₃ and t₄, and O₄ valid after t₄. then calling this method with a start date between t₁ and t₂ and a end date between t₃ and t₄ will result in a new map containing objects O₁ valid before t₂, O₂ valid between t₂ and t₃, and O₃ valid after t₃. The validity of O₁ is therefore extended in the past, and the validity of O₃ is extended in the future.

      Parameters:
      start - earliest date at which a transition is included in the range (may be set to AbsoluteDate.PAST_INFINITY to keep all early transitions)
      end - latest date at which a transition is included in the r (may be set to AbsoluteDate.FUTURE_INFINITY to keep all late transitions)
      Returns:
      a new instance with all transitions restricted to the specified range
      Since:
      13.1

    • forEach

      public void forEach(Consumer<T> action)
      Performs an action for each non-null element of the map.

      The action is performed chronologically.

      Parameters:
      action - action to perform on the non-null elements
      Since:
      13.1

    • getTransitions

      @Deprecated public SortedSet<FieldTimeSpanMap.Transition<T,F>> getTransitions()
      Deprecated.
      as of 13.1, this method is replaced by getFirstTransition() and then following intertwined links between Span and Transition
      Get an unmodifiable view of the sorted transitions.

      Note that since 13.1, this method creates a copy of the current data, it therefore does not update when new spans are added

      Returns:
      unmodifiable view of the sorted transitions