RealFieldElement.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) 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 ASF 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.  *      http://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.apache.commons.math4.legacy.core;

  19. import org.apache.commons.math4.legacy.exception.DimensionMismatchException;

  21. /**
  22.  * Interface representing a <a href="http://mathworld.wolfram.com/RealNumber.html">real</a>
  23.  * <a href="http://mathworld.wolfram.com/Field.html">field</a>.
  24.  * @param <T> the type of the field elements
  25.  * @see FieldElement
  26.  * @since 3.2
  27.  */
  28. public interface RealFieldElement<T> extends FieldElement<T> {

  30.     /** Get the real value of the number.
  31.      * @return real value
  32.      */
  33.     double getReal();

  35.     /** '+' operator.
  36.      * @param a right hand side parameter of the operator
  37.      * @return this+a
  38.      */
  39.     T add(double a);

  41.     /** '-' operator.
  42.      * @param a right hand side parameter of the operator
  43.      * @return this-a
  44.      */
  45.     T subtract(double a);

  47.     /** '&times;' operator.
  48.      * @param a right hand side parameter of the operator
  49.      * @return this&times;a
  50.      */
  51.     T multiply(double a);

  53.     /** '&divide;' operator.
  54.      * @param a right hand side parameter of the operator
  55.      * @return this&divide;a
  56.      */
  57.     T divide(double a);

  59.     /** IEEE remainder operator.
  60.      * @param a right hand side parameter of the operator
  61.      * @return this - n &times; a where n is the closest integer to this/a
  62.      * (the even integer is chosen for n if this/a is halfway between two integers)
  63.      */
  64.     T remainder(double a);

  66.     /** IEEE remainder operator.
  67.      * @param a right hand side parameter of the operator
  68.      * @return this - n &times; a where n is the closest integer to this/a
  69.      * (the even integer is chosen for n if this/a is halfway between two integers)
  70.      * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
  71.      */
  72.     T remainder(T a)
  73.         throws DimensionMismatchException;

  75.     /** absolute value.
  76.      * @return abs(this)
  77.      */
  78.     T abs();

  80.     /** Get the smallest whole number larger than instance.
  81.      * @return ceil(this)
  82.      */
  83.     T ceil();

  85.     /** Get the largest whole number smaller than instance.
  86.      * @return floor(this)
  87.      */
  88.     T floor();

  90.     /** Get the whole number that is the nearest to the instance, or the even one if x is exactly
  91.      * half way between two integers.
  92.      * @return a double number r such that r is an integer r - 0.5 &le; this &le; r + 0.5
  93.      */
  94.     T rint();

  96.     /** Get the closest long to instance value.
  97.      * @return closest long to {@link #getReal()}
  98.      */
  99.     long round();

  101.     /** Compute the signum of the instance.
  102.      * The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise
  103.      * @return -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
  104.      */
  105.     T signum();

  107.     /**
  108.      * Returns the instance with the sign of the argument.
  109.      * A NaN {@code sign} argument is treated as positive.
  110.      *
  111.      * @param sign the sign for the returned value
  112.      * @return the instance with the same sign as the {@code sign} argument
  113.      */
  114.     T copySign(T sign);

  116.     /**
  117.      * Returns the instance with the sign of the argument.
  118.      * A NaN {@code sign} argument is treated as positive.
  119.      *
  120.      * @param sign the sign for the returned value
  121.      * @return the instance with the same sign as the {@code sign} argument
  122.      */
  123.     T copySign(double sign);

  125.     /**
  126.      * Multiply the instance by a power of 2.
  127.      * @param n power of 2
  128.      * @return this &times; 2<sup>n</sup>
  129.      */
  130.     T scalb(int n);

  132.     /**
  133.      * Returns the hypotenuse of a triangle with sides {@code this} and {@code y}
  134.      * - sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
  135.      * avoiding intermediate overflow or underflow.
  136.      *
  137.      * <ul>
  138.      * <li> If either argument is infinite, then the result is positive infinity.</li>
  139.      * <li> else, if either argument is NaN then the result is NaN.</li>
  140.      * </ul>
  141.      *
  142.      * @param y a value
  143.      * @return sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
  144.      * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
  145.      */
  146.     T hypot(T y)
  147.         throws DimensionMismatchException;

  149.     /** {@inheritDoc} */
  150.     @Override
  151.     T reciprocal();

  153.     /** Square root.
  154.      * @return square root of the instance
  155.      */
  156.     T sqrt();

  158.     /** Cubic root.
  159.      * @return cubic root of the instance
  160.      */
  161.     T cbrt();

  163.     /** N<sup>th</sup> root.
  164.      * @param n order of the root
  165.      * @return n<sup>th</sup> root of the instance
  166.      */
  167.     T rootN(int n);

  169.     /** Power operation.
  170.      * @param p power to apply
  171.      * @return this<sup>p</sup>
  172.      */
  173.     T pow(double p);

  175.     /** Integer power operation.
  176.      * @param n power to apply
  177.      * @return this<sup>n</sup>
  178.      */
  179.     T pow(int n);

  181.     /** Power operation.
  182.      * @param e exponent
  183.      * @return this<sup>e</sup>
  184.      * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
  185.      */
  186.     T pow(T e)
  187.         throws DimensionMismatchException;

  189.     /** Exponential.
  190.      * @return exponential of the instance
  191.      */
  192.     T exp();

  194.     /** Exponential minus 1.
  195.      * @return exponential minus one of the instance
  196.      */
  197.     T expm1();

  199.     /** Natural logarithm.
  200.      * @return logarithm of the instance
  201.      */
  202.     T log();

  204.     /** Shifted natural logarithm.
  205.      * @return logarithm of one plus the instance
  206.      */
  207.     T log1p();

  209.     /** Base 10 logarithm.
  210.      * @return base 10 logarithm of the instance
  211.      * @since 4.0
  212.      */
  213.     T log10();

  215.     /** Cosine operation.
  216.      * @return cos(this)
  217.      */
  218.     T cos();

  220.     /** Sine operation.
  221.      * @return sin(this)
  222.      */
  223.     T sin();

  225.     /** Tangent operation.
  226.      * @return tan(this)
  227.      */
  228.     T tan();

  230.     /** Arc cosine operation.
  231.      * @return acos(this)
  232.      */
  233.     T acos();

  235.     /** Arc sine operation.
  236.      * @return asin(this)
  237.      */
  238.     T asin();

  240.     /** Arc tangent operation.
  241.      * @return atan(this)
  242.      */
  243.     T atan();

  245.     /** Two arguments arc tangent operation.
  246.      * @param x second argument of the arc tangent
  247.      * @return atan2(this, x)
  248.      * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
  249.      */
  250.     T atan2(T x)
  251.         throws DimensionMismatchException;

  253.     /** Hyperbolic cosine operation.
  254.      * @return cosh(this)
  255.      */
  256.     T cosh();

  258.     /** Hyperbolic sine operation.
  259.      * @return sinh(this)
  260.      */
  261.     T sinh();

  263.     /** Hyperbolic tangent operation.
  264.      * @return tanh(this)
  265.      */
  266.     T tanh();

  268.     /** Inverse hyperbolic cosine operation.
  269.      * @return acosh(this)
  270.      */
  271.     T acosh();

  273.     /** Inverse hyperbolic sine operation.
  274.      * @return asin(this)
  275.      */
  276.     T asinh();

  278.     /** Inverse hyperbolic  tangent operation.
  279.      * @return atanh(this)
  280.      */
  281.     T atanh();

  283.     /**
  284.      * Compute a linear combination.
  285.      * @param a Factors.
  286.      * @param b Factors.
  287.      * @return <code>&Sigma;<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
  288.      * @throws DimensionMismatchException if arrays dimensions don't match
  289.      * @since 3.2
  290.      */
  291.     T linearCombination(T[] a, T[] b)
  292.         throws DimensionMismatchException;

  294.     /**
  295.      * Compute a linear combination.
  296.      * @param a Factors.
  297.      * @param b Factors.
  298.      * @return <code>&Sigma;<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
  299.      * @throws DimensionMismatchException if arrays dimensions don't match
  300.      * @since 3.2
  301.      */
  302.     T linearCombination(double[] a, T[] b)
  303.         throws DimensionMismatchException;

  305.     /**
  306.      * Compute a linear combination.
  307.      * @param a1 first factor of the first term
  308.      * @param b1 second factor of the first term
  309.      * @param a2 first factor of the second term
  310.      * @param b2 second factor of the second term
  311.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  312.      * a<sub>2</sub>&times;b<sub>2</sub>
  313.      * @see #linearCombination(Object, Object, Object, Object, Object, Object)
  314.      * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
  315.      * @since 3.2
  316.      */
  317.     T linearCombination(T a1, T b1, T a2, T b2);

  319.     /**
  320.      * Compute a linear combination.
  321.      * @param a1 first factor of the first term
  322.      * @param b1 second factor of the first term
  323.      * @param a2 first factor of the second term
  324.      * @param b2 second factor of the second term
  325.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  326.      * a<sub>2</sub>&times;b<sub>2</sub>
  327.      * @see #linearCombination(double, Object, double, Object, double, Object)
  328.      * @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
  329.      * @since 3.2
  330.      */
  331.     T linearCombination(double a1, T b1, double a2, T b2);

  333.     /**
  334.      * Compute a linear combination.
  335.      * @param a1 first factor of the first term
  336.      * @param b1 second factor of the first term
  337.      * @param a2 first factor of the second term
  338.      * @param b2 second factor of the second term
  339.      * @param a3 first factor of the third term
  340.      * @param b3 second factor of the third term
  341.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  342.      * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub>
  343.      * @see #linearCombination(Object, Object, Object, Object)
  344.      * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
  345.      * @since 3.2
  346.      */
  347.     T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3);

  349.     /**
  350.      * Compute a linear combination.
  351.      * @param a1 first factor of the first term
  352.      * @param b1 second factor of the first term
  353.      * @param a2 first factor of the second term
  354.      * @param b2 second factor of the second term
  355.      * @param a3 first factor of the third term
  356.      * @param b3 second factor of the third term
  357.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  358.      * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub>
  359.      * @see #linearCombination(double, Object, double, Object)
  360.      * @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
  361.      * @since 3.2
  362.      */
  363.     T linearCombination(double a1, T b1,  double a2, T b2, double a3, T b3);

  365.     /**
  366.      * Compute a linear combination.
  367.      * @param a1 first factor of the first term
  368.      * @param b1 second factor of the first term
  369.      * @param a2 first factor of the second term
  370.      * @param b2 second factor of the second term
  371.      * @param a3 first factor of the third term
  372.      * @param b3 second factor of the third term
  373.      * @param a4 first factor of the third term
  374.      * @param b4 second factor of the third term
  375.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  376.      * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub> +
  377.      * a<sub>4</sub>&times;b<sub>4</sub>
  378.      * @see #linearCombination(Object, Object, Object, Object)
  379.      * @see #linearCombination(Object, Object, Object, Object, Object, Object)
  380.      * @since 3.2
  381.      */
  382.     T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4);

  384.     /**
  385.      * Compute a linear combination.
  386.      * @param a1 first factor of the first term
  387.      * @param b1 second factor of the first term
  388.      * @param a2 first factor of the second term
  389.      * @param b2 second factor of the second term
  390.      * @param a3 first factor of the third term
  391.      * @param b3 second factor of the third term
  392.      * @param a4 first factor of the third term
  393.      * @param b4 second factor of the third term
  394.      * @return a<sub>1</sub>&times;b<sub>1</sub> +
  395.      * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub> +
  396.      * a<sub>4</sub>&times;b<sub>4</sub>
  397.      * @see #linearCombination(double, Object, double, Object)
  398.      * @see #linearCombination(double, Object, double, Object, double, Object)
  399.      * @since 3.2
  400.      */
  401.     T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4);

  403.     /** Find the maximum of two field elements.
  404.      * @param <T> the type of the field elements
  405.      * @param e1 first element
  406.      * @param e2 second element
  407.      * @return max(a1, e2)
  408.      */
  409.     static <T extends RealFieldElement<T>> T max(final T e1, final T e2) {
  410.         return e1.subtract(e2).getReal() >= 0 ? e1 : e2;
  411.     }

  413.     /** Find the minimum of two field elements.
  414.      * @param <T> the type of the field elements
  415.      * @param e1 first element
  416.      * @param e2 second element
  417.      * @return min(a1, e2)
  418.      */
  419.     static <T extends RealFieldElement<T>> T min(final T e1, final T e2) {
  420.         return e1.subtract(e2).getReal() >= 0 ? e2 : e1;
  421.     }
  422. }
Created with JaCoCo 0.8.10.202304240956