Package org.orekit.utils

Class ParameterDriver

java.lang.Object
org.orekit.utils.ParameterDriver
Direct Known Subclasses:
AmbiguityDriver, DateDriver, ParameterDriversList.DelegatingDriver
public class ParameterDriver extends Object
Class allowing to drive the value of a parameter.

This class is typically used as a bridge between an estimation algorithm (typically orbit determination or optimizer) and an internal parameter in a physical model that needs to be tuned, or a bridge between a finite differences algorithm and an internal parameter in a physical model that needs to be slightly offset. The physical model will expose to the algorithm a set of instances of this class so the algorithm can call the setValue(double, AbsoluteDate) method to update the parameter value at a given date. Some parameters driver only have 1 value estimated/driven over the all period (constructor by default). Some others have several values estimated/driven on several periods/intervals. For example if the time period is 3 days for a drag parameter estimated all days then 3 values would be estimated, one for each time period. In order to allow several values to be estimated, the PDriver has a name and a value TimeSpanMap as attribute. In order, to cut the time span map there are 2 options :

  • Passive cut calling the addSpans(AbsoluteDate, AbsoluteDate, double) method. Given a start date, an end date and and a validity period (in sec) for the driver, the addSpans(org.orekit.time.AbsoluteDate, org.orekit.time.AbsoluteDate, double) method will cut the interval of name and value time span map from start date to date end in several interval of validity period duration. This method should not be called on orbital drivers and must be called only once at beginning of the process (for example beginning of orbit determination). WARNING : In order to ensure convergence for orbit determination, the start, end date and driver periodicity must be wisely chosen . There must be enough measurements on each interval or convergence won't reach or singular matrices will appear.
  • Active cut calling the addSpanAtDate(AbsoluteDate) method. Given a date, the method will cut the value and name time span name, in order to have a new span starting at the given date. Can be called several time to cut the time map as wished. WARNING : In order to ensure convergence for orbit determination, if the method is called several time, the start date must be wisely chosen . There must be enough measurements on each interval or convergence won't reach or singular matrices will appear.

Several ways exist in order to get a ParameterDriver value at a certain date for parameters having several values on several intervals.

  • First of all, the step estimation, that is to say, if a value wants to be known at a certain date, the value returned is the one of span beginning corresponding to the date. With this definition a value will be kept constant all along the span duration and will be the value at span start.
  • The continuous estimation, that is to say, when a value wants be to known at a date t, the value returned would be a linear interpolation between the value at the beginning of the span corresponding to date t and end this span (which is also the beginning of next span). NOT IMPLEMENTED FOR NOW
Each time the value is set, the physical model will be notified as it will register a ParameterObserver for this purpose.

This design has two major goals. First, it allows an external algorithm to drive internal parameters blindly, as it only needs to get a list of instances of this class, without knowing what they really drive. Second, it allows the physical model to not expose directly setters methods for its parameters. In order to be able to modify the parameter value, the algorithm must retrieve a parameter driver.

Since:
8.0
Author:
Luc Maisonobe, Melina Vanel
See Also:

  • Field Details

  • Constructor Details

    • ParameterDriver

      public ParameterDriver(String name, TimeSpanMap<String> namesSpanMap, TimeSpanMap<Double> valuesSpanMap, double referenceValue, double scale, double minValue, double maxValue)
      Create a new instance from another parameterDriver informations for example (useful for ParameterDriversList.DelegatingDriver)) At construction, the parameter new is configured as not selected, the reference date is set to null. validityPeriod, namesSpanMap and valueSpanMap.
      Parameters:
      name - general name of the parameter
      namesSpanMap - name time span map. WARNING, number of Span must be coherent with validityPeriod and valueSpanMap (same number of Span with same transitions dates)
      valuesSpanMap - values time span map
      referenceValue - reference value of the parameter
      scale - scaling factor to convert the parameters value to non-dimensional (typically set to the expected standard deviation of the parameter), it must be non-zero
      minValue - minimum value allowed
      maxValue - maximum value allowed
      Since:
      12.0

    • ParameterDriver

      public ParameterDriver(String name, double referenceValue, double scale, double minValue, double maxValue)
      Simple constructor.

      At construction, the parameter is configured as not selected, the reference date is set to null, the value is set to the referenceValue, the validity period is set to 0 so by default the parameterDriver will be estimated on only 1 interval from -INF to +INF. To change the validity period the addSpans(AbsoluteDate, AbsoluteDate, double) method must be called.

      Parameters:
      name - name of the parameter
      referenceValue - reference value of the parameter
      scale - scaling factor to convert the parameters value to non-dimensional (typically set to the expected standard deviation of the parameter), it must be non-zero
      minValue - minimum value allowed
      maxValue - maximum value allowed

  • Method Details

    • getNamesSpanMap

      public TimeSpanMap<String> getNamesSpanMap()
      Get current name span map of the parameterDriver, cut in interval in accordance with value span map and validity period.

      Note that if the expunge policy of the names map is reconfigured, then the expunge policy of the values map should be reconfigured too with the same settings.

      Returns:
      current name span map
      Since:
      12.0

    • getValueSpanMap

      public TimeSpanMap<Double> getValueSpanMap()
      Get value time span map for parameterDriver.

      Note that if the expunge policy of the values map is reconfigured, then the expunge policy of the getNamesSpanMap() names map} should be reconfigured too with the same settings.

      Returns:
      value time span map
      Since:
      12.0

    • setValueSpanMap

      public void setValueSpanMap(ParameterDriver driver)
      Set current parameter value span map to match another driver. In order to keep consistency, the validity period and name span map are updated.
      Parameters:
      driver - for which the value span map wants to be copied for the current driver
      Since:
      12.0

    • getNbOfValues

      public int getNbOfValues()
      Get the number of values to estimate that is to say the number. of Span present in valueSpanMap
      Returns:
      int the number of values to estimate
      Since:
      12.0

    • getTransitionDates

      public AbsoluteDate[] getTransitionDates()
      Get the dates of the transitions TimeSpanMap.
      Returns:
      dates of the transitions TimeSpanMap
      Since:
      12.0

    • getValues

      public double[] getValues()
      Get all values of the valueSpanMap in the chronological order.
      Returns:
      double[] containing values of the valueSpanMap in the chronological order

    • addObserver

      public void addObserver(ParameterObserver observer)
      Add an observer for this driver.

      The observer valueSpanMapChanged method is called once automatically when the observer is added, and then called at each value change.

      Parameters:
      observer - observer to add while being updated

    • removeObserver

      public void removeObserver(ParameterObserver observer)
      Remove an observer.
      Parameters:
      observer - observer to remove
      Since:
      9.1

    • replaceObserver

      public void replaceObserver(ParameterObserver oldObserver, ParameterObserver newObserver)
      Replace an observer.
      Parameters:
      oldObserver - observer to replace
      newObserver - new observer to use
      Since:
      10.1

    • getObservers

      public List<ParameterObserver> getObservers()
      Get the observers for this driver.
      Returns:
      an unmodifiable view of the observers for this driver
      Since:
      9.1

    • getName

      public String getName()
      Get parameter driver general name.
      Returns:
      name

    • getNameSpan

      public String getNameSpan(AbsoluteDate date)
      Get name of the parameter span for a specific date.
      Parameters:
      date - date at which the name of the span wants to be known
      Returns:
      name data of the name time span map at date

    • setName

      public void setName(String name)
      Change the general name of this parameter driver.
      Parameters:
      name - new name

    • addSpans

      public void addSpans(AbsoluteDate orbitDeterminationStartDate, AbsoluteDate orbitDeterminationEndDate, double validityPeriodForDriver)
      Cut values and names time span map given orbit determination start and end and driver periodicity.

      For example for a drag coefficient the validity period would be 1 days = 86400sec. To be called after constructor to cut the temporal axis with the wanted parameter driver temporality for estimations on the wanted interval.

      Must be called only once at the beginning of orbit determination for example. If called several times, will throw exception. If parameter estimations intervals must be changed then a new ParameterDriver must be created or the function addSpanAtDate(org.orekit.time.AbsoluteDate) should be used.

      This function should not be called on DateDriver and any of ParameterDrivenDateIntervalDetector attribute, because there is no sense to estimate several values for dateDriver.

      The choice of orbitDeterminationStartDate, orbitDeterminationEndDate and validityPeriodForDriver in a case of orbit determination must be done carefully, indeed, enough measurement should be available for each time interval or the orbit determination won't converge.

      Parameters:
      orbitDeterminationStartDate - start date for which the parameter driver starts to be estimated.
      orbitDeterminationEndDate - end date for which the parameter driver stops to be estimated.
      validityPeriodForDriver - validity period for which the parameter value is effective (for example 1 day for drag coefficient). Warning, validityPeriod should not be too short or the orbit determination won't converge.
      Since:
      12.0

    • addSpanAtDate

      public void addSpanAtDate(AbsoluteDate spanStartDate)
      Create a new span in values and names time span map given a start date. One must be aware of the importance of choosing wise dates if this function is called several times to create several span at wanted times. Indeed, if orbit determination is performed it might not converge or find singular matrix if the spans are too short and contains to few measurements. Must be called before any computation (for example before orbit determination).
      Parameters:
      spanStartDate - wanted start date for parameter value interval starts to be estimated.
      Since:
      12.0

    • getReferenceValue

      public double getReferenceValue()
      Get reference parameter value.
      Returns:
      reference parameter value

    • setReferenceValue

      public void setReferenceValue(double referenceValue)
      Set reference parameter value.
      Parameters:
      referenceValue - the reference value to set.
      Since:
      9.3

    • getMinValue

      public double getMinValue()
      Get minimum parameter value.
      Returns:
      minimum parameter value

    • setMinValue

      public void setMinValue(double minValue)
      Set minimum parameter value.
      Parameters:
      minValue - the minimum value to set.
      Since:
      9.3

    • getMaxValue

      public double getMaxValue()
      Get maximum parameter value.
      Returns:
      maximum parameter value

    • setMaxValue

      public void setMaxValue(double maxValue)
      Set maximum parameter value.
      Parameters:
      maxValue - the maximum value to set.
      Since:
      9.3

    • getScale

      public double getScale()
      Get scale.
      Returns:
      scale

    • setScale

      public void setScale(double scale)
      Set scale.
      Parameters:
      scale - the scale to set.
      Since:
      9.3

    • getNormalizedValue

      public double getNormalizedValue(AbsoluteDate date)
      Get normalized value at specific date.

      The normalized value is a non-dimensional value suitable for use as part of a vector in an optimization process. It is computed as (current - reference)/scale.

      Parameters:
      date - date for which the normalized value wants to be known
      Returns:
      normalized value

    • getNormalizedValue

      public double getNormalizedValue()
      Get normalized value. Only useable on ParameterDriver which have only 1 span on their TimeSpanMap value (that is to say for which the setPeriod method wasn't called) otherwise it will throw an exception.

      The normalized value is a non-dimensional value suitable for use as part of a vector in an optimization process. It is computed as (current - reference)/scale.

      Returns:
      normalized value

    • setNormalizedValue

      public void setNormalizedValue(double normalized, AbsoluteDate date)
      Set normalized value at specific date.

      The normalized value is a non-dimensional value suitable for use as part of a vector in an optimization process. It is computed as (current - reference)/scale.

      Parameters:
      normalized - value
      date - date for which the normalized value wants to be set

    • setNormalizedValue

      public void setNormalizedValue(double normalized)
      Set normalized value at specific date. Only useable on ParameterDriver which have only 1 span on their TimeSpanMap value (that is to say for which the setPeriod method wasn't called) otherwise it will throw an exception.

      The normalized value is a non-dimensional value suitable for use as part of a vector in an optimization process. It is computed as (current - reference)/scale.

      Parameters:
      normalized - value

    • getReferenceDate

      public AbsoluteDate getReferenceDate()
      Get current reference date.
      Returns:
      current reference date (null if it was never set)
      Since:
      9.0

    • setReferenceDate

      public void setReferenceDate(AbsoluteDate newReferenceDate)
      Set reference date.
      Parameters:
      newReferenceDate - new reference date
      Since:
      9.0

    • getValue

      public double getValue()
      Get current parameter value. Only usable on ParameterDriver which have only 1 span on their TimeSpanMap value (that is to say for which the setPeriod method wasn't called)
      Returns:
      current parameter value

    • getValue

      public double getValue(AbsoluteDate date)
      Get current parameter value at specific date, depending on isContinuousEstimation value, the value returned will be obtained by step estimation or continuous estimation.
      Parameters:
      date - date for which the value wants to be known. Only if parameter driver has 1 value estimated over the all orbit determination period (not validity period intervals for estimation), the date value can be null and then the only estimated value will be returned, in this case the date can also be whatever the value returned would be the same. Moreover in this particular case one can also call the getValue().
      Returns:
      current parameter value at date date, or for the all period if no validity period (= 1 value estimated over the all orbit determination period)

    • getValueStepEstimation

      public double getValueStepEstimation(AbsoluteDate date)
      Get current parameter value at specific date with step estimation.
      Parameters:
      date - date for which the value wants to be known. Only if parameter driver has 1 value estimated over the all orbit determination period (not validity period intervals for estimation), the date value can be null and then the only estimated value will be returned, in this case the date can also be whatever the value returned would be the same. Moreover in this particular case one can also call the getValue().
      Returns:
      current parameter value at date date, or for the all period if no validity period (= 1 value estimated over the all orbit determination period)

    • getValueContinuousEstimation

      public double getValueContinuousEstimation(AbsoluteDate date)
      Get current parameter value at specific date with continuous estimation.
      Parameters:
      date - date for which the value wants to be known. Only if parameter driver has 1 value estimated over the all orbit determination period (not validity period intervals for estimation), the date value can be null and then the only estimated value will be returned, in this case the date can also be whatever the value returned would be the same. Moreover in this particular case one can also call the getValue().
      Returns:
      current parameter value at date date, or for the all period if no validity period (= 1 value estimated over the all orbit determination period)
      Since:
      12.0

    • getValue

      public Gradient getValue(int freeParameters, Map<String,Integer> indices)
      Get the value as a gradient at special date.
      Parameters:
      freeParameters - total number of free parameters in the gradient
      indices - indices of the differentiation parameters in derivatives computations
      Returns:
      value with derivatives, will throw exception if called on a PDriver having several values driven
      Since:
      10.2

    • getValue

      public Gradient getValue(int freeParameters, Map<String,Integer> indices, AbsoluteDate date)
      Get the value as a gradient at special date.
      Parameters:
      freeParameters - total number of free parameters in the gradient
      indices - indices of the differentiation parameters in derivatives computations, must be span name and not driver name
      date - date for which the value wants to be known. Only if parameter driver has 1 value estimated over the all orbit determination period (not validity period intervals for estimation), the date value can be null and then the only estimated value will be returned
      Returns:
      value with derivatives
      Since:
      10.2

    • setValue

      public void setValue(double newValue, AbsoluteDate date)
      Set parameter value at specific date.

      If newValue is below getMinValue(), it will be silently set to getMinValue(). If newValue is above getMaxValue(), it will be silently set to getMaxValue().

      Parameters:
      newValue - new value to set
      date - date for which the value wants to be set. Only if parameter driver has 1 value estimated over the all orbit determination period (not validity period intervals for estimation), the date value can be null

    • setValue

      public void setValue(double newValue)
      Set parameter value. Only usable on ParameterDriver which have only 1 span on their TimeSpanMap value (that is to say for which the setPeriod method wasn't called)

      If newValue is below getMinValue(), it will be silently set to getMinValue(). If newValue is above getMaxValue(), it will be silently set to getMaxValue().

      Parameters:
      newValue - new value to set

    • setSelected

      public void setSelected(boolean selected)
      Configure a parameter selection status.

      Selection is used for estimated parameters in orbit determination, or to compute the Jacobian matrix in partial derivatives computation.

      Parameters:
      selected - if true the parameter is selected, otherwise it will be fixed

    • isSelected

      public boolean isSelected()
      Check if parameter is selected.

      Selection is used for estimated parameters in orbit determination, or to compute the Jacobian matrix in partial derivatives computation.

      Returns:
      true if parameter is selected, false if it is not

    • setContinuousEstimation

      public void setContinuousEstimation(boolean continuous)
      Set parameter estimation to continuous, by default step estimation.

      Continuous estimation : when a value wants to be known at date t, the value returned will be an interpolation between start value of the span corresponding to date t and end value (which corresponds to the start of the next span).

      Step estimation : when a value wants to be known at date t, the value returned will be the value of the beginning of span corresponding to date t, step estimation.

      Parameters:
      continuous - if true the parameter will be estimated with continuous estimation, if false with step estimation.

    • isContinuousEstimation

      public boolean isContinuousEstimation()
      Check if parameter estimation is continuous, that is to say when a value wants to be known at date t, the value returned will be an interpolation between start value on span corresponding for date t and end value (which corresponds to the start of the next span), continuous estimation. Or not continuous, that is to say when a value wants to be known at date t, the value returned will be the value of the start of span corresponding to date t, step estimation.
      Returns:
      true if continuous estimation/definition, false if step estimation/definition
      Since:
      12.0

    • toString

      public String toString()
      Get a text representation of the parameter.
      Overrides:
      toString in class Object
      Returns:
      text representation of the parameter, in the form name = value.