Multimodule project setup. Created "core", "complex" and "quaternion" modules.
Project: http://git-wip-us.apache.org/repos/asf/commons-numbers/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-numbers/commit/c4541327 Tree: http://git-wip-us.apache.org/repos/asf/commons-numbers/tree/c4541327 Diff: http://git-wip-us.apache.org/repos/asf/commons-numbers/diff/c4541327 Branch: refs/heads/multimodule Commit: c45413279a7e1eec230516ec1f8efd5456c6215e Parents: a752ab8 Author: Gilles Sadowski <[email protected]> Authored: Wed Jan 18 14:22:45 2017 +0100 Committer: Gilles Sadowski <[email protected]> Committed: Wed Jan 18 14:22:45 2017 +0100 ---------------------------------------------------------------------- NOTICE.txt | 2 +- README.md | 23 +- commons-numbers-complex/LICENSE.txt | 201 +++ commons-numbers-complex/NOTICE.txt | 6 + commons-numbers-complex/README.md | 98 ++ commons-numbers-complex/pom.xml | 61 + .../apache/commons/numbers/complex/Complex.java | 1369 ++++++++++++++++ .../commons/numbers/complex/ComplexUtils.java | 1430 +++++++++++++++++ .../commons/numbers/complex/Precision.java | 128 ++ .../commons/numbers/complex/RootsOfUnity.java | 116 ++ .../commons/numbers/complex/package-info.java | 20 + .../commons/numbers/complex/ComplexTest.java | 1477 ++++++++++++++++++ .../numbers/complex/ComplexUtilsTest.java | 475 ++++++ .../numbers/complex/RootsOfUnityTest.java | 84 + .../commons/numbers/complex/TestUtils.java | 409 +++++ commons-numbers-core/LICENSE.txt | 201 +++ commons-numbers-core/NOTICE.txt | 6 + commons-numbers-core/README.md | 98 ++ commons-numbers-core/pom.xml | 46 + .../apache/commons/numbers/core/Precision.java | 598 +++++++ .../commons/numbers/core/PrecisionTest.java | 547 +++++++ .../apache/commons/numbers/core/TestUtils.java | 320 ++++ commons-numbers-quaternion/LICENSE.txt | 201 +++ commons-numbers-quaternion/NOTICE.txt | 6 + commons-numbers-quaternion/README.md | 98 ++ commons-numbers-quaternion/pom.xml | 53 + .../commons/numbers/quaternion/Quaternion.java | 455 ++++++ .../numbers/quaternion/package-info.java | 20 + .../numbers/quaternion/QuaternionTest.java | 456 ++++++ pom.xml | 408 ++--- src/main/resources/checkstyle/checkstyle.xml | 202 +++ .../resources/checkstyle/license-header.txt | 16 + src/main/resources/clirr/clirr-ignored.xml | 21 + .../findbugs/findbugs-exclude-filter.xml | 28 + src/main/resources/pmd/pmd-ruleset.xml | 57 + 35 files changed, 9530 insertions(+), 206 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/NOTICE.txt ---------------------------------------------------------------------- diff --git a/NOTICE.txt b/NOTICE.txt index d22df2a..ea6ae07 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,4 +1,4 @@ -Apache Commons Math +Apache Commons Numbers Copyright 2001-2016 The Apache Software Foundation This product includes software developed at http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 905ee17..e0754e0 100644 --- a/README.md +++ b/README.md @@ -40,33 +40,28 @@ | | +======================================================================+ ---> -Apache Commons Complex -====================== +Apache Commons Numbers +=================== -[](https://travis-ci.org/apache/commons-complex) -[](https://coveralls.io/github/apache/commons-complex?branch=master) -[](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-complex/) -[](http://www.apache.org/licenses/LICENSE-2.0.html) - -The Apache Commons Complex project provides self-contained components addressing the most common practical problems involving Java computing with complex numbers. +The Apache Commons Numbers project provides number types and utilities. Documentation ------------- -More information can be found on the [homepage](https://commons.apache.org/proper/commons-complex). -The [JavaDoc](https://commons.apache.org/proper/commons-complex/apidocs) can be browsed. -Questions related to the usage of Apache Commons Math should be posted to the [user mailing list][ml]. +More information can be found on the [homepage](https://commons.apache.org/proper/commons-numbers). +The [JavaDoc](https://commons.apache.org/proper/commons-numbers/javadocs/api-release) can be browsed. +Questions related to the usage of Apache Commons Numbers should be posted to the [user mailing list][ml]. Where can I get the latest release? ----------------------------------- -You can download source and binaries from our [download page](https://commons.apache.org/proper/commons-complex/download_complex.cgi). +You can download source and binaries from our [download page](https://commons.apache.org/proper/commons-numbers/download_numbers.cgi). Alternatively you can pull it from the central Maven repositories: ```xml <dependency> <groupId>org.apache.commons</groupId> - <artifactId>commons-complex</artifactId> + <artifactId>commons-numbers-parent</artifactId> <version>1.0</version> </dependency> ``` @@ -90,7 +85,7 @@ Code is under the [Apache Licence v2](https://www.apache.org/licenses/LICENSE-2. Donations --------- -You like Apache Commons Math? Then [donate back to the ASF](https://www.apache.org/foundation/contributing.html) to support the development. +You like Apache Commons Numbers? Then [donate back to the ASF](https://www.apache.org/foundation/contributing.html) to support the development. Additional Resources -------------------- http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/commons-numbers-complex/LICENSE.txt ---------------------------------------------------------------------- diff --git a/commons-numbers-complex/LICENSE.txt b/commons-numbers-complex/LICENSE.txt new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/commons-numbers-complex/LICENSE.txt @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed 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. http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/commons-numbers-complex/NOTICE.txt ---------------------------------------------------------------------- diff --git a/commons-numbers-complex/NOTICE.txt b/commons-numbers-complex/NOTICE.txt new file mode 100644 index 0000000..ea6ae07 --- /dev/null +++ b/commons-numbers-complex/NOTICE.txt @@ -0,0 +1,6 @@ +Apache Commons Numbers +Copyright 2001-2016 The Apache Software Foundation + +This product includes software developed at +The Apache Software Foundation (http://www.apache.org/). + http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/commons-numbers-complex/README.md ---------------------------------------------------------------------- diff --git a/commons-numbers-complex/README.md b/commons-numbers-complex/README.md new file mode 100644 index 0000000..582b7ce --- /dev/null +++ b/commons-numbers-complex/README.md @@ -0,0 +1,98 @@ +<!--- + 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. +--> +<!--- + +======================================================================+ + |**** ****| + |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****| + |**** DO NOT EDIT DIRECTLY ****| + |**** ****| + +======================================================================+ + | TEMPLATE FILE: readme-md-template.md | + | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates | + +======================================================================+ + | | + | 1) Re-generate using: mvn commons:readme-md | + | | + | 2) Set the following properties in the component's pom: | + | - commons.componentid (required, alphabetic, lower case) | + | - commons.release.version (required) | + | | + | 3) Example Properties | + | | + | <properties> | + | <commons.componentid>math</commons.componentid> | + | <commons.release.version>1.2</commons.release.version> | + | </properties> | + | | + +======================================================================+ +---> +Apache Commons Numbers Complex +=================== + +Complex numbers. + +Documentation +------------- + +More information can be found on the [homepage](https://commons.apache.org/proper/commons-numbers). +The [JavaDoc](https://commons.apache.org/proper/commons-numbers/javadocs/api-release) can be browsed. +Questions related to the usage of Apache Commons Numbers Complex should be posted to the [user mailing list][ml]. + +Where can I get the latest release? +----------------------------------- +You can download source and binaries from our [download page](https://commons.apache.org/proper/commons-numbers/download_numbers.cgi). + +Alternatively you can pull it from the central Maven repositories: + +```xml +<dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-numbers-complex</artifactId> + <version>1.0</version> +</dependency> +``` + +Contributing +------------ + +We accept PRs via github. The [developer mailing list][ml] is the main channel of communication for contributors. +There are some guidelines which will make applying PRs easier for us: ++ No tabs! Please use spaces for indentation. ++ Respect the code style. ++ Create minimal diffs - disable on save actions like reformat source code or organize imports. If you feel the source code should be reformatted create a separate PR for this change. ++ Provide JUnit tests for your changes and make sure your changes don't break any existing tests by running ```mvn clean test```. + +If you plan to contribute on a regular basis, please consider filing a [contributor license agreement](https://www.apache.org/licenses/#clas). +You can learn more about contributing via GitHub in our [contribution guidelines](CONTRIBUTING.md). + +License +------- +Code is under the [Apache Licence v2](https://www.apache.org/licenses/LICENSE-2.0.txt). + +Donations +--------- +You like Apache Commons Numbers Complex? Then [donate back to the ASF](https://www.apache.org/foundation/contributing.html) to support the development. + +Additional Resources +-------------------- + ++ [Apache Commons Homepage](https://commons.apache.org/) ++ [Apache Bugtracker (JIRA)](https://issues.apache.org/jira/) ++ [Apache Commons Twitter Account](https://twitter.com/ApacheCommons) ++ #apachecommons IRC channel on freenode.org + +[ml]:https://commons.apache.org/mail-lists.html http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/commons-numbers-complex/pom.xml ---------------------------------------------------------------------- diff --git a/commons-numbers-complex/pom.xml b/commons-numbers-complex/pom.xml new file mode 100644 index 0000000..735348f --- /dev/null +++ b/commons-numbers-complex/pom.xml @@ -0,0 +1,61 @@ +<?xml version="1.0"?> +<!-- + 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. +--> +<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"; + xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";> + <modelVersion>4.0.0</modelVersion> + + <parent> + <groupId>org.apache.commons</groupId> + <artifactId>commons-numbers-parent</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + + <groupId>org.apache.commons</groupId> + <artifactId>commons-numbers-complex</artifactId> + <version>1.0-SNAPSHOT</version> + <name>Apache Commons Numbers Complex</name> + + <description>Complex numbers.</description> + + <properties> + <!-- This value must reflect the current name of the base package. --> + <commons.osgi.symbolicName>org.apache.commons.numbers.complex</commons.osgi.symbolicName> + <!-- OSGi --> + <commons.osgi.export>org.apache.commons.numbers.complex</commons.osgi.export> + <!-- Workaround to avoid duplicating config files. --> + <numbers.parent.dir>${basedir}/..</numbers.parent.dir> + </properties> + + <dependencies> + <dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-numbers-core</artifactId> + <version>1.0-SNAPSHOT</version> + </dependency> + + <dependency> + <groupId>org.apache.commons</groupId> + <artifactId>commons-math3</artifactId> + <version>3.6.1</version> + <scope>test</scope> + </dependency> + + </dependencies> + +</project> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/c4541327/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java ---------------------------------------------------------------------- diff --git a/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java new file mode 100644 index 0000000..9581f81 --- /dev/null +++ b/commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/Complex.java @@ -0,0 +1,1369 @@ +/* + * 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.numbers.complex; + +import java.io.Serializable; +import java.util.ArrayList; +import java.util.List; + +/** + * Representation of a Complex number, i.e. a number which has both a + * real and imaginary part. + * <p> + * 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><p> + * 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.complex.util.Precision#equals(double,double,int) + * equals for primitive double} in {@link org.apache.commons.numbers.complex.util.Precision} + * conforms with IEEE-754 while this class conforms with the standard behavior + * for Java object types.</p> + * + */ +public class Complex implements 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 (Math.abs(real) < Math.abs(imaginary)) { + if (imaginary == 0.0) { + return Math.abs(real); + } + double q = real / imaginary; + return Math.abs(imaginary) * Math.sqrt(1 + q * q); + } else { + if (real == 0.0) { + return Math.abs(imaginary); + } + double q = imaginary / real; + return Math.abs(real) * Math.sqrt(1 + q * q); + } + } + + /** + * Returns a {@code Complex} whose value is + * {@code (this + addend)}. + * Uses the definitional formula + * <p> + * {@code (a + bi) + (c + di) = (a+c) + (b+d)i} + * </p> + * 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}. + */ + public Complex add(Complex addend) { + 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}. + * <p> + * {@link #NaN} is returned if either the real or imaginary + * part of this Complex number equals {@code Double.NaN}. + * </p><p> + * 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}. + * </p> + * @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. + * <p> + * {@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}. + */ + public Complex divide(Complex divisor) { + 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 (Math.abs(c) < Math.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 (Math.abs(real) < Math.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 equals(real, c.real) && + 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). Returns {@code false} if either of the arguments is NaN. + * + * @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. Returns {@code false} if either of the arguments is NaN. + * + * @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 * hash(imaginary) + + 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: + * <p> + * {@code (a + bi)(c + di) = (ac - bd) + (ad + bc)i} + * </p> + * Returns {@link #NaN} if either {@code this} or {@code factor} has one or + * more {@code NaN} parts. + * <p> + * 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). + * </p><p> + * Returns finite values in components of the result per the definitional + * formula in all remaining cases.</p> + * + * @param factor value to be multiplied by this {@code Complex}. + * @return {@code this * factor}. + */ + public Complex multiply(Complex factor) { + 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 is {@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 + * <p> + * {@code (a + bi) - (c + di) = (a-c) + (b-d)i} + * </p> + * 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}. + */ + public Complex subtract(Complex subtrahend) { + 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: + * <p> + * {@code acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))} + * </p> + * 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: + * <p> + * {@code asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz))} + * </p><p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN} or infinite.</p> + * + * @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: + * <p> + * {@code atan(z) = (i/2) log((i + z)/(i - z))} + * </p><p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN} or infinite.</p> + * + * @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: + * <p> + * {@code cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i} + * </p><p> + * where the (real) functions on the right-hand side are + * {@link Math#sin}, {@link Math#cos}, + * {@link Math#cosh} and {@link Math#sinh}. + * </p><p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </p><p> + * Infinite values in real or imaginary parts of the input may result in + * infinite or NaN values returned in parts of the result.</p> + * <pre> + * Examples: + * <code> + * cos(1 ± INFINITY i) = 1 \u2213 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(Math.cos(real) * Math.cosh(imaginary), + -Math.sin(real) * Math.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 Math#sin}, {@link Math#cos}, + * {@link Math#cosh} and {@link Math#sinh}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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 ± 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(Math.cosh(real) * Math.cos(imaginary), + Math.sinh(real) * Math.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 Math#exp}, {@link Math#cos}, and + * {@link Math#sin}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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 ± 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 = Math.exp(real); + return createComplex(expReal * Math.cos(imaginary), + expReal * Math.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 Math#log}, + * {@code |a + bi|} is the modulus, {@link Complex#abs}, and + * {@code arg(a + bi) = }{@link Math#atan2}(b, a). + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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 ± 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(Math.log(abs()), + Math.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. + * <p> + * 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}.</p> + * + * @param x exponent to which this {@code Complex} is to be raised. + * @return <code> this<sup>x</sup></code>. + * @since 1.2 + */ + public Complex pow(Complex x) { + checkNotNull(x); + if (real == 0 && imaginary == 0) { + if (x.real > 0 && x.imaginary == 0) { + // 0 raised to positive number is 0 + return ZERO; + } else { + // 0 raised to anything else is NaN + return NaN; + } + } + 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) { + if (real == 0 && imaginary == 0) { + if (x > 0) { + // 0 raised to positive number is 0 + return ZERO; + } else { + // 0 raised to anything else is NaN + return NaN; + } + } + 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 Math#sin}, {@link Math#cos}, + * {@link Math#cosh} and {@link Math#sinh}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </p><p> + * 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(Math.sin(real) * Math.cosh(imaginary), + Math.cos(real) * Math.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 Math#sin}, {@link Math#cos}, + * {@link Math#cosh} and {@link Math#sinh}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </p><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> + * 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(Math.sinh(real) * Math.cos(imaginary), + Math.cosh(real) * Math.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 Math#abs}(a)</li> + * <li>{@code |a + bi| = }{@link Complex#abs}(a + bi)</li> + * <li>{@code sign(b) = }{@link Math#copySign(double,double) copySign(1d, b)} + * </ul> + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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> + * 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 = Math.sqrt((Math.abs(real) + abs()) / 2.0); + if (real >= 0.0) { + return createComplex(t, imaginary / (2.0 * t)); + } else { + return createComplex(Math.abs(imaginary) / (2.0 * t), + Math.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)))}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </p> + * 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 Math#sin}, {@link Math#cos}, {@link Math#cosh} and + * {@link Math#sinh}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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> + * 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 = Math.cos(real2) + Math.cosh(imaginary2); + + return createComplex(Math.sin(real2) / d, + Math.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 Math#sin}, {@link Math#cos}, {@link Math#cosh} and + * {@link Math#sinh}. + * <p> + * Returns {@link Complex#NaN} if either real or imaginary part of the + * input argument is {@code NaN}. + * </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> + * 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 = Math.cosh(real2) + Math.cos(imaginary2); + + return createComplex(Math.sinh(real2) / d, + Math.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. + * <p> + * 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 Math.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. + * <p> + * 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}. + * @since 2.0 + */ + public List<Complex> nthRoot(int n) { + + if (n <= 0) { + throw new RuntimeException("cannot compute nth root for null or negative n: {0}"); + } + + 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 = Math.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 * Math.PI / n; + double innerPart = nthPhi; + for (int k = 0; k < n ; k++) { + // inner part + final double realPart = nthRootOfAbs * Math.cos(innerPart); + final double imaginaryPart = nthRootOfAbs * Math.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} */ + @Override + public String toString() { + return "(" + real + ", " + imaginary + ")"; + } + + /** + * Checks that an object is not null. + * + * @param o Object to be checked. + */ + private static void checkNotNull(Object o) { + if (o == null) { + throw new RuntimeException("Null Argument to Complex Method"); + } + } + + /** + * Returns {@code true} if the values are equal according to semantics of + * {@link Double#equals(Object)}. + * + * @param x Value + * @param y Value + * @return {@code new Double(x).equals(new Double(y))} + */ + private static boolean equals(double x, double y) { + return new Double(x).equals(new Double(y)); + } + + /** + * Returns {@code true} if there is no double value strictly between the + * arguments or the difference between them is within the range of allowed + * error (inclusive). Returns {@code false} if either of the arguments + * is NaN. + * + * @param x First value. + * @param y Second value. + * @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. + */ + public static boolean equals(double x, double y, double eps) { + return equals(x, y, 1) || Math.abs(y - x) <= eps; + } + + + /** + * Returns {@code true} if there is no double value strictly between the + * arguments or the relative difference between them is less than or equal + * to the given tolerance. Returns {@code false} if either of the arguments + * is NaN. + * + * @param x First value. + * @param y Second value. + * @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. + * @since 3.1 + */ + public static boolean equalsWithRelativeTolerance(double x, double y, double eps) { + if (equals(x, y, 1)) { + return true; + } + + final double absoluteMax = Math.max(Math.abs(x), Math.abs(y)); + final double relativeDifference = Math.abs((x - y) / absoluteMax); + + return relativeDifference <= eps; + } + + /** + * Returns an integer hash code representing the given double value. + * + * @param value the value to be hashed + * @return the hash code + */ + public static int hash(double value) { + return new Double(value).hashCode(); + } + +} +
