ParameterDriver.java

/* Copyright 2002-2020 CS GROUP
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.orekit.utils;

import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.Map;

import org.hipparchus.analysis.differentiation.DSFactory;
import org.hipparchus.analysis.differentiation.DerivativeStructure;
import org.hipparchus.analysis.differentiation.Gradient;
import org.hipparchus.util.FastMath;
import org.hipparchus.util.Precision;
import org.orekit.errors.OrekitException;
import org.orekit.errors.OrekitMessages;
import org.orekit.time.AbsoluteDate;


/** Class allowing to drive the value of a parameter.
 * <p>
 * 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
 * {@link #setValue(double)} method to update the
 * parameter value. Each time the value is set, the physical model
 * will be notified as it will register a {@link ParameterObserver
 * ParameterObserver} for this purpose.
 * </p>
 * <p>
 * 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
 * <em>must</em> retrieve a parameter driver.
 * </p>
 * @see ParameterObserver
 * @author Luc Maisonobe
 * @since 8.0
 */
public class ParameterDriver {

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

    /** Reference value. */
    private double referenceValue;

    /** Scaling factor. */
    private double scale;

    /** Minimum value. */
    private double minValue;

    /** Maximum value. */
    private double maxValue;

    /** Reference date.
     * @since 9.0
     */
    private AbsoluteDate referenceDate;

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

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

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

    /** Simple constructor.
     * <p>
     * At construction, the parameter is configured as <em>not</em> selected,
     * the reference date is set to {@code null} and the value is set to the
     * {@code referenceValue}.
     * </p>
     * @param name name of the parameter
     * @param referenceValue reference value of the parameter
     * @param 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
     * @param minValue minimum value
     * @param maxValue maximum value
     */
    public ParameterDriver(final String name, final double referenceValue,
                           final double scale, final double minValue,
                           final double maxValue) {
        if (FastMath.abs(scale) <= Precision.SAFE_MIN) {
            throw new OrekitException(OrekitMessages.TOO_SMALL_SCALE_FOR_PARAMETER,
                                      name, scale);
        }
        this.name           = name;
        this.referenceValue = referenceValue;
        this.scale          = scale;
        this.minValue       = minValue;
        this.maxValue       = maxValue;
        this.referenceDate  = null;
        this.value          = referenceValue;
        this.selected       = false;
        this.observers      = new ArrayList<>();
    }


    /** Add an observer for this driver.
     * <p>
     * The observer {@link ParameterObserver#valueChanged(double, ParameterDriver)
     * valueChanged} method is called once automatically when the
     * observer is added, and then called at each value change.
     * </p>
     * @param observer observer to add
          * while being updated
     */
    public void addObserver(final ParameterObserver observer) {
        observers.add(observer);
        observer.valueChanged(getValue(), this);
    }

    /** Remove an observer.
     * @param observer observer to remove
     * @since 9.1
     */
    public void removeObserver(final ParameterObserver observer) {
        for (final Iterator<ParameterObserver> iterator = observers.iterator(); iterator.hasNext();) {
            if (iterator.next() == observer) {
                iterator.remove();
                return;
            }
        }
    }

    /** Replace an observer.
     * @param oldObserver observer to replace
     * @param newObserver new observer to use
     * @since 10.1
     */
    public void replaceObserver(final ParameterObserver oldObserver, final ParameterObserver newObserver) {
        for (int i = 0; i < observers.size(); ++i) {
            if (observers.get(i) == oldObserver) {
                observers.set(i, newObserver);
            }
        }
    }

    /** Get the observers for this driver.
     * @return an unmodifiable view of the observers for this driver
     * @since 9.1
     */
    public List<ParameterObserver> getObservers() {
        return Collections.unmodifiableList(observers);
    }

    /** Change the name of this parameter driver.
     * @param name new name
     */
    public void setName(final String name) {
        final String previousName = this.name;
        this.name = name;
        for (final ParameterObserver observer : observers) {
            observer.nameChanged(previousName, this);
        }
    }

    /** Get name.
     * @return name
     */
    public String getName() {
        return name;
    }

    /** Get reference parameter value.
     * @return reference parameter value
     */
    public double getReferenceValue() {
        return referenceValue;
    }

    /** Set reference parameter value.
     * @since 9.3
     * @param referenceValue the reference value to set.
     */
    public void setReferenceValue(final double referenceValue) {
        final double previousReferenceValue = this.referenceValue;
        this.referenceValue = referenceValue;
        for (final ParameterObserver observer : observers) {
            observer.referenceValueChanged(previousReferenceValue, this);
        }
    }

    /** Get minimum parameter value.
     * @return minimum parameter value
     */
    public double getMinValue() {
        return minValue;
    }

    /** Set minimum parameter value.
     * @since 9.3
     * @param minValue the minimum value to set.
     */
    public void setMinValue(final double minValue) {
        final double previousMinValue = this.minValue;
        this.minValue = minValue;
        for (final ParameterObserver observer : observers) {
            observer.minValueChanged(previousMinValue, this);
        }
        // Check if current value is not out of min/max range
        setValue(value);
    }

    /** Get maximum parameter value.
     * @return maximum parameter value
     */
    public double getMaxValue() {
        return maxValue;
    }

    /** Set maximum parameter value.
     * @since 9.3
     * @param maxValue the maximum value to set.
     */
    public void setMaxValue(final double maxValue) {
        final double previousMaxValue = this.maxValue;
        this.maxValue = maxValue;
        for (final ParameterObserver observer : observers) {
            observer.maxValueChanged(previousMaxValue, this);
        }
        // Check if current value is not out of min/max range
        setValue(value);
    }

    /** Get scale.
     * @return scale
     */
    public double getScale() {
        return scale;
    }

    /** Set scale.
     * @since 9.3
     * @param scale the scale to set.
     */
    public void setScale(final double scale) {
        final double previousScale = this.scale;
        this.scale = scale;
        for (final ParameterObserver observer : observers) {
            observer.scaleChanged(previousScale, this);
        }
    }

    /** Get normalized value.
     * <p>
     * The normalized value is a non-dimensional value
     * suitable for use as part of a vector in an optimization
     * process. It is computed as {@code (current - reference)/scale}.
     * </p>
     * @return normalized value
     */
    public double getNormalizedValue() {
        return (value - referenceValue) / scale;
    }

    /** Set normalized value.
     * <p>
     * The normalized value is a non-dimensional value
     * suitable for use as part of a vector in an optimization
     * process. It is computed as {@code (current - reference)/scale}.
     * </p>
     * @param normalized value
     */
    public void setNormalizedValue(final double normalized) {
        setValue(referenceValue + scale * normalized);
    }

    /** Get current reference date.
     * @return current reference date (null if it was never set)
     * @since 9.0
     */
    public AbsoluteDate getReferenceDate() {
        return referenceDate;
    }

    /** Set reference date.
     * @param newReferenceDate new reference date
     * @since 9.0
     */
    public void setReferenceDate(final AbsoluteDate newReferenceDate) {
        final AbsoluteDate previousReferenceDate = getReferenceDate();
        referenceDate = newReferenceDate;
        for (final ParameterObserver observer : observers) {
            observer.referenceDateChanged(previousReferenceDate, this);
        }
    }

    /** Get current parameter value.
     * @return current parameter value
     */
    public double getValue() {
        return value;
    }

    /** Get the value as a derivative structure.
     * @param factory factory for the derivatives
     * @param indices indices of the differentiation parameters in derivatives computations
     * @return value with derivatives
     * @since 9.3
     * @deprecated as of 10.2, replaced by {@link #getValue(int, Map)}
     */
    @Deprecated
    public DerivativeStructure getValue(final DSFactory factory, final Map<String, Integer> indices) {
        final Integer index = indices.get(name);
        return (index == null) ? factory.constant(value) : factory.variable(index, value);
    }

    /** Get the value as a gradient.
     * @param freeParameters total number of free parameters in the gradient
     * @param indices indices of the differentiation parameters in derivatives computations
     * @return value with derivatives
     * @since 10.2
     */
    public Gradient getValue(final int freeParameters, final Map<String, Integer> indices) {
        final Integer index = indices.get(name);
        return (index == null) ? Gradient.constant(freeParameters, value) : Gradient.variable(freeParameters, index, value);
    }

    /** Set parameter value.
     * <p>
     * If {@code newValue} is below {@link #getMinValue()}, it will
     * be silently set to {@link #getMinValue()}. If {@code newValue} is
     * above {@link #getMaxValue()}, it will be silently set to {@link
     * #getMaxValue()}.
     * </p>
     * @param newValue new value
     */
    public void setValue(final double newValue) {
        final double previousValue = getValue();
        value = FastMath.max(minValue, FastMath.min(maxValue, newValue));
        for (final ParameterObserver observer : observers) {
            observer.valueChanged(previousValue, this);
        }
    }

    /** Configure a parameter selection status.
     * <p>
     * Selection is used for estimated parameters in orbit determination,
     * or to compute the Jacobian matrix in partial derivatives computation.
     * </p>
     * @param selected if true the parameter is selected,
     * otherwise it will be fixed
     */
    public void setSelected(final boolean selected) {
        final boolean previousSelection = isSelected();
        this.selected = selected;
        for (final ParameterObserver observer : observers) {
            observer.selectionChanged(previousSelection, this);
        }
    }

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

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

}