Java tutorial
/* * 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.complex; import java.io.Serializable; import java.util.ArrayList; import java.util.List; import org.apache.commons.math3.FieldElement; import org.apache.commons.math3.exception.NotPositiveException; import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.util.FastMath; import org.apache.commons.math3.util.MathUtils; import org.apache.commons.math3.util.Precision; /** * Representation of a Complex number, i.e. a number which has both a * real and imaginary part. * <br/> * 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: * <ul> * <li>{@code 1 + NaNi}</li> * <li>{@code NaN + i}</li> * <li>{@code NaN + NaNi}</li> * </ul> * Note that this is in contradiction with 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.math3.util.Precision#equals(double,double,int) * equals for primitive double} in {@link org.apache.commons.math3.util.Precision} * conforms with IEEE-754 while this class conforms with the standard behavior * for Java object types. * <br/> * Implements Serializable since 2.0 * */ public class Complex implements FieldElement<Complex>, Serializable { /** The square root of -1. A number representing "0.0 + 1.0i" */ public static final Complex I = new Complex(0.0, 1.0); // CHECKSTYLE: stop ConstantName /** A complex number representing "NaN + NaNi" */ public static final Complex NaN = new Complex(Double.NaN, Double.NaN); // CHECKSTYLE: resume ConstantName /** A complex number representing "+INF + INFi" */ public static final Complex INF = new Complex(Double.POSITIVE_INFINITY, Double.POSITIVE_INFINITY); /** A complex number representing "1.0 + 0.0i" */ public static final Complex ONE = new Complex(1.0, 0.0); /** A complex number representing "0.0 + 0.0i" */ public static final Complex ZERO = new Complex(0.0, 0.0); /** Serializable version identifier */ private static final long serialVersionUID = -6195664516687396620L; /** The imaginary part. */ private final double imaginary; /** The real part. */ private final double real; /** Record whether this complex number is equal to NaN. */ private final transient boolean isNaN; /** Record whether this complex number is infinite. */ private final transient boolean isInfinite; /** * Create a complex number given only the real part. * * @param real Real part. */ public Complex(double real) { this(real, 0.0); } /** * Create a complex number given the real and imaginary parts. * * @param real Real part. * @param imaginary Imaginary part. */ public Complex(double real, double imaginary) { this.real = real; this.imaginary = imaginary; isNaN = Double.isNaN(real) || Double.isNaN(imaginary); isInfinite = !isNaN && (Double.isInfinite(real) || Double.isInfinite(imaginary)); } /** * Return the absolute value of this complex number. * Returns {@code NaN} if either real or imaginary part is {@code NaN} * and {@code Double.POSITIVE_INFINITY} if neither part is {@code NaN}, * but at least one part is infinite. * * @return the absolute value. */ public double abs() { if (isNaN) { return Double.NaN; } if (isInfinite()) { return Double.POSITIVE_INFINITY; } if (FastMath.abs(real) < FastMath.abs(imaginary)) { if (imaginary == 0.0) { return FastMath.abs(real); } double q = real / imaginary; return FastMath.abs(imaginary) * FastMath.sqrt(1 + q * q); } else { if (real == 0.0) { return FastMath.abs(imaginary); } double q = imaginary / real; return FastMath.abs(real) * FastMath.sqrt(1 + q * q); } } /** * Returns a {@code Complex} whose value is * {@code (this + addend)}. * Uses the definitional formula * <pre> * <code> * (a + bi) + (c + di) = (a+c) + (b+d)i * </code> * </pre> * <br/> * 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}. */ 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); } /** * Return the conjugate of this complex number. * The conjugate of {@code a + bi} is {@code a - bi}. * <br/> * {@link #NaN} is returned if either the real or imaginary * part of this Complex number equals {@code Double.NaN}. * <br/> * 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 * <pre> * <code> * a + bi ac + bd + (bc - ad)i * ----------- = ------------------------- * c + di c<sup>2</sup> + d<sup>2</sup> * </code> * </pre> * but uses * <a href="http://doi.acm.org/10.1145/1039813.1039814"> * prescaling of operands</a> to limit the effects of overflows and * underflows in the computation. * <br/> * {@code Infinite} and {@code NaN} values are handled according to the * following rules, applied in the order presented: * <ul> * <li>If either {@code this} or {@code divisor} has a {@code NaN} value * in either part, {@link #NaN} is returned. * </li> * <li>If {@code divisor} equals {@link #ZERO}, {@link #NaN} is returned. * </li> * <li>If {@code this} and {@code divisor} are both infinite, * {@link #NaN} is returned. * </li> * <li>If {@code this} is finite (i.e., has no {@code Infinite} or * {@code NaN} parts) and {@code divisor} is infinite (one or both parts * infinite), {@link #ZERO} is returned. * </li> * <li>If {@code this} is infinite and {@code divisor} is finite, * {@code NaN} values are returned in the parts of the result if the * {@link java.lang.Double} rules applied to the definitional formula * force {@code NaN} results. * </li> * </ul> * * @param divisor Value by which this {@code Complex} is to be divided. * @return {@code this / divisor}. * @throws NullArgumentException if {@code divisor} is {@code null}. */ public Complex divide(Complex divisor) throws NullArgumentException { MathUtils.checkNotNull(divisor); if (isNaN || divisor.isNaN) { return NaN; } final double c = divisor.getReal(); final double d = divisor.getImaginary(); if (c == 0.0 && d == 0.0) { return NaN; } if (divisor.isInfinite() && !isInfinite()) { return ZERO; } if (FastMath.abs(c) < FastMath.abs(d)) { double q = c / d; double denominator = c * q + d; return createComplex((real * q + imaginary) / denominator, (imaginary * q - real) / denominator); } else { double q = d / c; double denominator = d * q + c; return createComplex((imaginary * q + real) / denominator, (imaginary - real * q) / denominator); } } /** * Returns a {@code Complex} whose value is {@code (this / divisor)}, * with {@code divisor} interpreted as a real number. * * @param divisor Value by which this {@code Complex} is to be divided. * @return {@code this / divisor}. * @see #divide(Complex) */ public Complex divide(double divisor) { if (isNaN || Double.isNaN(divisor)) { return NaN; } if (divisor == 0d) { return NaN; } if (Double.isInfinite(divisor)) { return !isInfinite() ? ZERO : NaN; } return createComplex(real / divisor, imaginary / divisor); } /** {@inheritDoc} */ public Complex reciprocal() { if (isNaN) { return NaN; } if (real == 0.0 && imaginary == 0.0) { return INF; } if (isInfinite) { return ZERO; } if (FastMath.abs(real) < FastMath.abs(imaginary)) { double q = real / imaginary; double scale = 1. / (real * q + imaginary); return createComplex(scale * q, -scale); } else { double q = imaginary / real; double scale = 1. / (imaginary * q + real); return createComplex(scale, -scale * q); } } /** * Test for equality with another object. * If both the real and imaginary parts of two complex numbers * are exactly the same, and neither is {@code Double.NaN}, the two * Complex objects are considered to be equal. * The behavior is the same as for JDK's {@link Double#equals(Object) * Double}: * <ul> * <li>All {@code NaN} values are considered to be equal, * i.e, if either (or both) real and imaginary parts of the complex * number are equal to {@code Double.NaN}, the complex number is equal * to {@code NaN}. * </li> * <li> * Instances constructed with different representations of zero (i.e. * either "0" or "-0") are <em>not</em> considered to be equal. * </li> * </ul> * * @param other Object to test for equality with this instance. * @return {@code true} if the objects are equal, {@code false} if object * is {@code null}, not an instance of {@code Complex}, or not equal to * this instance. */ @Override public boolean equals(Object other) { if (this == other) { return true; } if (other instanceof Complex) { Complex c = (Complex) other; if (c.isNaN) { return isNaN; } else { return MathUtils.equals(real, c.real) && MathUtils.equals(imaginary, c.imaginary); } } return false; } /** * Test for the floating-point equality between Complex objects. * It returns {@code true} if both arguments are equal or within the * range of allowed error (inclusive). * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). * @param maxUlps {@code (maxUlps - 1)} is the number of floating point * values between the real (resp. imaginary) parts of {@code x} and * {@code y}. * @return {@code true} if there are fewer than {@code maxUlps} floating * point values between the real (resp. imaginary) parts of {@code x} * and {@code y}. * * @see Precision#equals(double,double,int) * @since 3.3 */ public static boolean equals(Complex x, Complex y, int maxUlps) { return Precision.equals(x.real, y.real, maxUlps) && Precision.equals(x.imaginary, y.imaginary, maxUlps); } /** * Returns {@code true} iff the values are equal as defined by * {@link #equals(Complex,Complex,int) equals(x, y, 1)}. * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). * @return {@code true} if the values are equal. * * @since 3.3 */ public static boolean equals(Complex x, Complex y) { return equals(x, y, 1); } /** * Returns {@code true} if, both for the real part and for the imaginary * part, there is no double value strictly between the arguments or the * difference between them is within the range of allowed error * (inclusive). * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). * @param eps Amount of allowed absolute error. * @return {@code true} if the values are two adjacent floating point * numbers or they are within range of each other. * * @see Precision#equals(double,double,double) * @since 3.3 */ public static boolean equals(Complex x, Complex y, double eps) { return Precision.equals(x.real, y.real, eps) && Precision.equals(x.imaginary, y.imaginary, eps); } /** * Returns {@code true} if, both for the real part and for the imaginary * part, there is no double value strictly between the arguments or the * relative difference between them is smaller or equal to the given * tolerance. * * @param x First value (cannot be {@code null}). * @param y Second value (cannot be {@code null}). * @param eps Amount of allowed relative error. * @return {@code true} if the values are two adjacent floating point * numbers or they are within range of each other. * * @see Precision#equalsWithRelativeTolerance(double,double,double) * @since 3.3 */ public static boolean equalsWithRelativeTolerance(Complex x, Complex y, double eps) { return Precision.equalsWithRelativeTolerance(x.real, y.real, eps) && Precision.equalsWithRelativeTolerance(x.imaginary, y.imaginary, eps); } /** * Get a hashCode for the complex number. * Any {@code Double.NaN} value in real or imaginary part produces * the same hash code {@code 7}. * * @return a hash code value for this object. */ @Override public int hashCode() { if (isNaN) { return 7; } return 37 * (17 * MathUtils.hash(imaginary) + MathUtils.hash(real)); } /** * Access the imaginary part. * * @return the imaginary part. */ public double getImaginary() { return imaginary; } /** * Access the real part. * * @return the real part. */ public double getReal() { return real; } /** * Checks whether either or both parts of this complex number is * {@code NaN}. * * @return true if either or both parts of this complex number is * {@code NaN}; false otherwise. */ public boolean isNaN() { return isNaN; } /** * Checks whether either the real or imaginary part of this complex number * takes an infinite value (either {@code Double.POSITIVE_INFINITY} or * {@code Double.NEGATIVE_INFINITY}) and neither part * is {@code NaN}. * * @return true if one or both parts of this complex number are infinite * and neither part is {@code NaN}. */ public boolean isInfinite() { return isInfinite; } /** * Returns a {@code Complex} whose value is {@code this * factor}. * Implements preliminary checks for {@code NaN} and infinity followed by * the definitional formula: * <pre> * <code> * (a + bi)(c + di) = (ac - bd) + (ad + bc)i * </code> * </pre> * Returns {@link #NaN} if either {@code this} or {@code factor} has one or * more {@code NaN} parts. * <br/> * 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). * <br/> * 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}. */ 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) */ 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 equals {@code Double.NaN}. * * @return {@code -this}. */ 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 * <pre> * <code> * (a + bi) - (c + di) = (a-c) + (b-d)i * </code> * </pre> * 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}. */ 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 * <a href="http://mathworld.wolfram.com/InverseCosine.html" TARGET="_top"> * inverse cosine</a> of this complex number. * Implements the formula: * <pre> * <code> * acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>)))) * </code> * </pre> * 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 * <a href="http://mathworld.wolfram.com/InverseSine.html" TARGET="_top"> * inverse sine</a> of this complex number. * Implements the formula: * <pre> * <code> * asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz)) * </code> * </pre> * 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 * <a href="http://mathworld.wolfram.com/InverseTangent.html" TARGET="_top"> * inverse tangent</a> of this complex number. * Implements the formula: * <pre> * <code> * atan(z) = (i/2) log((i + z)/(i - z)) * </code> * </pre> * 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 * <a href="http://mathworld.wolfram.com/Cosine.html" TARGET="_top"> * cosine</a> * of this complex number. * Implements the formula: * <pre> * <code> * cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * cos(1 ± INFINITY i) = 1 ∓ INFINITY i * cos(±INFINITY + i) = NaN + NaN i * cos(±INFINITY ± INFINITY i) = NaN + NaN i * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/HyperbolicCosine.html" TARGET="_top"> * hyperbolic cosine</a> of this complex number. * Implements the formula: * <pre> * <code> * cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i} * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * cosh(1 ± INFINITY i) = NaN + NaN i * cosh(±INFINITY + i) = INFINITY ± INFINITY i * cosh(±INFINITY ± INFINITY i) = NaN + NaN i * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/ExponentialFunction.html" TARGET="_top"> * exponential function</a> of this complex number. * Implements the formula: * <pre> * <code> * exp(a + bi) = exp(a)cos(b) + exp(a)sin(b)i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#exp}, {@link FastMath#cos}, and * {@link FastMath#sin}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * 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 * </code> * </pre> * * @return <code><i>e</i><sup>this</sup></code>. * @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 * <a href="http://mathworld.wolfram.com/NaturalLogarithm.html" TARGET="_top"> * natural logarithm</a> of this complex number. * Implements the formula: * <pre> * <code> * log(a + bi) = ln(|a + bi|) + arg(a + bi)i * </code> * </pre> * 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). * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * 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. * <pre> * Examples: * <code> * 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 * </code> * </pre> * * @return the value <code>ln this</code>, 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: * <pre> * <code> * y<sup>x</sup> = exp(x·log(y)) * </code> * </pre> * where {@code exp} and {@code log} are {@link #exp} and * {@link #log}, respectively. * <br/> * 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 <code> this<sup>{@code x}</sup></code>. * @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 <code>this<sup>x</sup></code>. * @see #pow(Complex) */ public Complex pow(double x) { return this.log().multiply(x).exp(); } /** * Compute the * <a href="http://mathworld.wolfram.com/Sine.html" TARGET="_top"> * sine</a> * of this complex number. * Implements the formula: * <pre> * <code> * sin(a + bi) = sin(a)cosh(b) - cos(a)sinh(b)i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or {@code NaN} values returned in parts of the result. * <pre> * Examples: * <code> * sin(1 ± INFINITY i) = 1 ± INFINITY i * sin(±INFINITY + i) = NaN + NaN i * sin(±INFINITY ± INFINITY i) = NaN + NaN i * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/HyperbolicSine.html" TARGET="_top"> * hyperbolic sine</a> of this complex number. * Implements the formula: * <pre> * <code> * sinh(a + bi) = sinh(a)cos(b)) + cosh(a)sin(b)i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#cosh} and {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * sinh(1 ± INFINITY i) = NaN + NaN i * sinh(±INFINITY + i) = ± INFINITY + INFINITY i * sinh(±INFINITY ± INFINITY i) = NaN + NaN i * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/SquareRoot.html" TARGET="_top"> * square root</a> of this complex number. * Implements the following algorithm to compute {@code sqrt(a + bi)}: * <ol><li>Let {@code t = sqrt((|a| + |a + bi|) / 2)}</li> * <li><pre>if {@code a ≥ 0} return {@code t + (b/2t)i} * else return {@code |b|/2t + sign(b)t i }</pre></li> * </ol> * where <ul> * <li>{@code |a| = }{@link FastMath#abs}(a)</li> * <li>{@code |a + bi| = }{@link Complex#abs}(a + bi)</li> * <li>{@code sign(b) = }{@link FastMath#copySign(double,double) copySign(1d, b)} * </ul> * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * 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 * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/SquareRoot.html" TARGET="_top"> * square root</a> of <code>1 - this<sup>2</sup></code> for this complex * number. * Computes the result directly as * {@code sqrt(ONE.subtract(z.multiply(z)))}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * 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 of <code>1 - this<sup>2</sup></code>. * @since 1.2 */ public Complex sqrt1z() { return createComplex(1.0, 0.0).subtract(this.multiply(this)).sqrt(); } /** * Compute the * <a href="http://mathworld.wolfram.com/Tangent.html" TARGET="_top"> * tangent</a> of this complex number. * Implements the formula: * <pre> * <code> * tan(a + bi) = sin(2a)/(cos(2a)+cosh(2b)) + [sinh(2b)/(cos(2a)+cosh(2b))]i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and * {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * 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. * <pre> * Examples: * <code> * 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 * </code> * </pre> * * @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 * <a href="http://mathworld.wolfram.com/HyperbolicTangent.html" TARGET="_top"> * hyperbolic tangent</a> of this complex number. * Implements the formula: * <pre> * <code> * tan(a + bi) = sinh(2a)/(cosh(2a)+cos(2b)) + [sin(2b)/(cosh(2a)+cos(2b))]i * </code> * </pre> * where the (real) functions on the right-hand side are * {@link FastMath#sin}, {@link FastMath#cos}, {@link FastMath#cosh} and * {@link FastMath#sinh}. * <br/> * Returns {@link Complex#NaN} if either real or imaginary part of the * input argument is {@code NaN}. * <br/> * Infinite values in real or imaginary parts of the input may result in * infinite or NaN values returned in parts of the result. * <pre> * Examples: * <code> * 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 * </code> * </pre> * * @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. * <br/> * 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: * <pre> * <code> * z<sub>k</sub> = abs<sup>1/n</sup> (cos(phi + 2πk/n) + i (sin(phi + 2πk/n)) * </code> * </pre> * for <i>{@code k=0, 1, ..., n-1}</i>, where {@code abs} and {@code phi} * are respectively the {@link #abs() modulus} and * {@link #getArgument() argument} of this complex number. * <br/> * 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<Complex> of all {@code n}-th roots of {@code this}. * @throws NotPositiveException if {@code n <= 0}. * @since 2.0 */ public List<Complex> nthRoot(int n) throws NotPositiveException { if (n <= 0) { throw new NotPositiveException(LocalizedFormats.CANNOT_COMPUTE_NTH_ROOT_FOR_NEGATIVE_N, n); } final List<Complex> result = new ArrayList<Complex>(); if (isNaN) { result.add(NaN); return result; } if (isInfinite()) { result.add(INF); return result; } // nth root of abs -- faster / more accurate to use a solver here? final double nthRootOfAbs = FastMath.pow(abs(), 1.0 / n); // Compute nth roots of complex number with k = 0, 1, ... n-1 final double nthPhi = getArgument() / n; final double slice = 2 * FastMath.PI / n; double innerPart = nthPhi; for (int k = 0; k < n; k++) { // inner part final double realPart = nthRootOfAbs * FastMath.cos(innerPart); final double imaginaryPart = nthRootOfAbs * FastMath.sin(innerPart); result.add(createComplex(realPart, imaginaryPart)); innerPart += slice; } return result; } /** * Create a complex number given the real and imaginary parts. * * @param realPart Real part. * @param imaginaryPart Imaginary part. * @return a new complex number instance. * @since 1.2 * @see #valueOf(double, double) */ protected Complex createComplex(double realPart, double imaginaryPart) { return new Complex(realPart, imaginaryPart); } /** * Create a complex number given the real and imaginary parts. * * @param realPart Real part. * @param imaginaryPart Imaginary part. * @return a Complex instance. */ public static Complex valueOf(double realPart, double imaginaryPart) { if (Double.isNaN(realPart) || Double.isNaN(imaginaryPart)) { return NaN; } return new Complex(realPart, imaginaryPart); } /** * Create a complex number given only the real part. * * @param realPart Real part. * @return a Complex instance. */ public static Complex valueOf(double realPart) { if (Double.isNaN(realPart)) { return NaN; } return new Complex(realPart); } /** * Resolve the transient fields in a deserialized Complex Object. * Subclasses will need to override {@link #createComplex} to * deserialize properly. * * @return A Complex instance with all fields resolved. * @since 2.0 */ protected final Object readResolve() { return createComplex(real, imaginary); } /** {@inheritDoc} */ public ComplexField getField() { return ComplexField.getInstance(); } /** {@inheritDoc} */ @Override public String toString() { return "(" + real + ", " + imaginary + ")"; } }