001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.math3; 018 019import org.apache.commons.math3.exception.DimensionMismatchException; 020 021/** 022 * Interface representing a <a href="http://mathworld.wolfram.com/RealNumber.html">real</a> 023 * <a href="http://mathworld.wolfram.com/Field.html">field</a>. 024 * @param <T> the type of the field elements 025 * @see FieldElement 026 * @since 3.2 027 */ 028public interface RealFieldElement<T> extends FieldElement<T> { 029 030 /** Get the real value of the number. 031 * @return real value 032 */ 033 double getReal(); 034 035 /** '+' operator. 036 * @param a right hand side parameter of the operator 037 * @return this+a 038 */ 039 T add(double a); 040 041 /** '-' operator. 042 * @param a right hand side parameter of the operator 043 * @return this-a 044 */ 045 T subtract(double a); 046 047 /** '×' operator. 048 * @param a right hand side parameter of the operator 049 * @return this×a 050 */ 051 T multiply(double a); 052 053 /** '÷' operator. 054 * @param a right hand side parameter of the operator 055 * @return this÷a 056 */ 057 T divide(double a); 058 059 /** IEEE remainder operator. 060 * @param a right hand side parameter of the operator 061 * @return this - n × a where n is the closest integer to this/a 062 * (the even integer is chosen for n if this/a is halfway between two integers) 063 */ 064 T remainder(double a); 065 066 /** IEEE remainder operator. 067 * @param a right hand side parameter of the operator 068 * @return this - n × a where n is the closest integer to this/a 069 * (the even integer is chosen for n if this/a is halfway between two integers) 070 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 071 */ 072 T remainder(T a) 073 throws DimensionMismatchException; 074 075 /** absolute value. 076 * @return abs(this) 077 */ 078 T abs(); 079 080 /** Get the smallest whole number larger than instance. 081 * @return ceil(this) 082 */ 083 T ceil(); 084 085 /** Get the largest whole number smaller than instance. 086 * @return floor(this) 087 */ 088 T floor(); 089 090 /** Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers. 091 * @return a double number r such that r is an integer r - 0.5 ≤ this ≤ r + 0.5 092 */ 093 T rint(); 094 095 /** Get the closest long to instance value. 096 * @return closest long to {@link #getReal()} 097 */ 098 long round(); 099 100 /** Compute the signum of the instance. 101 * The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise 102 * @return -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a 103 */ 104 T signum(); 105 106 /** 107 * Returns the instance with the sign of the argument. 108 * A NaN {@code sign} argument is treated as positive. 109 * 110 * @param sign the sign for the returned value 111 * @return the instance with the same sign as the {@code sign} argument 112 */ 113 T copySign(T sign); 114 115 /** 116 * Returns the instance with the sign of the argument. 117 * A NaN {@code sign} argument is treated as positive. 118 * 119 * @param sign the sign for the returned value 120 * @return the instance with the same sign as the {@code sign} argument 121 */ 122 T copySign(double sign); 123 124 /** 125 * Multiply the instance by a power of 2. 126 * @param n power of 2 127 * @return this × 2<sup>n</sup> 128 */ 129 T scalb(int n); 130 131 /** 132 * Returns the hypotenuse of a triangle with sides {@code this} and {@code y} 133 * - sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>) 134 * avoiding intermediate overflow or underflow. 135 * 136 * <ul> 137 * <li> If either argument is infinite, then the result is positive infinity.</li> 138 * <li> else, if either argument is NaN then the result is NaN.</li> 139 * </ul> 140 * 141 * @param y a value 142 * @return sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>) 143 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 144 */ 145 T hypot(T y) 146 throws DimensionMismatchException; 147 148 /** {@inheritDoc} */ 149 T reciprocal(); 150 151 /** Square root. 152 * @return square root of the instance 153 */ 154 T sqrt(); 155 156 /** Cubic root. 157 * @return cubic root of the instance 158 */ 159 T cbrt(); 160 161 /** N<sup>th</sup> root. 162 * @param n order of the root 163 * @return n<sup>th</sup> root of the instance 164 */ 165 T rootN(int n); 166 167 /** Power operation. 168 * @param p power to apply 169 * @return this<sup>p</sup> 170 */ 171 T pow(double p); 172 173 /** Integer power operation. 174 * @param n power to apply 175 * @return this<sup>n</sup> 176 */ 177 T pow(int n); 178 179 /** Power operation. 180 * @param e exponent 181 * @return this<sup>e</sup> 182 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 183 */ 184 T pow(T e) 185 throws DimensionMismatchException; 186 187 /** Exponential. 188 * @return exponential of the instance 189 */ 190 T exp(); 191 192 /** Exponential minus 1. 193 * @return exponential minus one of the instance 194 */ 195 T expm1(); 196 197 /** Natural logarithm. 198 * @return logarithm of the instance 199 */ 200 T log(); 201 202 /** Shifted natural logarithm. 203 * @return logarithm of one plus the instance 204 */ 205 T log1p(); 206 207// TODO: add this method in 4.0, as it is not possible to do it in 3.2 208// due to incompatibility of the return type in the Dfp class 209// /** Base 10 logarithm. 210// * @return base 10 logarithm of the instance 211// */ 212// T log10(); 213 214 /** Cosine operation. 215 * @return cos(this) 216 */ 217 T cos(); 218 219 /** Sine operation. 220 * @return sin(this) 221 */ 222 T sin(); 223 224 /** Tangent operation. 225 * @return tan(this) 226 */ 227 T tan(); 228 229 /** Arc cosine operation. 230 * @return acos(this) 231 */ 232 T acos(); 233 234 /** Arc sine operation. 235 * @return asin(this) 236 */ 237 T asin(); 238 239 /** Arc tangent operation. 240 * @return atan(this) 241 */ 242 T atan(); 243 244 /** Two arguments arc tangent operation. 245 * @param x second argument of the arc tangent 246 * @return atan2(this, x) 247 * @exception DimensionMismatchException if number of free parameters or orders are inconsistent 248 */ 249 T atan2(T x) 250 throws DimensionMismatchException; 251 252 /** Hyperbolic cosine operation. 253 * @return cosh(this) 254 */ 255 T cosh(); 256 257 /** Hyperbolic sine operation. 258 * @return sinh(this) 259 */ 260 T sinh(); 261 262 /** Hyperbolic tangent operation. 263 * @return tanh(this) 264 */ 265 T tanh(); 266 267 /** Inverse hyperbolic cosine operation. 268 * @return acosh(this) 269 */ 270 T acosh(); 271 272 /** Inverse hyperbolic sine operation. 273 * @return asin(this) 274 */ 275 T asinh(); 276 277 /** Inverse hyperbolic tangent operation. 278 * @return atanh(this) 279 */ 280 T atanh(); 281 282 /** 283 * Compute a linear combination. 284 * @param a Factors. 285 * @param b Factors. 286 * @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>. 287 * @throws DimensionMismatchException if arrays dimensions don't match 288 * @since 3.2 289 */ 290 T linearCombination(T[] a, T[] b) 291 throws DimensionMismatchException; 292 293 /** 294 * Compute a linear combination. 295 * @param a Factors. 296 * @param b Factors. 297 * @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>. 298 * @throws DimensionMismatchException if arrays dimensions don't match 299 * @since 3.2 300 */ 301 T linearCombination(double[] a, T[] b) 302 throws DimensionMismatchException; 303 304 /** 305 * Compute a linear combination. 306 * @param a1 first factor of the first term 307 * @param b1 second factor of the first term 308 * @param a2 first factor of the second term 309 * @param b2 second factor of the second term 310 * @return a<sub>1</sub>×b<sub>1</sub> + 311 * a<sub>2</sub>×b<sub>2</sub> 312 * @see #linearCombination(Object, Object, Object, Object, Object, Object) 313 * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object) 314 * @since 3.2 315 */ 316 T linearCombination(T a1, T b1, T a2, T b2); 317 318 /** 319 * Compute a linear combination. 320 * @param a1 first factor of the first term 321 * @param b1 second factor of the first term 322 * @param a2 first factor of the second term 323 * @param b2 second factor of the second term 324 * @return a<sub>1</sub>×b<sub>1</sub> + 325 * a<sub>2</sub>×b<sub>2</sub> 326 * @see #linearCombination(double, Object, double, Object, double, Object) 327 * @see #linearCombination(double, Object, double, Object, double, Object, double, Object) 328 * @since 3.2 329 */ 330 T linearCombination(double a1, T b1, double a2, T b2); 331 332 /** 333 * Compute a linear combination. 334 * @param a1 first factor of the first term 335 * @param b1 second factor of the first term 336 * @param a2 first factor of the second term 337 * @param b2 second factor of the second term 338 * @param a3 first factor of the third term 339 * @param b3 second factor of the third term 340 * @return a<sub>1</sub>×b<sub>1</sub> + 341 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> 342 * @see #linearCombination(Object, Object, Object, Object) 343 * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object) 344 * @since 3.2 345 */ 346 T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3); 347 348 /** 349 * Compute a linear combination. 350 * @param a1 first factor of the first term 351 * @param b1 second factor of the first term 352 * @param a2 first factor of the second term 353 * @param b2 second factor of the second term 354 * @param a3 first factor of the third term 355 * @param b3 second factor of the third term 356 * @return a<sub>1</sub>×b<sub>1</sub> + 357 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> 358 * @see #linearCombination(double, Object, double, Object) 359 * @see #linearCombination(double, Object, double, Object, double, Object, double, Object) 360 * @since 3.2 361 */ 362 T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3); 363 364 /** 365 * Compute a linear combination. 366 * @param a1 first factor of the first term 367 * @param b1 second factor of the first term 368 * @param a2 first factor of the second term 369 * @param b2 second factor of the second term 370 * @param a3 first factor of the third term 371 * @param b3 second factor of the third term 372 * @param a4 first factor of the third term 373 * @param b4 second factor of the third term 374 * @return a<sub>1</sub>×b<sub>1</sub> + 375 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> + 376 * a<sub>4</sub>×b<sub>4</sub> 377 * @see #linearCombination(Object, Object, Object, Object) 378 * @see #linearCombination(Object, Object, Object, Object, Object, Object) 379 * @since 3.2 380 */ 381 T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4); 382 383 /** 384 * Compute a linear combination. 385 * @param a1 first factor of the first term 386 * @param b1 second factor of the first term 387 * @param a2 first factor of the second term 388 * @param b2 second factor of the second term 389 * @param a3 first factor of the third term 390 * @param b3 second factor of the third term 391 * @param a4 first factor of the third term 392 * @param b4 second factor of the third term 393 * @return a<sub>1</sub>×b<sub>1</sub> + 394 * a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> + 395 * a<sub>4</sub>×b<sub>4</sub> 396 * @see #linearCombination(double, Object, double, Object) 397 * @see #linearCombination(double, Object, double, Object, double, Object) 398 * @since 3.2 399 */ 400 T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4); 401 402}