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 package org.hipparchus.analysis.differentiation;
18
19 import org.hipparchus.CalculusFieldElement;
20 import org.hipparchus.exception.MathIllegalArgumentException;
21 import org.hipparchus.util.FastMath;
22
23 /** Interface representing both the value and the differentials of a function.
24 * @param <T> the type of the field elements
25 * @since 1.7
26 */
27 public interface Derivative<T extends CalculusFieldElement<T>> extends CalculusFieldElement<T>, DifferentialAlgebra {
28
29 /** {@inheritDoc} */
30 @Override
31 default double getReal() {
32 return getValue();
33 }
34
35 /** Get the value part of the function.
36 * @return value part of the value of the function
37 */
38 double getValue();
39
40 /** Create a new object with new value (zeroth-order derivative, as passed as input)
41 * and same derivatives of order one and above.
42 * <p>
43 * This default implementation is there so that no API gets broken
44 * by the next release, which is not a major one. Custom inheritors
45 * should probably overwrite it.
46 * </p>
47 * @param value zeroth-order derivative of new represented function
48 * @return new object with changed value
49 * @since 3.1
50 */
51 default T withValue(double value) {
52 return add(newInstance(value - getValue()));
53 }
54
55 /** Get a partial derivative.
56 * @param orders derivation orders with respect to each variable (if all orders are 0,
57 * the value is returned)
58 * @return partial derivative
59 * @see #getValue()
60 * @exception MathIllegalArgumentException if the numbers of variables does not
61 * match the instance
62 * @exception MathIllegalArgumentException if sum of derivation orders is larger
63 * than the instance limits
64 */
65 double getPartialDerivative(int ... orders)
66 throws MathIllegalArgumentException;
67
68 /** {@inheritDoc} */
69 @Override
70 default T add(double a) {
71 return withValue(getValue() + a);
72 }
73
74 /** {@inheritDoc} */
75 @Override
76 default T subtract(double a) {
77 return withValue(getValue() - a);
78 }
79
80 /** Compute composition of the instance by a univariate function.
81 * @param f array of value and derivatives of the function at
82 * the current point (i.e. [f({@link #getValue()}),
83 * f'({@link #getValue()}), f''({@link #getValue()})...]).
84 * @return f(this)
85 * @exception MathIllegalArgumentException if the number of derivatives
86 * in the array is not equal to {@link #getOrder() order} + 1
87 */
88 T compose(double... f)
89 throws MathIllegalArgumentException;
90
91 /** {@inheritDoc} */
92 @Override
93 default T log10() {
94 return log().divide(FastMath.log(10.));
95 }
96
97 /** {@inheritDoc} */
98 @Override
99 default T pow(T e) {
100 return log().multiply(e).exp();
101 }
102
103 /** {@inheritDoc} */
104 @Override
105 default T cosh() {
106 return (exp().add(negate().exp())).divide(2);
107 }
108
109 /** {@inheritDoc} */
110 @Override
111 default T sinh() {
112 return (exp().subtract(negate().exp())).divide(2);
113 }
114
115 /** {@inheritDoc} */
116 @Override
117 default T acos() {
118 return asin().negate().add(getPi().divide(2));
119 }
120
121 /** {@inheritDoc} */
122 @Override
123 default int getExponent() {
124 return FastMath.getExponent(getValue());
125 }
126
127 /** {@inheritDoc} */
128 @Override
129 default T remainder(double a) {
130 return withValue(FastMath.IEEEremainder(getValue(), a));
131 }
132 }