- * Implementations of arithmetic operations handle {@code NaN} and - * infinite values according to the rules for {@link java.lang.Double}, i.e. - * {@link #equals} is an equivalence relation for all instances that have - * a {@code NaN} in either real or imaginary part, e.g. the following are - * considered equal: - *
- * Note that this contradicts the IEEE-754 standard for floating - * point numbers (according to which the test {@code x == x} must fail if - * {@code x} is {@code NaN}). The method - * {@link org.apache.commons.numbers.core.Precision#equals(double,double,int) - * equals for primitive double} in {@link org.apache.commons.numbers.core.Precision} - * conforms with IEEE-754 while this class conforms with the standard behavior - * for Java object types.
- * - */ -public class Complex implements FieldElement- * {@code (a + bi) + (c + di) = (a+c) + (b+d)i} - *
- * If either {@code this} or {@code addend} has a {@code NaN} value in - * either part, {@link #NaN} is returned; otherwise {@code Infinite} - * and {@code NaN} values are returned in the parts of the result - * according to the rules for {@link java.lang.Double} arithmetic. - * - * @param addend Value to be added to this {@code Complex}. - * @return {@code this + addend}. - * @throws NullArgumentException if {@code addend} is {@code null}. - */ - @Override - public Complex add(Complex addend) throws NullArgumentException { - MathUtils.checkNotNull(addend); - if (isNaN || addend.isNaN) { - return NaN; - } - - return createComplex(real + addend.getReal(), - imaginary + addend.getImaginary()); - } - - /** - * Returns a {@code Complex} whose value is {@code (this + addend)}, - * with {@code addend} interpreted as a real number. - * - * @param addend Value to be added to this {@code Complex}. - * @return {@code this + addend}. - * @see #add(Complex) - */ - public Complex add(double addend) { - if (isNaN || Double.isNaN(addend)) { - return NaN; - } - - return createComplex(real + addend, imaginary); - } - - /** - * Returns the conjugate of this complex number. - * The conjugate of {@code a + bi} is {@code a - bi}. - *- * {@link #NaN} is returned if either the real or imaginary - * part of this Complex number equals {@code Double.NaN}. - *
- * If the imaginary part is infinite, and the real part is not - * {@code NaN}, the returned value has infinite imaginary part - * of the opposite sign, e.g. the conjugate of - * {@code 1 + POSITIVE_INFINITY i} is {@code 1 - NEGATIVE_INFINITY i}. - *
- * @return the conjugate of this Complex object. - */ - public Complex conjugate() { - if (isNaN) { - return NaN; - } - - return createComplex(real, -imaginary); - } - - /** - * Returns a {@code Complex} whose value is - * {@code (this / divisor)}. - * Implements the definitional formula - *
- *
- * a + bi ac + bd + (bc - ad)i
- * ----------- = -------------------------
- * c + di c2 + d2
- *
- *
- * but uses
- *
- * prescaling of operands to limit the effects of overflows and
- * underflows in the computation.
- * - * {@code Infinite} and {@code NaN} values are handled according to the - * following rules, applied in the order presented: - *
- * {@code (a + bi)(c + di) = (ac - bd) + (ad + bc)i} - *
- * Returns {@link #NaN} if either {@code this} or {@code factor} has one or - * more {@code NaN} parts. - *- * Returns {@link #INF} if neither {@code this} nor {@code factor} has one - * or more {@code NaN} parts and if either {@code this} or {@code factor} - * has one or more infinite parts (same result is returned regardless of - * the sign of the components). - *
- * Returns finite values in components of the result per the definitional - * formula in all remaining cases.
- * - * @param factor value to be multiplied by this {@code Complex}. - * @return {@code this * factor}. - * @throws NullArgumentException if {@code factor} is {@code null}. - */ - @Override - public Complex multiply(Complex factor) - throws NullArgumentException { - MathUtils.checkNotNull(factor); - if (isNaN || factor.isNaN) { - return NaN; - } - if (Double.isInfinite(real) || - Double.isInfinite(imaginary) || - Double.isInfinite(factor.real) || - Double.isInfinite(factor.imaginary)) { - // we don't use isInfinite() to avoid testing for NaN again - return INF; - } - return createComplex(real * factor.real - imaginary * factor.imaginary, - real * factor.imaginary + imaginary * factor.real); - } - - /** - * Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor} - * interpreted as a integer number. - * - * @param factor value to be multiplied by this {@code Complex}. - * @return {@code this * factor}. - * @see #multiply(Complex) - */ - @Override - public Complex multiply(final int factor) { - if (isNaN) { - return NaN; - } - if (Double.isInfinite(real) || - Double.isInfinite(imaginary)) { - return INF; - } - return createComplex(real * factor, imaginary * factor); - } - - /** - * Returns a {@code Complex} whose value is {@code this * factor}, with {@code factor} - * interpreted as a real number. - * - * @param factor value to be multiplied by this {@code Complex}. - * @return {@code this * factor}. - * @see #multiply(Complex) - */ - public Complex multiply(double factor) { - if (isNaN || Double.isNaN(factor)) { - return NaN; - } - if (Double.isInfinite(real) || - Double.isInfinite(imaginary) || - Double.isInfinite(factor)) { - // we don't use isInfinite() to avoid testing for NaN again - return INF; - } - return createComplex(real * factor, imaginary * factor); - } - - /** - * Returns a {@code Complex} whose value is {@code (-this)}. - * Returns {@code NaN} if either real or imaginary - * part of this Complex number is {@code Double.NaN}. - * - * @return {@code -this}. - */ - @Override - public Complex negate() { - if (isNaN) { - return NaN; - } - - return createComplex(-real, -imaginary); - } - - /** - * Returns a {@code Complex} whose value is - * {@code (this - subtrahend)}. - * Uses the definitional formula - *- * {@code (a + bi) - (c + di) = (a-c) + (b-d)i} - *
- * If either {@code this} or {@code subtrahend} has a {@code NaN]} value in either part, - * {@link #NaN} is returned; otherwise infinite and {@code NaN} values are - * returned in the parts of the result according to the rules for - * {@link java.lang.Double} arithmetic. - * - * @param subtrahend value to be subtracted from this {@code Complex}. - * @return {@code this - subtrahend}. - * @throws NullArgumentException if {@code subtrahend} is {@code null}. - */ - @Override - public Complex subtract(Complex subtrahend) - throws NullArgumentException { - MathUtils.checkNotNull(subtrahend); - if (isNaN || subtrahend.isNaN) { - return NaN; - } - - return createComplex(real - subtrahend.getReal(), - imaginary - subtrahend.getImaginary()); - } - - /** - * Returns a {@code Complex} whose value is - * {@code (this - subtrahend)}. - * - * @param subtrahend value to be subtracted from this {@code Complex}. - * @return {@code this - subtrahend}. - * @see #subtract(Complex) - */ - public Complex subtract(double subtrahend) { - if (isNaN || Double.isNaN(subtrahend)) { - return NaN; - } - return createComplex(real - subtrahend, imaginary); - } - - /** - * Compute the - * - * inverse cosine of this complex number. - * Implements the formula: - *- * {@code acos(z) = -i (log(z + i (sqrt(1 - z2))))} - *
- * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite. - * - * @return the inverse cosine of this complex number. - * @since 1.2 - */ - public Complex acos() { - if (isNaN) { - return NaN; - } - - return this.add(this.sqrt1z().multiply(I)).log().multiply(I.negate()); - } - - /** - * Compute the - * - * inverse sine of this complex number. - * Implements the formula: - *- * {@code asin(z) = -i (log(sqrt(1 - z2) + iz))} - *
- * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite.
- * - * @return the inverse sine of this complex number. - * @since 1.2 - */ - public Complex asin() { - if (isNaN) { - return NaN; - } - - return sqrt1z().add(this.multiply(I)).log().multiply(I.negate()); - } - - /** - * Compute the - * - * inverse tangent of this complex number. - * Implements the formula: - *- * {@code atan(z) = (i/2) log((i + z)/(i - z))} - *
- * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite.
- * - * @return the inverse tangent of this complex number - * @since 1.2 - */ - public Complex atan() { - if (isNaN) { - return NaN; - } - - return this.add(I).divide(I.subtract(this)).log() - .multiply(I.divide(createComplex(2.0, 0.0))); - } - - /** - * Compute the - * - * cosine of this complex number. - * Implements the formula: - *- * {@code cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i} - *
- * where the (real) functions on the right-hand side are - * {@link FastMath#sin}, {@link FastMath#cos}, - * {@link FastMath#cosh} and {@link FastMath#sinh}. - *
- * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result.
- *
- * Examples:
- *
- * cos(1 ± INFINITY i) = 1 \u2213 INFINITY i
- * cos(±INFINITY + i) = NaN + NaN i
- * cos(±INFINITY ± INFINITY i) = NaN + NaN i
- *
- *
- *
- * @return the cosine of this complex number.
- * @since 1.2
- */
- public Complex cos() {
- if (isNaN) {
- return NaN;
- }
-
- return createComplex(FastMath.cos(real) * FastMath.cosh(imaginary),
- -FastMath.sin(real) * FastMath.sinh(imaginary));
- }
-
- /**
- * Compute the
- *
- * hyperbolic cosine of this complex number.
- * Implements the formula:
- *
- *
- * cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#sin}, {@link FastMath#cos},
- * {@link FastMath#cosh} and {@link FastMath#sinh}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * cosh(1 ± INFINITY i) = NaN + NaN i
- * cosh(±INFINITY + i) = INFINITY ± INFINITY i
- * cosh(±INFINITY ± INFINITY i) = NaN + NaN i
- *
- *
- *
- * @return the hyperbolic cosine of this complex number.
- * @since 1.2
- */
- public Complex cosh() {
- if (isNaN) {
- return NaN;
- }
-
- return createComplex(FastMath.cosh(real) * FastMath.cos(imaginary),
- FastMath.sinh(real) * FastMath.sin(imaginary));
- }
-
- /**
- * Compute the
- *
- * exponential function of this complex number.
- * Implements the formula:
- *
- *
- * exp(a + bi) = exp(a)cos(b) + exp(a)sin(b)i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#exp}, {@link FastMath#cos}, and
- * {@link FastMath#sin}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * exp(1 ± INFINITY i) = NaN + NaN i
- * exp(INFINITY + i) = INFINITY + INFINITY i
- * exp(-INFINITY + i) = 0 + 0i
- * exp(±INFINITY ± INFINITY i) = NaN + NaN i
- *
- *
- *
- * @return ethis.
- * @since 1.2
- */
- public Complex exp() {
- if (isNaN) {
- return NaN;
- }
-
- double expReal = FastMath.exp(real);
- return createComplex(expReal * FastMath.cos(imaginary),
- expReal * FastMath.sin(imaginary));
- }
-
- /**
- * Compute the
- *
- * natural logarithm of this complex number.
- * Implements the formula:
- *
- *
- * log(a + bi) = ln(|a + bi|) + arg(a + bi)i
- *
- *
- * where ln on the right hand side is {@link FastMath#log},
- * {@code |a + bi|} is the modulus, {@link Complex#abs}, and
- * {@code arg(a + bi) = }{@link FastMath#atan2}(b, a).
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite (or critical) values in real or imaginary parts of the input may - * result in infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * log(1 ± INFINITY i) = INFINITY ± (π/2)i
- * log(INFINITY + i) = INFINITY + 0i
- * log(-INFINITY + i) = INFINITY + πi
- * log(INFINITY ± INFINITY i) = INFINITY ± (π/4)i
- * log(-INFINITY ± INFINITY i) = INFINITY ± (3π/4)i
- * log(0 + 0i) = -INFINITY + 0i
- *
- *
- *
- * @return the value ln this, the natural logarithm
- * of {@code this}.
- * @since 1.2
- */
- public Complex log() {
- if (isNaN) {
- return NaN;
- }
-
- return createComplex(FastMath.log(abs()),
- FastMath.atan2(imaginary, real));
- }
-
- /**
- * Returns of value of this complex number raised to the power of {@code x}.
- * Implements the formula:
- *
- *
- * yx = exp(x·log(y))
- *
- *
- * where {@code exp} and {@code log} are {@link #exp} and
- * {@link #log}, respectively.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN} or infinite, or if {@code y} - * equals {@link Complex#ZERO}.
- * - * @param x exponent to which this {@code Complex} is to be raised. - * @return thisx.
- * @throws NullArgumentException if x is {@code null}.
- * @since 1.2
- */
- public Complex pow(Complex x)
- throws NullArgumentException {
- MathUtils.checkNotNull(x);
- return this.log().multiply(x).exp();
- }
-
- /**
- * Returns of value of this complex number raised to the power of {@code x}.
- *
- * @param x exponent to which this {@code Complex} is to be raised.
- * @return thisx.
- * @see #pow(Complex)
- */
- public Complex pow(double x) {
- return this.log().multiply(x).exp();
- }
-
- /**
- * Compute the
- *
- * sine
- * of this complex number.
- * Implements the formula:
- *
- *
- * sin(a + bi) = sin(a)cosh(b) - cos(a)sinh(b)i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#sin}, {@link FastMath#cos},
- * {@link FastMath#cosh} and {@link FastMath#sinh}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or {@code NaN} values returned in parts of the result. - *
- * Examples:
- *
- * sin(1 ± INFINITY i) = 1 ± INFINITY i
- * sin(±INFINITY + i) = NaN + NaN i
- * sin(±INFINITY ± INFINITY i) = NaN + NaN i
- *
- *
- *
- * @return the sine of this complex number.
- * @since 1.2
- */
- public Complex sin() {
- if (isNaN) {
- return NaN;
- }
-
- return createComplex(FastMath.sin(real) * FastMath.cosh(imaginary),
- FastMath.cos(real) * FastMath.sinh(imaginary));
- }
-
- /**
- * Compute the
- *
- * hyperbolic sine of this complex number.
- * Implements the formula:
- *
- *
- * sinh(a + bi) = sinh(a)cos(b)) + cosh(a)sin(b)i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#sin}, {@link FastMath#cos},
- * {@link FastMath#cosh} and {@link FastMath#sinh}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * sinh(1 ± INFINITY i) = NaN + NaN i
- * sinh(±INFINITY + i) = ± INFINITY + INFINITY i
- * sinh(±INFINITY ± INFINITY i) = NaN + NaN i
- *
- *
- *
- * @return the hyperbolic sine of {@code this}.
- * @since 1.2
- */
- public Complex sinh() {
- if (isNaN) {
- return NaN;
- }
-
- return createComplex(FastMath.sinh(real) * FastMath.cos(imaginary),
- FastMath.cosh(real) * FastMath.sin(imaginary));
- }
-
- /**
- * Compute the
- *
- * square root of this complex number.
- * Implements the following algorithm to compute {@code sqrt(a + bi)}:
- * if {@code a ≥ 0} return {@code t + (b/2t)i}
- * else return {@code |b|/2t + sign(b)t i }- * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * sqrt(1 ± INFINITY i) = INFINITY + NaN i
- * sqrt(INFINITY + i) = INFINITY + 0i
- * sqrt(-INFINITY + i) = 0 + INFINITY i
- * sqrt(INFINITY ± INFINITY i) = INFINITY + NaN i
- * sqrt(-INFINITY ± INFINITY i) = NaN ± INFINITY i
- *
- *
- *
- * @return the square root of {@code this}.
- * @since 1.2
- */
- public Complex sqrt() {
- if (isNaN) {
- return NaN;
- }
-
- if (real == 0.0 && imaginary == 0.0) {
- return createComplex(0.0, 0.0);
- }
-
- double t = FastMath.sqrt((FastMath.abs(real) + abs()) / 2.0);
- if (real >= 0.0) {
- return createComplex(t, imaginary / (2.0 * t));
- } else {
- return createComplex(FastMath.abs(imaginary) / (2.0 * t),
- FastMath.copySign(1d, imaginary) * t);
- }
- }
-
- /**
- * Compute the
- *
- * square root of 1 - this2 for this complex
- * number.
- * Computes the result directly as
- * {@code sqrt(ONE.subtract(z.multiply(z)))}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - * - * @return the square root of1 - this2.
- * @since 1.2
- */
- public Complex sqrt1z() {
- return createComplex(1.0, 0.0).subtract(this.multiply(this)).sqrt();
- }
-
- /**
- * Compute the
- *
- * tangent of this complex number.
- * Implements the formula:
- *
- *
- * tan(a + bi) = sin(2a)/(cos(2a)+cosh(2b)) + [sinh(2b)/(cos(2a)+cosh(2b))]i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and
- * {@link FastMath#sinh}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite (or critical) values in real or imaginary parts of the input may - * result in infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * tan(a ± INFINITY i) = 0 ± i
- * tan(±INFINITY + bi) = NaN + NaN i
- * tan(±INFINITY ± INFINITY i) = NaN + NaN i
- * tan(±π/2 + 0 i) = ±INFINITY + NaN i
- *
- *
- *
- * @return the tangent of {@code this}.
- * @since 1.2
- */
- public Complex tan() {
- if (isNaN || Double.isInfinite(real)) {
- return NaN;
- }
- if (imaginary > 20.0) {
- return createComplex(0.0, 1.0);
- }
- if (imaginary < -20.0) {
- return createComplex(0.0, -1.0);
- }
-
- double real2 = 2.0 * real;
- double imaginary2 = 2.0 * imaginary;
- double d = FastMath.cos(real2) + FastMath.cosh(imaginary2);
-
- return createComplex(FastMath.sin(real2) / d,
- FastMath.sinh(imaginary2) / d);
- }
-
- /**
- * Compute the
- *
- * hyperbolic tangent of this complex number.
- * Implements the formula:
- *
- *
- * tan(a + bi) = sinh(2a)/(cosh(2a)+cos(2b)) + [sin(2b)/(cosh(2a)+cos(2b))]i
- *
- *
- * where the (real) functions on the right-hand side are
- * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and
- * {@link FastMath#sinh}.
- * - * Returns {@link Complex#NaN} if either real or imaginary part of the - * input argument is {@code NaN}. - *
- * Infinite values in real or imaginary parts of the input may result in - * infinite or NaN values returned in parts of the result. - *
- * Examples:
- *
- * tanh(a ± INFINITY i) = NaN + NaN i
- * tanh(±INFINITY + bi) = ±1 + 0 i
- * tanh(±INFINITY ± INFINITY i) = NaN + NaN i
- * tanh(0 + (π/2)i) = NaN + INFINITY i
- *
- *
- *
- * @return the hyperbolic tangent of {@code this}.
- * @since 1.2
- */
- public Complex tanh() {
- if (isNaN || Double.isInfinite(imaginary)) {
- return NaN;
- }
- if (real > 20.0) {
- return createComplex(1.0, 0.0);
- }
- if (real < -20.0) {
- return createComplex(-1.0, 0.0);
- }
- double real2 = 2.0 * real;
- double imaginary2 = 2.0 * imaginary;
- double d = FastMath.cosh(real2) + FastMath.cos(imaginary2);
-
- return createComplex(FastMath.sinh(real2) / d,
- FastMath.sin(imaginary2) / d);
- }
-
-
-
- /**
- * Compute the argument of this complex number.
- * The argument is the angle phi between the positive real axis and
- * the point representing this number in the complex plane.
- * The value returned is between -PI (not inclusive)
- * and PI (inclusive), with negative values returned for numbers with
- * negative imaginary parts.
- * - * If either real or imaginary part (or both) is NaN, NaN is returned. - * Infinite parts are handled as {@code Math.atan2} handles them, - * essentially treating finite parts as zero in the presence of an - * infinite coordinate and returning a multiple of pi/4 depending on - * the signs of the infinite parts. - * See the javadoc for {@code Math.atan2} for full details. - * - * @return the argument of {@code this}. - */ - public double getArgument() { - return FastMath.atan2(getImaginary(), getReal()); - } - - /** - * Computes the n-th roots of this complex number. - * The nth roots are defined by the formula: - *
- *
- * zk = abs1/n (cos(phi + 2πk/n) + i (sin(phi + 2πk/n))
- *
- *
- * for {@code k=0, 1, ..., n-1}, where {@code abs} and {@code phi}
- * are respectively the {@link #abs() modulus} and
- * {@link #getArgument() argument} of this complex number.
- *
- * If one or both parts of this complex number is NaN, a list with just
- * one element, {@link #NaN} is returned.
- * if neither part is NaN, but at least one part is infinite, the result
- * is a one-element list containing {@link #INF}.
- *
- * @param n Degree of root.
- * @return a List of all {@code n}-th roots of {@code this}.
- * @throws NotPositiveException if {@code n <= 0}.
- * @since 2.0
- */
- public List
- * This class is a singleton.
- * We use here the Initialization On Demand Holder Idiom.