Skip to content

Commit

Permalink
NUMBERS-188 javadoc edits
Browse files Browse the repository at this point in the history
  • Loading branch information
@sumanth-rajkumar
sumanth-rajkumar committed Jul 19, 2022
1 parent c9d5cb4 commit 142fa7b
Show file tree
Hide file tree
Showing 7 changed files with 102 additions and 123 deletions.
10 changes: 5 additions & 5 deletions ...ns-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexFunctions.java
View file
Expand Up @@ -209,7 +209,7 @@ public static boolean isInfinite(double real, double imaginary) {
* @param real Real part \( a \) of the complex number \( (a +ib \).
* @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \).
* @param action Consumer for the natural logarithm of the complex number.
* @param <R> the object taken by the supplied action.
* @param <R> the return type of the supplied action.
* @return the object returned by the supplied action.
* @see Math#log(double)
* @see <a href="http://functions.wolfram.com/ElementaryFunctions/Log/">Log</a>
Expand Down Expand Up @@ -237,7 +237,7 @@ public static <R> R log(double real, double imaginary, ComplexSink<R> action) {
* @param real Real part \( a \) of the complex number \( (a +ib \).
* @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \).
* @param action Consumer for the natural logarithm of the complex number.
* @param <R> the object taken by the supplied action.
* @param <R> the return type of the supplied action.
* @return the object returned by the supplied action.
* @see Math#log10(double)
*/
Expand All @@ -263,7 +263,7 @@ public static <R> R log10(double real, double imaginary, ComplexSink<R> action)
* @param real Real part \( a \) of the complex number \( (a +ib \).
* @param imaginary Imaginary part \( b \) of the complex number \( (a +ib \).
* @param action Consumer for the natural logarithm of the complex number.
* @param <R> the object taken by the supplied action.
* @param <R> the return type of the supplied action.
* @return the object returned by the supplied action.
*/
private static <R> R log(DoubleUnaryOperator log,
Expand Down Expand Up @@ -666,7 +666,7 @@ static double x2y2m1(double x, double y) {
* @see <a href="https://doi.org/10.1007/BF01397083">
* Dekker (1971) A floating-point technique for extending the available precision</a>
*/
static double splitHigh(double a) {
private static double splitHigh(double a) {
final double c = MULTIPLIER * a;
return c - (c - a);
}
Expand All @@ -687,7 +687,7 @@ static double splitHigh(double a) {
* @see <a href="http://www-2.cs.cmu.edu/afs/cs/project/quake/public/papers/robust-arithmetic.ps">
* Shewchuk (1997) Theorum 18</a>
*/
static double squareLow(double low, double high, double square) {
private static double squareLow(double low, double high, double square) {
final double lh = low * high;
return low * low - (((square - high * high) - lh) - lh);
}
Expand Down
2 changes: 1 addition & 1 deletion commons-numbers-complex/src/main/java/org/apache/commons/numbers/complex/ComplexSink.java
View file
Expand Up @@ -18,7 +18,7 @@
package org.apache.commons.numbers.complex;

/**
* Represents a data sink for a complex number \( (a + i b) \)
* Represents a data sink for a complex number \( (a + i b) \).
* Operations return a result of type {@code R}.
*
* <p>This is a functional interface whose functional method is
Expand Down
20 changes: 9 additions & 11 deletions commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CReferenceTest.java
View file
Expand Up @@ -157,10 +157,10 @@ static void assertEquals(Supplier<String> msg, double expected, double actual, l
* Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* complex real and imaginary parts.
*
* @param c Input number.
* @param name the operation name
* @param operation1 the operation on the Complex object
* @param operation2 the operation on the complex real and imaginary parts
* @param c Input complex number.
* @param name Operation name.
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param expected Expected result.
*/
static void assertComplex(Complex c,
Expand All @@ -169,12 +169,10 @@ static void assertComplex(Complex c,
ComplexUnaryOperator<ComplexNumber> operation2,
Complex expected, long maxUlps) {

final Complex z = operation1.apply(c);
final Complex z = TestUtils.assertSame(c, operation1, operation2, name);

assertEquals(() -> "UnaryOperator " + name + "(" + c + "): real", expected.real(), z.real(), maxUlps);
assertEquals(() -> "UnaryOperator " + name + "(" + c + "): imaginary", expected.imag(), z.imag(), maxUlps);

TestUtils.assertSame(c, operation1, operation2, name);
}

/**
Expand Down Expand Up @@ -259,10 +257,10 @@ private static void assertBiOperation(String name,
/**
* Assert the operation using the data loaded from test resources.
*
* @param name the operation name
* @param operation1 the operation on the Complex object
* @param operation2 the operation on the complex real and imaginary parts
* @param maxUlps the maximum units of least precision between the two values
* @param name Operation name
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param maxUlps Maximum units of least precision between the two values.
*/
private static void assertOperation(String name,
UnaryOperator<Complex> operation1,
Expand Down
134 changes: 66 additions & 68 deletions commons-numbers-complex/src/test/java/org/apache/commons/numbers/complex/CStandardTest.java
View file
Expand Up @@ -309,7 +309,7 @@ private static void assertConjugateEquality(Complex z,
*
* <p>The results must be binary equal. This includes the sign of zero.
*
* Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* <p>Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* complex real and imaginary parts.
*
* <h2>ISO C99 equalities</h2>
Expand All @@ -330,10 +330,13 @@ private static void assertConjugateEquality(Complex z,
* <li>sinh(inf, nan)
* </ul>
*
* @param operation the operation
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param name Operation name.
*/
private static void assertConjugateEquality(UnaryOperator<Complex> operation,
ComplexUnaryOperator<ComplexNumber> operation2) {
private static void assertConjugateEquality(UnaryOperator<Complex> operation1,
ComplexUnaryOperator<ComplexNumber> operation2,
String name) {
// Edge cases. Inf/NaN are specifically handled in the C99 test cases
// but are repeated here to enforce the conjugate equality even when the C99
// standard does not specify a sign. This may be revised in the future.
Expand All @@ -343,7 +346,7 @@ private static void assertConjugateEquality(UnaryOperator<Complex> operation,
for (final double y : parts) {
// No conjugate for imaginary NaN
if (!Double.isNaN(y)) {
assertConjugateEquality(complex(x, y), operation, operation2, UnspecifiedSign.NONE);
assertConjugateEquality(complex(x, y), operation1, operation2, UnspecifiedSign.NONE, name);
}
}
}
Expand All @@ -352,7 +355,7 @@ private static void assertConjugateEquality(UnaryOperator<Complex> operation,
for (int i = 0; i < 100; i++) {
final double x = next(rng);
final double y = next(rng);
assertConjugateEquality(complex(x, y), operation, operation2, UnspecifiedSign.NONE);
assertConjugateEquality(complex(x, y), operation1, operation2, UnspecifiedSign.NONE, name);
}
}

Expand All @@ -366,25 +369,23 @@ private static void assertConjugateEquality(UnaryOperator<Complex> operation,
* <p>The results must be binary equal; the sign of the complex number is first processed
* using the provided sign specification.
*
* Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* <p>Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* complex real and imaginary parts.
*
* @param z the complex number
* @param operation1 the operation on the Complex object
* @param operation2 the operation on the complex real and imaginary parts
* @param z Input complex number.
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param sign the sign specification
* @param name Operation name.
*/
private static void assertConjugateEquality(Complex z,
UnaryOperator<Complex> operation1,
ComplexUnaryOperator<ComplexNumber> operation2,
UnspecifiedSign sign) {
UnspecifiedSign sign, String name) {

final Complex zConj = z.conj();
final Complex c1 = operation1.apply(zConj);
final Complex c2 = operation1.apply(z).conj();

final ComplexNumber cn1 = operation2.apply(zConj.getReal(), zConj.getImaginary(), ComplexNumber::new);
final ComplexNumber cn2 = operation2.apply(z.getReal(), z.getImaginary(), ComplexNumber::conj);
final Complex c1 = TestUtils.assertSame(zConj, operation1, operation2, name);
final Complex c2 = TestUtils.assertSame(z, operation1, operation2, name).conj();

final Complex t1 = sign.removeSign(c1);
final Complex t2 = sign.removeSign(c2);
Expand All @@ -396,9 +397,6 @@ private static void assertConjugateEquality(Complex z,
String.format("Conjugate equality failed (z=%s). Expected: %s but was: %s (Unspecified sign = %s)",
z, c1, c2, sign));
}

TestUtils.assertSame(c1, cn1);
TestUtils.assertSame(c2, cn2);
}

/**
Expand Down Expand Up @@ -619,19 +617,20 @@ private static void assertComplex(Complex z,
*
* <p>The results must be binary equal. This includes the sign of zero.
*
* Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* <p>Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* complex real and imaginary parts.
*
* @param z the complex
* @param operation1 the operation on the Complex object
* @param operation2 the operation on the complex real and imaginary parts
* @param expected the expected
* @param z Input complex number.
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param expected Expected complex number.
* @param name Operation name.
*/
private static void assertComplex(Complex z,
UnaryOperator<Complex> operation1,
ComplexUnaryOperator<ComplexNumber> operation2,
Complex expected) {
assertComplex(z, operation1, operation2, expected, FunctionType.NONE, UnspecifiedSign.NONE);
Complex expected, String name) {
assertComplex(z, operation1, operation2, expected, FunctionType.NONE, UnspecifiedSign.NONE, name);
}

/**
Expand All @@ -655,31 +654,32 @@ private static void assertComplex(Complex z,
* <p>The results must be binary equal; the sign of the complex number is first processed
* using the provided sign specification.
*
* Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* <p>Assert the operation on the complex number is <em>exactly</em> equal to the operation on
* complex real and imaginary parts.
*
* @param z the complex
* @param operation the operation on the Complex object
* @param operation2 the operation on the complex real and imaginary parts
* @param expected the expected
* @param z Input complex number.
* @param operation1 Operation on the Complex object.
* @param operation2 Operation on the complex real and imaginary parts.
* @param expected Expected complex number.
* @param type the type
* @param sign the sign specification
* @param name Operation name.
*/
private static void assertComplex(Complex z,
UnaryOperator<Complex> operation,
UnaryOperator<Complex> operation1,
ComplexUnaryOperator<ComplexNumber> operation2,
Complex expected,
FunctionType type,
UnspecifiedSign sign) {
UnspecifiedSign sign,
String name) {

// Developer note: Set the sign specification to UnspecifiedSign.NONE
// to see which equalities fail. They should be for input defined
// in ISO C99 with an unspecified output sign, e.g.
// sign = UnspecifiedSign.NONE

// Test the operation
final Complex c = operation.apply(z);
final ComplexNumber c1 = operation2.apply(z.getReal(), z.getImaginary(), ComplexNumber::new);
final Complex c = TestUtils.assertSame(z, operation1, operation2, name);

final Complex t1 = sign.removeSign(c);
final Complex t2 = sign.removeSign(expected);
Expand All @@ -691,11 +691,11 @@ private static void assertComplex(Complex z,
}

if (!Double.isNaN(z.getImaginary())) {
assertConjugateEquality(z, operation, operation2, sign);
assertConjugateEquality(z, operation1, operation2, sign, name);
}

if (type != FunctionType.NONE) {
assertFunctionType(z, operation, type, sign);
assertFunctionType(z, operation1, type, sign);

// An odd/even function should satisfy the conjugate equality
// on the negated complex. This ensures testing the equalities
Expand All @@ -705,11 +705,9 @@ private static void assertComplex(Complex z,
// = -(-re, -im) (odd)
// (-re, -im) = (-re, im)
if (!Double.isNaN(z.getImaginary())) {
assertConjugateEquality(z.negate(), operation, operation2, sign);
assertConjugateEquality(z.negate(), operation1, operation2, sign, name);
}
}

TestUtils.assertSame(c, c1);
}

/**
Expand Down Expand Up @@ -1443,30 +1441,30 @@ void testLog() {
final UnaryOperator<Complex> operation1 = Complex::log;
final ComplexUnaryOperator<ComplexNumber> operation2 = ComplexFunctions::log;

assertConjugateEquality(operation1, operation2);
assertComplex(negZeroZero, operation1, operation2, negInfPi);
assertComplex(Complex.ZERO, operation1, operation2, negInfZero);
assertConjugateEquality(operation1, operation2, "log");
assertComplex(negZeroZero, operation1, operation2, negInfPi, "log");
assertComplex(Complex.ZERO, operation1, operation2, negInfZero, "log");
for (double x : finite) {
assertComplex(complex(x, inf), operation1, operation2, infPiTwo);
assertComplex(complex(x, inf), operation1, operation2, infPiTwo, "log");
}
for (double x : finite) {
assertComplex(complex(x, nan), operation1, operation2, NAN);
assertComplex(complex(x, nan), operation1, operation2, NAN, "log");
}
for (double y : positiveFinite) {
assertComplex(complex(-inf, y), operation1, operation2, infPi);
assertComplex(complex(-inf, y), operation1, operation2, infPi, "log");
}
for (double y : positiveFinite) {
assertComplex(complex(inf, y), operation1, operation2, infZero);
assertComplex(complex(inf, y), operation1, operation2, infZero, "log");
}
assertComplex(negInfInf, operation1, operation2, infThreePiFour);
assertComplex(infInf, operation1, operation2, infPiFour);
assertComplex(negInfNaN, operation1, operation2, infNaN);
assertComplex(infNaN, operation1, operation2, infNaN);
assertComplex(negInfInf, operation1, operation2, infThreePiFour, "log");
assertComplex(infInf, operation1, operation2, infPiFour, "log");
assertComplex(negInfNaN, operation1, operation2, infNaN, "log");
assertComplex(infNaN, operation1, operation2, infNaN, "log");
for (double y : finite) {
assertComplex(complex(nan, y), operation1, operation2, NAN);
assertComplex(complex(nan, y), operation1, operation2, NAN, "log");
}
assertComplex(nanInf, operation1, operation2, infNaN);
assertComplex(NAN, operation1, operation2, NAN);
assertComplex(nanInf, operation1, operation2, infNaN, "log");
assertComplex(NAN, operation1, operation2, NAN, "log");
}

/**
Expand All @@ -1478,30 +1476,30 @@ void testLog10() {
final UnaryOperator<Complex> operation1 = Complex::log10;
final ComplexUnaryOperator<ComplexNumber> operation2 = ComplexFunctions::log10;

assertConjugateEquality(operation1, operation2);
assertComplex(negZeroZero, operation1, operation2, negInfPi);
assertComplex(Complex.ZERO, operation1, operation2, negInfZero);
assertConjugateEquality(operation1, operation2, "log10");
assertComplex(negZeroZero, operation1, operation2, negInfPi, "log10");
assertComplex(Complex.ZERO, operation1, operation2, negInfZero, "log10");
for (double x : finite) {
assertComplex(complex(x, inf), operation1, operation2, infPiTwo);
assertComplex(complex(x, inf), operation1, operation2, infPiTwo, "log10");
}
for (double x : finite) {
assertComplex(complex(x, nan), operation1, operation2, NAN);
assertComplex(complex(x, nan), operation1, operation2, NAN, "log10");
}
for (double y : positiveFinite) {
assertComplex(complex(-inf, y), operation1, operation2, infPi);
assertComplex(complex(-inf, y), operation1, operation2, infPi, "log10");
}
for (double y : positiveFinite) {
assertComplex(complex(inf, y), operation1, operation2, infZero);
assertComplex(complex(inf, y), operation1, operation2, infZero, "log10");
}
assertComplex(negInfInf, operation1, operation2, infThreePiFour);
assertComplex(infInf, operation1, operation2, infPiFour);
assertComplex(negInfNaN, operation1, operation2, infNaN);
assertComplex(infNaN, operation1, operation2, infNaN);
assertComplex(negInfInf, operation1, operation2, infThreePiFour, "log10");
assertComplex(infInf, operation1, operation2, infPiFour, "log10");
assertComplex(negInfNaN, operation1, operation2, infNaN, "log10");
assertComplex(infNaN, operation1, operation2, infNaN, "log10");
for (double y : finite) {
assertComplex(complex(nan, y), operation1, operation2, NAN);
assertComplex(complex(nan, y), operation1, operation2, NAN, "log10");
}
assertComplex(nanInf, operation1, operation2, infNaN);
assertComplex(NAN, operation1, operation2, NAN);
assertComplex(nanInf, operation1, operation2, infNaN, "log10");
assertComplex(NAN, operation1, operation2, NAN, "log10");
}

/**
Expand Down

0 comments on commit 142fa7b

Please sign in to comment.