/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.math3;
import org.apache.commons.math3.exception.DimensionMismatchException;
/**
* Interface representing a <a href="http://mathworld.wolfram.com/RealNumber.html">real</a>
* <a href="http://mathworld.wolfram.com/Field.html">field</a>.
* @param <T> the type of the field elements
* @see FieldElement
* @since 3.2
*/
public interface RealFieldElement<T> extends FieldElement<T> {
/** Get the real value of the number.
* @return real value
*/
double getReal();
/** '+' operator.
* @param a right hand side parameter of the operator
* @return this+a
*/
T add(double a);
/** '-' operator.
* @param a right hand side parameter of the operator
* @return this-a
*/
T subtract(double a);
/** '×' operator.
* @param a right hand side parameter of the operator
* @return this×a
*/
T multiply(double a);
/** '÷' operator.
* @param a right hand side parameter of the operator
* @return this÷s;a
*/
T divide(double a);
/** IEEE remainder operator.
* @param a right hand side parameter of the operator
* @return this - n × a where n is the closest integer to this/a
* (the even integer is chosen for n if this/a is halfway between two integers)
*/
T remainder(double a);
/** IEEE remainder operator.
* @param a right hand side parameter of the operator
* @return this - n × a where n is the closest integer to this/a
* (the even integer is chosen for n if this/a is halfway between two integers)
* @exception DimensionMismatchException if number of free parameters or orders are inconsistent
*/
T remainder(T a)
throws DimensionMismatchException;
/** absolute value.
* @return abs(this)
*/
T abs();
/** Get the smallest whole number larger than instance.
* @return ceil(this)
*/
T ceil();
/** Get the largest whole number smaller than instance.
* @return floor(this)
*/
T floor();
/** Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers.
* @return a double number r such that r is an integer r - 0.5 <= this <= r + 0.5
*/
T rint();
/** Get the closest long to instance value.
* @return closest long to {@link #getReal()}
*/
long round();
/** Compute the signum of the instance.
* The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise
* @return -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
*/
T signum();
/**
* Returns the instance with the sign of the argument.
* A NaN {@code sign} argument is treated as positive.
*
* @param sign the sign for the returned value
* @return the instance with the same sign as the {@code sign} argument
*/
T copySign(T sign);
/**
* Returns the instance with the sign of the argument.
* A NaN {@code sign} argument is treated as positive.
*
* @param sign the sign for the returned value
* @return the instance with the same sign as the {@code sign} argument
*/
T copySign(double sign);
/**
* Multiply the instance by a power of 2.
* @param n power of 2
* @return this × 2<sup>n</sup>
*/
T scalb(int n);
/**
* Returns the hypotenuse of a triangle with sides {@code this} and {@code y}
* - sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>)<br/>
* avoiding intermediate overflow or underflow.
*
* <ul>
* <li> If either argument is infinite, then the result is positive infinity.</li>
* <li> else, if either argument is NaN then the result is NaN.</li>
* </ul>
*
* @param y a value
* @return sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>)
* @exception DimensionMismatchException if number of free parameters or orders are inconsistent
*/
T hypot(T y)
throws DimensionMismatchException;
/** {@inheritDoc} */
T reciprocal();
/** Square root.
* @return square root of the instance
*/
T sqrt();
/** Cubic root.
* @return cubic root of the instance
*/
T cbrt();
/** N<sup>th</sup> root.
* @param n order of the root
* @return n<sup>th</sup> root of the instance
*/
T rootN(int n);
/** Power operation.
* @param p power to apply
* @return this<sup>p</sup>
*/
T pow(double p);
/** Integer power operation.
* @param n power to apply
* @return this<sup>n</sup>
*/
T pow(int n);
/** Power operation.
* @param e exponent
* @return this<sup>e</sup>
* @exception DimensionMismatchException if number of free parameters or orders are inconsistent
*/
T pow(T e)
throws DimensionMismatchException;
/** Exponential.
* @return exponential of the instance
*/
T exp();
/** Exponential minus 1.
* @return exponential minus one of the instance
*/
T expm1();
/** Natural logarithm.
* @return logarithm of the instance
*/
T log();
/** Shifted natural logarithm.
* @return logarithm of one plus the instance
*/
T log1p();
// TODO: add this method in 4.0, as it is not possible to do it in 3.2
// due to incompatibility of the return type in the Dfp class
// /** Base 10 logarithm.
// * @return base 10 logarithm of the instance
// */
// T log10();
/** Cosine operation.
* @return cos(this)
*/
T cos();
/** Sine operation.
* @return sin(this)
*/
T sin();
/** Tangent operation.
* @return tan(this)
*/
T tan();
/** Arc cosine operation.
* @return acos(this)
*/
T acos();
/** Arc sine operation.
* @return asin(this)
*/
T asin();
/** Arc tangent operation.
* @return atan(this)
*/
T atan();
/** Two arguments arc tangent operation.
* @param x second argument of the arc tangent
* @return atan2(this, x)
* @exception DimensionMismatchException if number of free parameters or orders are inconsistent
*/
T atan2(T x)
throws DimensionMismatchException;
/** Hyperbolic cosine operation.
* @return cosh(this)
*/
T cosh();
/** Hyperbolic sine operation.
* @return sinh(this)
*/
T sinh();
/** Hyperbolic tangent operation.
* @return tanh(this)
*/
T tanh();
/** Inverse hyperbolic cosine operation.
* @return acosh(this)
*/
T acosh();
/** Inverse hyperbolic sine operation.
* @return asin(this)
*/
T asinh();
/** Inverse hyperbolic tangent operation.
* @return atanh(this)
*/
T atanh();
/**
* Compute a linear combination.
* @param a Factors.
* @param b Factors.
* @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
* @throws DimensionMismatchException if arrays dimensions don't match
* @since 3.2
*/
T linearCombination(T[] a, T[] b)
throws DimensionMismatchException;
/**
* Compute a linear combination.
* @param a Factors.
* @param b Factors.
* @return <code>Σ<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
* @throws DimensionMismatchException if arrays dimensions don't match
* @since 3.2
*/
T linearCombination(double[] a, T[] b)
throws DimensionMismatchException;
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub>
* @see #linearCombination(Object, Object, Object, Object, Object, Object)
* @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
* @since 3.2
*/
T linearCombination(T a1, T b1, T a2, T b2);
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub>
* @see #linearCombination(double, Object, double, Object, double, Object)
* @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
* @since 3.2
*/
T linearCombination(double a1, T b1, double a2, T b2);
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @param a3 first factor of the third term
* @param b3 second factor of the third term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub>
* @see #linearCombination(Object, Object, Object, Object)
* @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
* @since 3.2
*/
T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3);
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @param a3 first factor of the third term
* @param b3 second factor of the third term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub>
* @see #linearCombination(double, Object, double, Object)
* @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
* @since 3.2
*/
T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3);
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @param a3 first factor of the third term
* @param b3 second factor of the third term
* @param a4 first factor of the third term
* @param b4 second factor of the third term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> +
* a<sub>4</sub>×b<sub>4</sub>
* @see #linearCombination(Object, Object, Object, Object)
* @see #linearCombination(Object, Object, Object, Object, Object, Object)
* @since 3.2
*/
T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4);
/**
* Compute a linear combination.
* @param a1 first factor of the first term
* @param b1 second factor of the first term
* @param a2 first factor of the second term
* @param b2 second factor of the second term
* @param a3 first factor of the third term
* @param b3 second factor of the third term
* @param a4 first factor of the third term
* @param b4 second factor of the third term
* @return a<sub>1</sub>×b<sub>1</sub> +
* a<sub>2</sub>×b<sub>2</sub> + a<sub>3</sub>×b<sub>3</sub> +
* a<sub>4</sub>×b<sub>4</sub>
* @see #linearCombination(double, Object, double, Object)
* @see #linearCombination(double, Object, double, Object, double, Object)
* @since 3.2
*/
T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4);
}