ParameterDriver (OREKIT 12.0.1 API)

java.lang.Object
- org.orekit.utils.ParameterDriver

Direct Known Subclasses:

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 Summary

Constructors
Constructor and Description
`ParameterDriver(String name, double referenceValue, double scale, double minValue, double maxValue)` Simple constructor.
`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`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addObserver(ParameterObserver observer)` Add an observer for this driver.
`void`	`addSpanAtDate(AbsoluteDate spanStartDate)` Create a new span in values and names time span map given a start date.
`void`	`addSpans(AbsoluteDate orbitDeterminationStartDate, AbsoluteDate orbitDeterminationEndDate, double validityPeriodForDriver)` Cut values and names time span map given orbit determination start and end and driver periodicity.
`double`	`getMaxValue()` Get maximum parameter value.
`double`	`getMinValue()` Get minimum parameter value.
`String`	`getName()` Get parameter driver general name.
`String`	`getNameSpan(AbsoluteDate date)` Get name of the parameter span for a specific date.
`TimeSpanMap<String>`	`getNamesSpanMap()` Get current name span map of the parameterDriver, cut in interval in accordance with value span map and validity period.
`int`	`getNbOfValues()` Get the number of values to estimate that is to say the number.
`double`	`getNormalizedValue()` Get normalized value.
`double`	`getNormalizedValue(AbsoluteDate date)` Get normalized value at specific date.
`List<ParameterObserver>`	`getObservers()` Get the observers for this driver.
`AbsoluteDate`	`getReferenceDate()` Get current reference date.
`double`	`getReferenceValue()` Get reference parameter value.
`double`	`getScale()` Get scale.
`AbsoluteDate[]`	`getTransitionDates()` Get the dates of the transitions for the drag sensitive models `TimeSpanMap`.
`double`	`getValue()` Get current parameter value.
`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.
`org.hipparchus.analysis.differentiation.Gradient`	`getValue(int freeParameters, Map<String,Integer> indices)` Get the value as a gradient at special date.
`org.hipparchus.analysis.differentiation.Gradient`	`getValue(int freeParameters, Map<String,Integer> indices, AbsoluteDate date)` Get the value as a gradient at special date.
`double`	`getValueContinuousEstimation(AbsoluteDate date)` Get current parameter value at specific date with continuous estimation.
`double[]`	`getValues()` Get all values of the valueSpanMap in the chronological order.
`TimeSpanMap<Double>`	`getValueSpanMap()` Get value time span map for parameterDriver.
`double`	`getValueStepEstimation(AbsoluteDate date)` Get current parameter value at specific date with step estimation.
`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.
`boolean`	`isSelected()` Check if parameter is selected.
`void`	`removeObserver(ParameterObserver observer)` Remove an observer.
`void`	`replaceObserver(ParameterObserver oldObserver, ParameterObserver newObserver)` Replace an observer.
`void`	`setContinuousEstimation(boolean continuous)` Set parameter estimation to continuous, by default step estimation.
`void`	`setMaxValue(double maxValue)` Set maximum parameter value.
`void`	`setMinValue(double minValue)` Set minimum parameter value.
`void`	`setName(String name)` Change the general name of this parameter driver.
`void`	`setNormalizedValue(double normalized)` Set normalized value at specific date.
`void`	`setNormalizedValue(double normalized, AbsoluteDate date)` Set normalized value at specific date.
`void`	`setReferenceDate(AbsoluteDate newReferenceDate)` Set reference date.
`void`	`setReferenceValue(double referenceValue)` Set reference parameter value.
`void`	`setScale(double scale)` Set scale.
`void`	`setSelected(boolean selected)` Configure a parameter selection status.
`void`	`setValue(double newValue)` Set parameter value.
`void`	`setValue(double newValue, AbsoluteDate date)` Set parameter value at specific date.
`void`	`setValueSpanMap(ParameterDriver driver)` Set current parameter value span map to match another driver.
`String`	`toString()` Get a text representation of the parameter.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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
  - getTransitionDates
```
public AbsoluteDate[] getTransitionDates()
```
    Get the dates of the transitions for the drag sensitive models TimeSpanMap.
    
    Returns:
    
    dates of the transitions for the drag sensitive models 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:
    
    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 org.hipparchus.analysis.differentiation.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 org.hipparchus.analysis.differentiation.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.

Class ParameterDriver

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ParameterDriver

ParameterDriver

Method Detail

getNamesSpanMap

getValueSpanMap

setValueSpanMap

getNbOfValues

getTransitionDates

getValues

addObserver

removeObserver

replaceObserver

getObservers

getName

getNameSpan

setName

addSpans

addSpanAtDate

getReferenceValue

setReferenceValue

getMinValue

setMinValue

getMaxValue

setMaxValue

getScale

setScale

getNormalizedValue

getNormalizedValue

setNormalizedValue

setNormalizedValue

getReferenceDate

setReferenceDate

getValue

getValue

getValueStepEstimation

getValueContinuousEstimation

getValue

getValue

setValue

setValue

setSelected

isSelected

setContinuousEstimation

isContinuousEstimation

toString