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 valueTimeSpanMap
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, theaddSpans(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
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 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 forParameterDriversList.DelegatingDriver
)) At construction, the parameter new is configured as not selected, the reference date is set tonull
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 modelsTimeSpanMap
.double
getValue()
Get current parameter value.Gradient
getValue(int freeParameters, Map<String,Integer> indices)
Get the value as a gradient at special date.Gradient
getValue(int freeParameters, Map<String,Integer> indices, AbsoluteDate date)
Get the value as a gradient at special date.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.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.
-
-
-
Field Detail
-
SPAN
public static final String SPAN
Name of the parameter.- See Also:
- Constant Field Values
-
-
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 forParameterDriversList.DelegatingDriver
)) At construction, the parameter new is configured as not selected, the reference date is set tonull
. validityPeriod, namesSpanMap and valueSpanMap.- Parameters:
name
- general name of the parameternamesSpanMap
- 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 mapreferenceValue
- reference value of the parameterscale
- scaling factor to convert the parameters value to non-dimensional (typically set to the expected standard deviation of the parameter), it must be non-zerominValue
- minimum value allowedmaxValue
- 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 thereferenceValue
, 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 theaddSpans(AbsoluteDate, AbsoluteDate, double)
method must be called.- Parameters:
name
- name of the parameterreferenceValue
- reference value of the parameterscale
- scaling factor to convert the parameters value to non-dimensional (typically set to the expected standard deviation of the parameter), it must be non-zerominValue
- minimum value allowedmaxValue
- 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 modelsTimeSpanMap
.- 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 replacenewObserver
- 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 ofParameterDrivenDateIntervalDetector
attribute, because there is no sense to estimate several values for dateDriver.The choice of
orbitDeterminationStartDate
,orbitDeterminationEndDate
andvalidityPeriodForDriver
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 setnormalized
- 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 benull
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 thegetValue()
.- 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 benull
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 thegetValue()
.- 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 benull
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 thegetValue()
.- 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 gradientindices
- 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 gradientindices
- indices of the differentiation parameters in derivatives computations, must be span name and not driver namedate
- 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 benull
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 belowgetMinValue()
, it will be silently set togetMinValue()
. IfnewValue
is abovegetMaxValue()
, it will be silently set togetMaxValue()
.- 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 benull
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 belowgetMinValue()
, it will be silently set togetMinValue()
. IfnewValue
is abovegetMaxValue()
, it will be silently set togetMaxValue()
.- 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
-
-