Package org.orekit.estimation.leastsquares

Class BatchLSEstimator

java.lang.Object
org.orekit.estimation.leastsquares.BatchLSEstimator
All Implemented Interfaces:
ParameterEstimator
Direct Known Subclasses:
SequentialBatchLSEstimator
public class BatchLSEstimator extends Object implements ParameterEstimator
Least squares estimator for orbit determination.

The least squares estimator can be used with different orbit propagators in Orekit. Current propagators list of usable propagators are numerical, DSST, Brouwer-Lyddane, Eckstein-Hechler, SGP4, Keplerian, and ephemeris-based.

Since:
8.0
Author:
Luc Maisonobe

  • Constructor Details

    • BatchLSEstimator

      public BatchLSEstimator(LeastSquaresOptimizer optimizer, PropagatorBuilder... propagatorBuilder)
      Simple constructor.

      If multiple propagator builders are set up, the orbits of several spacecrafts will be used simultaneously. This is useful if the propagators share some model or measurements parameters (typically pole motion, prime meridian correction or ground stations positions).

      Setting up multiple propagator builders is also useful when inter-satellite measurements are used, even if only one of the orbit is estimated and the other ones are fixed. This is typically used when very high accuracy GNSS measurements are needed and the navigation bulletins are not considered accurate enough and the navigation constellation must be propagated numerically.

      Parameters:
      optimizer - solver for least squares problem
      propagatorBuilder - builders to use for propagation

  • Method Details

    • setObserver

      public void setObserver(BatchLSObserver observer)
      Set an observer for iterations.
      Parameters:
      observer - observer to be notified at the end of each iteration

    • addMeasurement

      public void addMeasurement(ObservedMeasurement<?> measurement)
      Add a measurement.
      Parameters:
      measurement - measurement to add

    • setMaxIterations

      public void setMaxIterations(int maxIterations)
      Set the maximum number of iterations.

      The iterations correspond to the top level iterations of the least squares optimizer.

      Parameters:
      maxIterations - maxIterations maximum number of iterations
      See Also:

    • setMaxEvaluations

      public void setMaxEvaluations(int maxEvaluations)
      Set the maximum number of model evaluations.

      The evaluations correspond to the orbit propagations and measurements estimations performed with a set of estimated parameters.

      For Gauss-Newton optimizer there is one evaluation at each iteration, so the maximum numbers may be set to the same value. For Levenberg-Marquardt optimizer, there can be several evaluations at some iterations (typically for the first couple of iterations), so the maximum number of evaluations may be set to a higher value than the maximum number of iterations.

      Parameters:
      maxEvaluations - maximum number of model evaluations
      See Also:

    • getPropagatorBuilders

      public PropagatorBuilder[] getPropagatorBuilders()
      Description copied from interface: ParameterEstimator
      Getter for the propagator builders.
      Specified by:
      getPropagatorBuilders in interface ParameterEstimator
      Returns:
      builders

    • getMeasurementsParametersDrivers

      public ParameterDriversList getMeasurementsParametersDrivers(boolean estimatedOnly)
      Get the measurements parameters supported by this estimator (including measurements and modifiers).
      Parameters:
      estimatedOnly - if true, only estimated parameters are returned
      Returns:
      measurements parameters supported by this estimator

    • setParametersConvergenceThreshold

      public void setParametersConvergenceThreshold(double parametersConvergenceThreshold)
      Set convergence threshold.

      The convergence used for estimation is based on the estimated parameters normalized values. Convergence is considered to have been reached when the difference between previous and current normalized value is less than the convergence threshold for all parameters. The same value is used for all parameters since they are normalized and hence dimensionless.

      Normalized values are computed as (current - reference)/scale, so convergence is reached when the following condition holds for all estimated parameters: |current[i] - previous[i]| <= threshold * scale[i]

      So the convergence threshold specified here can be considered as a multiplication factor applied to scale. Since for all parameters the scale is often small (typically about 1 m for orbital positions for example), then the threshold should not be too small. A value of 10⁻³ is often quite accurate.

      Calling this method overrides any checker that could have been set beforehand by calling setConvergenceChecker(ConvergenceChecker). Both methods are mutually exclusive.

      Parameters:
      parametersConvergenceThreshold - convergence threshold on normalized parameters (dimensionless, related to parameters scales)
      See Also:

    • setConvergenceChecker

      public void setConvergenceChecker(ConvergenceChecker<LeastSquaresProblem.Evaluation> convergenceChecker)
      Set a custom convergence checker.

      Calling this method overrides any checker that could have been set beforehand by calling setParametersConvergenceThreshold(double). Both methods are mutually exclusive.

      Parameters:
      convergenceChecker - convergence checker to set
      Since:
      10.1
      See Also:

    • estimate

      public Propagator[] estimate()
      Estimate the orbital, propagation and measurements parameters.

      The initial guess for all parameters must have been set before calling this method using ParameterEstimator.getOrbitalParametersDrivers(boolean), ParameterEstimator.getPropagationParametersDrivers(boolean) (boolean)}, and getMeasurementsParametersDrivers(boolean) and then setting the values of the parameters.

      For parameters whose reference date has not been set to a non-null date beforehand (i.e. the parameters for which ParameterDriver.getReferenceDate() returns null, a default reference date will be set automatically at the start of the estimation to the initial orbit date of the first propagator builder. For parameters whose reference date has been set to a non-null date, this reference date is untouched.

      After this method returns, the estimated parameters can be retrieved using ParameterEstimator.getOrbitalParametersDrivers(boolean), ParameterEstimator.getPropagationParametersDrivers(boolean) (boolean)}, and getMeasurementsParametersDrivers(boolean) and then getting the values of the parameters.

      As a convenience, the method also returns a fully configured and ready to use propagator set up with all the estimated values.

      For even more in-depth information, the getOptimum() method provides detailed elements (covariance matrix, estimated parameters standard deviation, weighted Jacobian, RMS, χ², residuals and more).

      Returns:
      propagators configured with estimated orbits as initial states, and all propagators estimated parameters also set

    • getLastEstimations

      public Map<ObservedMeasurement<?>,EstimatedMeasurement<?>> getLastEstimations()
      Get the last estimations performed.
      Returns:
      last estimations performed

    • getOptimum

      public LeastSquaresOptimizer.Optimum getOptimum()
      Get the optimum found.

      The LeastSquaresOptimizer.Optimum object contains detailed elements (covariance matrix, estimated parameters standard deviation, weighted Jacobian, RMS, χ², residuals and more).

      Beware that the returned object is the raw view from the underlying mathematical library. At this raw level, parameters have normalized values whereas the space flight parameters have physical values with their units. So there are scaling factors to apply when using these elements.

      Returns:
      optimum found after last call to estimate()

    • getPhysicalCovariances

      public RealMatrix getPhysicalCovariances(double threshold)
      Get the covariances matrix in space flight dynamics physical units.

      This method retrieve the covariances from the [@link optimum and applies the scaling factors to it in order to convert it from raw normalized values back to physical values.

      Parameters:
      threshold - threshold to identify matrix singularity
      Returns:
      covariances matrix in space flight dynamics physical units
      Since:
      9.1

    • getIterationsCount

      public int getIterationsCount()
      Get the number of iterations used for last estimation.
      Returns:
      number of iterations used for last estimation
      See Also:

    • getEvaluationsCount

      public int getEvaluationsCount()
      Get the number of evaluations used for last estimation.
      Returns:
      number of evaluations used for last estimation
      See Also: