ParameterDriver.java

  1. /* Copyright 2002-2017 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.utils;

  19. import java.util.ArrayList;
  20. import java.util.List;

  22. import org.hipparchus.util.FastMath;
  23. import org.hipparchus.util.Precision;
  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.errors.OrekitMessages;
  26. import org.orekit.time.AbsoluteDate;


  29. /** Class allowing to drive the value of a parameter.
  30.  * <p>
  31.  * This class is typically used as a bridge between an estimation
  32.  * algorithm (typically orbit determination or optimizer) and an
  33.  * internal parameter in a physical model that needs to be tuned,
  34.  * or a bridge between a finite differences algorithm and an
  35.  * internal parameter in a physical model that needs to be slightly
  36.  * offset. The physical model will expose to the algorithm a
  37.  * set of instances of this class so the algorithm can call the
  38.  * {@link #setValue(double)} method to update the
  39.  * parameter value. Each time the value is set, the physical model
  40.  * will be notified as it will register a {@link ParameterObserver
  41.  * ParameterObserver} for this purpose.
  42.  * </p>
  43.  * <p>
  44.  * This design has two major goals. First, it allows an external
  45.  * algorithm to drive internal parameters almost anonymously, as it only
  46.  * needs to get a list of instances of this class, without knowing
  47.  * what they really drive. Second, it allows the physical model to
  48.  * not expose directly setters methods for its parameters. In order
  49.  * to be able to modify the parameter value, the algorithm
  50.  * <em>must</em> retrieve a parameter driver.
  51.  * </p>
  52.  * @see ParameterObserver
  53.  * @author Luc Maisonobe
  54.  * @since 8.0
  55.  */
  56. public class ParameterDriver {

  58.     /** Name of the parameter. */
  59.     private String name;

  61.     /** Reference value. */
  62.     private final double referenceValue;

  64.     /** Scaling factor. */
  65.     private final double scale;

  67.     /** Minimum value. */
  68.     private final double minValue;

  70.     /** Maximum value. */
  71.     private final double maxValue;

  73.     /** Reference date.
  74.      * @since 9.0
  75.      */
  76.     private AbsoluteDate referenceDate;

  78.     /** Current value. */
  79.     private double value;

  81.     /** Selection status.
  82.      * <p>
  83.      * Selection is used for estimated parameters in orbit determination,
  84.      * or to compute the Jacobian matrix in partial derivatives computation.
  85.      * </p>
  86.      */
  87.     private boolean selected;

  89.     /** Observers observing this driver. */
  90.     private final List<ParameterObserver> observers;

  92.     /** Simple constructor.
  93.      * <p>
  94.      * At construction, the parameter is configured as <em>not</em> selected,
  95.      * the reference date is set to {@code null} and the value is set to the
  96.      * {@code referenceValue}.
  97.      * </p>
  98.      * @param name name of the parameter
  99.      * @param referenceValue reference value of the parameter
  100.      * @param scale scaling factor to convert the parameters value to
  101.      * non-dimensional (typically set to the expected standard deviation of the
  102.      * parameter), it must be non-zero
  103.      * @param minValue minimum value
  104.      * @param maxValue maximum value
  105.      * @exception OrekitException if scale is too close to zero
  106.      */
  107.     public ParameterDriver(final String name, final double referenceValue,
  108.                            final double scale, final double minValue,
  109.                            final double maxValue)
  110.         throws OrekitException {
  111.         if (FastMath.abs(scale) <= Precision.SAFE_MIN) {
  112.             throw new OrekitException(OrekitMessages.TOO_SMALL_SCALE_FOR_PARAMETER,
  113.                                       name, scale);
  114.         }
  115.         this.name           = name;
  116.         this.referenceValue = referenceValue;
  117.         this.scale          = scale;
  118.         this.minValue       = minValue;
  119.         this.maxValue       = maxValue;
  120.         this.referenceDate  = null;
  121.         this.value          = referenceValue;
  122.         this.selected       = false;
  123.         this.observers      = new ArrayList<ParameterObserver>();
  124.     }


  127.     /** Add an observer for this driver.
  128.      * <p>
  129.      * The observer {@link ParameterObserver#valueChanged(double, ParameterDriver)
  130.      * valueChanged} method is called once automatically when the
  131.      * observer is added, and then called at each value change.
  132.      * </p>
  133.      * @param observer observer to add
  134.      * @exception OrekitException if the observer triggers one
  135.      * while being updated
  136.      */
  137.     public void addObserver(final ParameterObserver observer)
  138.         throws OrekitException {
  139.         observers.add(observer);
  140.         observer.valueChanged(getValue(), this);
  141.     }

  143.     /** Change the name of this parameter driver.
  144.      * @param name new name
  145.      */
  146.     public void setName(final String name) {
  147.         final String previousName = this.name;
  148.         this.name = name;
  149.         for (final ParameterObserver observer : observers) {
  150.             observer.nameChanged(previousName, this);
  151.         }
  152.     }

  154.     /** Get name.
  155.      * @return name
  156.      */
  157.     public String getName() {
  158.         return name;
  159.     }

  161.     /** Get reference parameter value.
  162.      * @return reference parameter value
  163.      */
  164.     public double getReferenceValue() {
  165.         return referenceValue;
  166.     }

  168.     /** Get minimum parameter value.
  169.      * @return minimum parameter value
  170.      */
  171.     public double getMinValue() {
  172.         return minValue;
  173.     }

  175.     /** Get maximum parameter value.
  176.      * @return maximum parameter value
  177.      */
  178.     public double getMaxValue() {
  179.         return maxValue;
  180.     }

  182.     /** Get scale.
  183.      * @return scale
  184.      */
  185.     public double getScale() {
  186.         return scale;
  187.     }

  189.     /** Get normalized value.
  190.      * <p>
  191.      * The normalized value is a non-dimensional value
  192.      * suitable for use as part of a vector in an optimization
  193.      * process. It is computed as {@code (current - reference)/scale}.
  194.      * </p>
  195.      * @return normalized value
  196.      */
  197.     public double getNormalizedValue() {
  198.         return (value - referenceValue) / scale;
  199.     }

  201.     /** Set normalized value.
  202.      * <p>
  203.      * The normalized value is a non-dimensional value
  204.      * suitable for use as part of a vector in an optimization
  205.      * process. It is computed as {@code (current - reference)/scale}.
  206.      * </p>
  207.      * @param normalized value
  208.      * @exception OrekitException if an observer throws one
  209.      */
  210.     public void setNormalizedValue(final double normalized) throws OrekitException {
  211.         setValue(referenceValue + scale * normalized);
  212.     }

  214.     /** Get current reference date.
  215.      * @return current reference date (null if it was never set)
  216.      * @since 9.0
  217.      */
  218.     public AbsoluteDate getReferenceDate() {
  219.         return referenceDate;
  220.     }

  222.     /** Set reference date.
  223.      * @param newReferenceDate new reference date
  224.      * @since 9.0
  225.      */
  226.     public void setReferenceDate(final AbsoluteDate newReferenceDate) {
  227.         final AbsoluteDate previousReferenceDate = getReferenceDate();
  228.         referenceDate = newReferenceDate;
  229.         for (final ParameterObserver observer : observers) {
  230.             observer.referenceDateChanged(previousReferenceDate, this);
  231.         }
  232.     }

  234.     /** Get current parameter value.
  235.      * @return current parameter value
  236.      */
  237.     public double getValue() {
  238.         return value;
  239.     }

  241.     /** Set parameter value.
  242.      * <p>
  243.      * If {@code newValue} is below {@link #getMinValue()}, it will
  244.      * be silently to {@link #getMinValue()}. If {@code newValue} is
  245.      * above {@link #getMaxValue()}, it will be silently to {@link
  246.      * #getMaxValue()}.
  247.      * </p>
  248.      * @param newValue new value
  249.      * @exception OrekitException if an observer throws one
  250.      */
  251.     public void setValue(final double newValue) throws OrekitException {
  252.         final double previousValue = getValue();
  253.         value = FastMath.max(minValue, FastMath.min(maxValue, newValue));
  254.         for (final ParameterObserver observer : observers) {
  255.             observer.valueChanged(previousValue, this);
  256.         }
  257.     }

  259.     /** Configure a parameter selection status.
  260.      * <p>
  261.      * Selection is used for estimated parameters in orbit determination,
  262.      * or to compute the Jacobian matrix in partial derivatives computation.
  263.      * </p>
  264.      * @param selected if true the parameter is selected,
  265.      * otherwise it will be fixed
  266.      */
  267.     public void setSelected(final boolean selected) {
  268.         final boolean previousSelection = isSelected();
  269.         this.selected = selected;
  270.         for (final ParameterObserver observer : observers) {
  271.             observer.selectionChanged(previousSelection, this);
  272.         }
  273.     }

  275.     /** Check if parameter is selected.
  276.      * <p>
  277.      * Selection is used for estimated parameters in orbit determination,
  278.      * or to compute the Jacobian matrix in partial derivatives computation.
  279.      * </p>
  280.      * @return true if parameter is selected, false if it is not
  281.      */
  282.     public boolean isSelected() {
  283.         return selected;
  284.     }

  286.     /** Get a text representation of the parameter.
  287.      * @return text representation of the parameter, in the form name = value.
  288.      */
  289.     public String toString() {
  290.         return name + " = " + value;
  291.     }

  293. }
Created with JaCoCo 0.7.9.201702052155