Package org.orekit.utils

Class 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 converge for orbit determination, the start, end date and driver periodicity must be wisely choosen . There must be enough measurements on each interval or convergence won't reach or singular matrixes 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 converge for orbit determination, if the method is called several time, the start date must be wisely choosen . There must be enough measurements on each interval or convergence won't reach or singular matrixes 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 all along the span duration and will be the value of the 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 almost anonymously, 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:
    ParameterObserver

    • Constructor Detail

      • 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 Detail

      • 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.
        Returns:
        current name span map
        Since:
        12.0

      • getValueSpanMap

        public TimeSpanMap<Double> getValueSpanMap()
        Get value time span map for parameterDriver.
        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

      • 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:
        date - date for which the normalized value wants to be set
        normalized - value

      • 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:
        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
        newValue - new value to set

      • 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.