complexutils.java

Apache的common math数学软件包

/*
 * 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.math.complex;

import org.apache.commons.math.util.MathUtils;

/**
 * Static implementations of common 
 * {@link org.apache.commons.math.complex.Complex}-valued functions.  Included
 * are trigonometric, exponential, log, power and square root functions.
 *<p>
 * Reference:
 * <ul>
 * <li><a href="http://myweb.lmu.edu/dmsmith/ZMLIB.pdf">
 * Multiple Precision Complex Arithmetic and Functions</a></li>
 * </ul>
 * See individual method javadocs for the computational formulas used.
 * In general, NaN values in either real or imaginary parts of input arguments
 * result in {@link Complex#NaN} returned.  Otherwise, infinite or NaN values
 * are returned as they arise in computing the real functions specified in the
 * computational formulas.  Null arguments result in NullPointerExceptions.
 *
 * @version $Revision: 615734 $ $Date: 2008-01-27 23:10:03 -0700 (Sun, 27 Jan 2008) $
 */
public class ComplexUtils {
    
    /**
     * Default constructor.
     */
    private ComplexUtils() {
        super();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/InverseCosine.html" TARGET="_top">
     * inverse cosine</a> for the given complex argument.
     * <p>
     * Implements the formula: <pre>
     * <code> acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))</code></pre>
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code> or infinite.
     * 
     * @param z the value whose inverse cosine is to be returned
     * @return the inverse cosine of <code>z</code>
     * @throws NullPointerException if <code>z</code> is null
     * @deprecated use Complex.acos()
     */
    public static Complex acos(Complex z) {
        return z.acos();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/InverseSine.html" TARGET="_top">
     * inverse sine</a> for the given complex argument.
     * <p>
     * Implements the formula: <pre>
     * <code> asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz)) </code></pre>
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code> or infinite.
     * 
     * @param z the value whose inverse sine is to be returned.
     * @return the inverse sine of <code>z</code>.
     * @throws NullPointerException if <code>z</code> is null
     * @deprecated use Complex.asin()
     */
    public static Complex asin(Complex z) {
        return z.asin();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/InverseTangent.html" TARGET="_top">
     * inverse tangent</a> for the given complex argument.
     * <p>
     * Implements the formula: <pre>
     * <code> atan(z) = (i/2) log((i + z)/(i - z)) </code></pre>
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code> or infinite. 
     * 
     * @param z the value whose inverse tangent is to be returned
     * @return the inverse tangent of <code>z</code>
     * @throws NullPointerException if <code>z</code> is null
     * @deprecated use Complex.atan()
     */
    public static Complex atan(Complex z) {
        return z.atan();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/Cosine.html" TARGET="_top">
     * cosine</a>
     * for the given complex argument.
     * <p>
     * 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 java.lang.Math#sin}, {@link java.lang.Math#cos}, 
     * {@link MathUtils#cosh} and {@link MathUtils#sinh}.
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code>.
     * <p>
     * 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 &plusmn; INFINITY i) = 1 &#x2213; INFINITY i
     * cos(&plusmn;INFINITY + i) = NaN + NaN i
     * cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
     * 
     * @param z the value whose cosine is to be returned
     * @return the cosine of <code>z</code>
     * @throws NullPointerException if <code>z</code> is null
     * @deprecated use Complex.cos()
     */
    public static Complex cos(Complex z) {
        return z.cos();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/HyperbolicCosine.html" TARGET="_top">
     * hyperbolic cosine</a> for the given complex argument.
     * <p>
     * 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 java.lang.Math#sin}, {@link java.lang.Math#cos}, 
     * {@link MathUtils#cosh} and {@link MathUtils#sinh}.
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code>.
     * <p>
     * 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 &plusmn; INFINITY i) = NaN + NaN i
     * cosh(&plusmn;INFINITY + i) = INFINITY &plusmn; INFINITY i
     * cosh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
     * <p>
     * Throws <code>NullPointerException</code> if z is null.
     * 
     * @param z the value whose hyperbolic cosine is to be returned.
     * @return the hyperbolic cosine of <code>z</code>.
     * @deprecated use Complex.cosh()
     */
    public static Complex cosh(Complex z) {
        return z.cosh();
    }
    
    /**
     * Compute the
     * <a href="http://mathworld.wolfram.com/ExponentialFunction.html" TARGET="_top">
     * exponential function</a> for the given complex argument.
     * <p>
     * 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 java.lang.Math#exp}, {@link java.lang.Math#cos}, and
     * {@link java.lang.Math#sin}.
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code>.
     * <p>
     * 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 &plusmn; INFINITY i) = NaN + NaN i
     * exp(INFINITY + i) = INFINITY + INFINITY i
     * exp(-INFINITY + i) = 0 + 0i
     * exp(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
     * <p>
     * Throws <code>NullPointerException</code> if z is null.
     * 
     * @param z the value
     * @return <i>e</i><sup><code>z</code></sup>
     * @deprecated use Complex.exp()
     */
    public static Complex exp(Complex z) {
        return z.exp();
    }
    
    /**
     * Compute the 
     * <a href="http://mathworld.wolfram.com/NaturalLogarithm.html" TARGET="_top">
     * natural logarithm</a> for the given complex argument.
     * <p>
     * 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 java.lang.Math#log},
     * <code>|a + bi|</code> is the modulus, {@link Complex#abs},  and
     * <code>arg(a + bi) = {@link java.lang.Math#atan2}(b, a)</code>
     * <p>
     * Returns {@link Complex#NaN} if either real or imaginary part of the 
     * input argument is <code>NaN</code>.
     * <p>
     * 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 &plusmn; INFINITY i) = INFINITY &plusmn; (&pi;/2)i
     * log(INFINITY + i) = INFINITY + 0i
     * log(-INFINITY + i) = INFINITY + &pi;i
     * log(INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (&pi;/4)i
     * log(-INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (3&pi;/4)i
     * log(0 + 0i) = -INFINITY + 0i
     * </code></pre>
     * Throws <code>NullPointerException</code> if z is null.
     * 
     * @param z the value.
     * @return ln <code>z</code>.
     * @deprecated use Complex.log()
     */
    public static Complex log(Complex z) {
        return z.log();
    }
    
    /**
     * Creates a complex number from the given polar representation.
     * <p>
     * The value returned is <code>r&middot;e<sup>i&middot;theta</sup></code>,