View Javadoc
1   /*
2    * Licensed to the Hipparchus project under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The Hipparchus project 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    *      https://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  
18  package org.hipparchus.ode;
19  
20  import org.hipparchus.CalculusFieldElement;
21  import org.hipparchus.exception.MathIllegalArgumentException;
22  import org.hipparchus.exception.MathIllegalStateException;
23  
24  /**
25   * This interface allows users to add secondary differential equations to a primary
26   * set of differential equations.
27   * <p>
28   * In some cases users may need to integrate some problem-specific equations along
29   * with a primary set of differential equations. One example is optimal control where
30   * adjoined parameters linked to the minimized Hamiltonian must be integrated.
31   * </p>
32   * <p>
33   * This interface allows users to add such equations to a primary set of {@link
34   * FieldOrdinaryDifferentialEquation first order differential equations}
35   * thanks to the {@link FieldExpandableODE#addSecondaryEquations(FieldSecondaryODE)}
36   * method.
37   * </p>
38   * @see FieldOrdinaryDifferentialEquation
39   * @see FieldExpandableODE
40   * @param <T> the type of the field elements
41   */
42  public interface FieldSecondaryODE<T extends CalculusFieldElement<T>> {
43  
44      /** Get the dimension of the secondary state parameters.
45       * @return dimension of the secondary state parameters
46       */
47      int getDimension();
48  
49      /** Initialize equations at the start of an ODE integration.
50       * <p>
51       * This method is called once at the start of the integration. It
52       * may be used by the equations to initialize some internal data
53       * if needed.
54       * </p>
55       * <p>
56       * The default implementation does nothing.
57       * </p>
58       * @param t0 value of the independent <I>time</I> variable at integration start
59       * @param primary0 array containing the value of the primary state vector at integration start
60       * @param secondary0 array containing the value of the secondary state vector at integration start
61       * @param finalTime target time for the integration
62       */
63      default void init(T t0, T[] primary0, T[] secondary0, T finalTime) {
64          // nothing by default
65      }
66  
67      /** Compute the derivatives related to the secondary state parameters.
68       * <p>
69       * In some cases, additional equations can require to change the derivatives
70       * of the primary state (i.e. the content of the {@code primaryDot} array).
71       * One use case is optimal control, when the secondary equations handle co-state,
72       * which changes control, and the control changes the primary state. In this
73       * case, the primary and secondary equations are not really independent from each
74       * other, so if possible it would be better to put state and co-state and their
75       * equations all in the primary equations. As this is not always possible, this
76       * method explicitly <em>allows</em> to modify the content of the {@code primaryDot}
77       * array. This array will be used to evolve the primary state only <em>after</em>
78       * all secondary equations have computed their derivatives, hence allowing this
79       * side effect.
80       * </p>
81       * @param t current value of the independent <I>time</I> variable
82       * @param primary array containing the current value of the primary state vector
83       * @param primaryDot array containing the derivative of the primary state vector
84       * (the method is allowed to change the derivatives here, when the additional
85       * equations do have an effect on the primary equations)
86       * @param secondary array containing the current value of the secondary state vector
87       * @return derivative of the secondary state vector
88       * @exception MathIllegalStateException if the number of functions evaluations is exceeded
89       * @exception MathIllegalArgumentException if arrays dimensions do not match equations settings
90       */
91      T[] computeDerivatives(T t, T[] primary, T[] primaryDot, T[] secondary)
92          throws MathIllegalArgumentException, MathIllegalStateException;
93  
94  }