View Javadoc

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  
18  package org.apache.commons.math.complex;
19  
20  import org.apache.commons.math.MathRuntimeException;
21  
22  /**
23   * Static implementations of common 
24   * {@link org.apache.commons.math.complex.Complex} utilities functions.
25   *
26   * @version $Revision: 772119 $ $Date: 2009-05-06 05:43:28 -0400 (Wed, 06 May 2009) $
27   */
28  public class ComplexUtils {
29      
30      /**
31       * Default constructor.
32       */
33      private ComplexUtils() {
34          super();
35      }
36      
37      /**
38       * Creates a complex number from the given polar representation.
39       * <p>
40       * The value returned is <code>r&middot;e<sup>i&middot;theta</sup></code>,
41       * computed as <code>r&middot;cos(theta) + r&middot;sin(theta)i</code></p>
42       * <p>
43       * If either <code>r</code> or <code>theta</code> is NaN, or 
44       * <code>theta</code> is infinite, {@link Complex#NaN} is returned.</p>
45       * <p>
46       * If <code>r</code> is infinite and <code>theta</code> is finite, 
47       * infinite or NaN values may be returned in parts of the result, following
48       * the rules for double arithmetic.<pre>
49       * Examples: 
50       * <code>
51       * polar2Complex(INFINITY, &pi;/4) = INFINITY + INFINITY i
52       * polar2Complex(INFINITY, 0) = INFINITY + NaN i
53       * polar2Complex(INFINITY, -&pi;/4) = INFINITY - INFINITY i
54       * polar2Complex(INFINITY, 5&pi;/4) = -INFINITY - INFINITY i </code></pre></p>
55       * 
56       * @param r the modulus of the complex number to create
57       * @param theta  the argument of the complex number to create
58       * @return <code>r&middot;e<sup>i&middot;theta</sup></code>
59       * @throws IllegalArgumentException  if r is negative
60       * @since 1.1
61       */
62      public static Complex polar2Complex(double r, double theta) {
63          if (r < 0) {
64              throw MathRuntimeException.createIllegalArgumentException(
65                    "negative complex module {0}", r);
66          }
67          return new Complex(r * Math.cos(theta), r * Math.sin(theta));
68      }
69      
70  }