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