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 <S> the type of the field elements
25 * @param <T> the type of the function derivative
26 * @see Derivative
27 * @since 1.7
28 */
29 public interface FieldDerivative<S extends CalculusFieldElement<S>, T extends FieldDerivative<S, T>>
30 extends CalculusFieldElement<T>, DifferentialAlgebra {
31
32 /** Get the value part of the function.
33 * @return value part of the value of the function
34 */
35 S getValue();
36
37 /** Get a partial derivative.
38 * @param orders derivation orders with respect to each variable (if all orders are 0,
39 * the value is returned)
40 * @return partial derivative
41 * @see #getValue()
42 * @exception MathIllegalArgumentException if the numbers of variables does not
43 * match the instance
44 * @exception MathIllegalArgumentException if sum of derivation orders is larger
45 * than the instance limits
46 */
47 S getPartialDerivative(int ... orders)
48 throws MathIllegalArgumentException;
49
50 /** {@inheritDoc} */
51 @Override
52 default double getReal() {
53 return getValue().getReal();
54 }
55
56 /** Create an instance corresponding to a constant Field value.
57 * <p>
58 * This default implementation is there so that no API gets broken
59 * by the next release, which is not a major one. Custom inheritors
60 * should probably overwrite it.
61 * </p>
62 * @param value constant value
63 * @return instance corresponding to a constant Field value
64 * @since 3.1
65 */
66 default T newInstance(S value) {
67 return newInstance(value.getReal());
68 }
69
70 /** Create a new object with new value (zeroth-order derivative, as passed as input)
71 * and same derivatives of order one and above.
72 * <p>
73 * This default implementation is there so that no API gets broken
74 * by the next release, which is not a major one. Custom inheritors
75 * should probably overwrite it.
76 * </p>
77 * @param value zeroth-order derivative of new represented function
78 * @return new object with changed value
79 * @since 3.1
80 */
81 default T withValue(S value) {
82 return add(newInstance(value.subtract(getValue())));
83 }
84
85 /** '+' operator.
86 * @param a right hand side parameter of the operator
87 * @return this+a
88 * @since 3.1
89 */
90 default T add(S a) {
91 return withValue(getValue().add(a));
92 }
93
94 /** '-' operator.
95 * @param a right hand side parameter of the operator
96 * @return this-a
97 * @since 3.1
98 */
99 default T subtract(S a) {
100 return withValue(getValue().subtract(a));
101 }
102
103 /** {@inheritDoc} */
104 @Override
105 default T log10() {
106 return log().divide(FastMath.log(10.));
107 }
108
109 /** {@inheritDoc} */
110 @Override
111 default T pow(T e) {
112 return log().multiply(e).exp();
113 }
114
115 /** {@inheritDoc} */
116 @Override
117 default T cosh() {
118 return (exp().add(negate().exp())).divide(2);
119 }
120
121 /** {@inheritDoc} */
122 @Override
123 default T sinh() {
124 return (exp().subtract(negate().exp())).divide(2);
125 }
126
127 /** {@inheritDoc} */
128 @Override
129 default T acos() {
130 return asin().negate().add(getPi().divide(2));
131 }
132
133 /** {@inheritDoc} */
134 @Override
135 default T ceil() {
136 return newInstance(getValue().ceil());
137 }
138
139 /** {@inheritDoc} */
140 @Override
141 default T floor() {
142 return newInstance(getValue().floor());
143 }
144
145 /** {@inheritDoc} */
146 @Override
147 default T rint() {
148 return newInstance(getValue().rint());
149 }
150
151 /** {@inheritDoc} */
152 @Override
153 default T ulp() {
154 return newInstance(getValue().ulp());
155 }
156
157 /** {@inheritDoc} */
158 @Override
159 default T sign() {
160 return newInstance(getValue().sign());
161 }
162
163 /** {@inheritDoc} */
164 @Override
165 default int getExponent() {
166 return getValue().getExponent();
167 }
168
169 }