/* Copyright 2002-2026 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.drivers;
  
  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.Gradient;
  import org.hipparchus.exception.LocalizedCoreFormats;
  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;
  import org.orekit.time.TimeInterval;
  
  /** 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. 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.
   * </p>
   * <p>
   * Any object can be notified when any of value, name, selection status… are changed.
   * This is done by {@link #addObserver(ParameterObserver)}  registering} a
   * {@link ParameterObserver ParameterObserver} to the parameter driver.
   * <p>
   * This design has two major goals. First, it allows an external algorithm to drive
   * internal parameters blindly, 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>
   * <p>
   * As of versions 12.X and 13.X, it was possible to set up time-dependent values
   * within a single {@code ParameterDriver}. This feature has been replaced by
   * {@link ParameterDriversSequence} as of 14.0, which is simpler and also allows
   * finer selection, making it possible to select only a subset of the parameters
   * along a timeline. Starting with version 14.0, {@code ParameterDriver} instances
   * only hold one value, which can have a restricted validity range.
   * </p>
   * @see ParameterObserver
   * @author Luc Maisonobe
   * @author Melina Vanel
   * @since 8.0
   */
  public class ParameterDriver {
  
      /** Name of the parameter. */
      private String name;
  
      /** Reference value. */
      private double referenceValue;
  
      /** Scaling factor. */
      private double scale;
  
      /** Current value.
       * @since 14.0
       */
      private double value;
  
      /** Minimum value. */
      private double minValue;
  
      /** Maximum value. */
      private double maxValue;
  
      /** Reference date.
       * @since 9.0
       */
      private AbsoluteDate referenceDate;
  
      /** Validity interval.
       * @since 14.0
       */
      private TimeInterval validity;
  
      /** 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},
      * 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 allowed
      * @param maxValue       maximum value allowed
      * @param validity       validity interval
      */
     public ParameterDriver(final String name,
                            final double referenceValue, final double scale,
                            final double minValue, final double maxValue,
                            final TimeInterval validity) {
 
         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.value          = referenceValue;
         this.minValue       = minValue;
         this.maxValue       = maxValue;
         this.validity       = validity;
         this.referenceDate  = null;
         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
      */
     public void addObserver(final ParameterObserver observer) {
         observers.add(observer);
     }
 
     /** 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);
     }
 
     /** Get parameter driver general name.
      * @return name
      */
     public String getName() {
         return name;
     }
 
     /** Change the general 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 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) {
 
         // safety check
         if (minValue > maxValue) {
             throw new OrekitException(LocalizedCoreFormats.NUMBER_TOO_LARGE, minValue, maxValue);
         }
 
         if (value < minValue) {
             // clip value to minimum
             setValue(minValue);
         }
 
         final double previousMinValue = this.minValue;
         this.minValue = minValue;
         for (final ParameterObserver observer : observers) {
             observer.minValueChanged(previousMinValue, this);
         }
 
     }
 
     /** 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) {
 
         // safety check
         if (maxValue < minValue) {
             throw new OrekitException(LocalizedCoreFormats.NUMBER_TOO_SMALL, maxValue, minValue);
         }
 
         if (value > maxValue) {
             // clip value to maximum
             setValue(maxValue);
         }
 
         final double previousMaxValue = this.maxValue;
         this.maxValue = maxValue;
         for (final ParameterObserver observer : observers) {
             observer.maxValueChanged(previousMaxValue, this);
         }
 
     }
 
     /** 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 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(getName());
         return (index == null) ?
                Gradient.constant(freeParameters, getValue()) :
                Gradient.variable(freeParameters, index, getValue());
     }
 
     /** 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 to set
      */
     public void setValue(final double newValue) {
         final double previousValue = value;
         value = FastMath.max(minValue, FastMath.min(maxValue, newValue));
         for (final ParameterObserver observer : observers) {
             observer.valueChanged(previousValue, this);
         }
     }
 
     /** Get the validity interval.
      * @return validity interval
      * @since 14.0
      */
     public TimeInterval getValidity() {
         return validity;
     }
 
     /** Set the validity interval.
      * @param validity validity interval
      * @since 14.0
      */
     public void setValidity(final TimeInterval validity) {
         final TimeInterval previousValidity = getValidity();
         this.validity = validity;
         for (final ParameterObserver observer : observers) {
             observer.validityChanged(previousValidity, 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;
     }
 
 }