org.apache.commons.math3.RealFieldElement Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-math3 Show documentation
Show all versions of commons-math3 Show documentation
The Apache Commons Math project is a library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems not immediately available in the Java programming language or commons-lang.
/*
* 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 real
* field.
* @param the type of the field elements
* @see FieldElement
* @since 3.2
*/
public interface RealFieldElement extends FieldElement {
/** 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÷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 × 2n
*/
T scalb(int n);
/**
* Returns the hypotenuse of a triangle with sides {@code this} and {@code y}
* - sqrt(this2 +y2)
* avoiding intermediate overflow or underflow.
*
*
* - If either argument is infinite, then the result is positive infinity.
* - else, if either argument is NaN then the result is NaN.
*
*
* @param y a value
* @return sqrt(this2 +y2)
* @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();
/** Nth root.
* @param n order of the root
* @return nth root of the instance
*/
T rootN(int n);
/** Power operation.
* @param p power to apply
* @return thisp
*/
T pow(double p);
/** Integer power operation.
* @param n power to apply
* @return thisn
*/
T pow(int n);
/** Power operation.
* @param e exponent
* @return thise
* @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 Σi ai bi.
* @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 Σi ai bi.
* @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 a1×b1 +
* a2×b2
* @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 a1×b1 +
* a2×b2
* @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 a1×b1 +
* a2×b2 + a3×b3
* @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 a1×b1 +
* a2×b2 + a3×b3
* @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 a1×b1 +
* a2×b2 + a3×b3 +
* a4×b4
* @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 a1×b1 +
* a2×b2 + a3×b3 +
* a4×b4
* @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);
}