[jira] [Commented] (NUMBERS-161) PlaneAngle Numerical Accuracy

["Matt Juntunen (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/NUMBERS-161?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17355011#comment-17355011 ] 

Matt Juntunen commented on NUMBERS-161:
---------------------------------------

Here is my thought for this API:
{code:java}
abstract class PlaneAngle {

    final double value;
    
    private PlaneAngle(double value){ this.value = value; }
    
    // get the raw value; units depend on the type
    double getValue() { return value; }
    
    // get the value in turns, degrees, or radians, performing multiplications
    // as needed
    double turns() {}
    double degrees() {}
    double radians() {}
    
    // convert to instances of the various subtypes
    PlaneAngle.Turns toTurns() {}
    PlaneAngle.Degrees toDegrees() {}
    PlaneAngle.Radians toRadians() {}
    
    // angle manipulation methods
    PlaneAngle add(PlaneAngle angle) {}
    PlaneAngle subtract(PlaneAngle angle) {}
    PlaneAngle multiply(double m) {}
    PlaneAngle divide(double d) {}
    
    // add a multiple of the full circle period to this instance
    // and return a new instance
    PlaneAngle addPeriod(double f) {}
    
    // return a new instance with the value within one period above the given 
    // lower bound
    PlaneAngle normalizeAbove(PlaneAngle lower) {}
    
    // return a new instance with the value within one period below the given
    // upper bound
    PlaneAngle normalizeBelow(PlaneAngle upper) {}

    // factory methods
    static PlaneAngle.Turns ofTurns(double turn) {}
    static PlaneAngle.Degrees ofDegrees(double deg) {}
    static PlaneAngle.Radians ofRadians(double rad) {}

    // unit-specific implementation classes
    static class Turns extends PlaneAngle {
        // ...
    }

    static class Degrees extends PlaneAngle {
        // ...
    }
    
    static class Radians extends PlaneAngle {
        // ...
    }
}
{code}

The manipulation methods (add, subtract, etc) are added so that callers can perform operations on the angles without needing to perform conversions themselves. The minimum amount of unit conversions would be performed internally, with degrees preferred over turns and radians preferred over degrees.

> PlaneAngle Numerical Accuracy
> -----------------------------
>
>                 Key: NUMBERS-161
>                 URL: https://issues.apache.org/jira/browse/NUMBERS-161
>             Project: Commons Numbers
>          Issue Type: Improvement
>            Reporter: Matt Juntunen
>            Priority: Major
>
> The current {{PlaneAngle}} class introduces unnecessary round-off errors during use since it internally converts all values to turns. For example, it is currently impossible to represent the radians value {{Double.MIN_NORMAL}} exactly since the internal multiplication introduces errors: {{PlaneAngle.ofRadians(Double.MIN_NORMAL).toRadians()}} does not equal {{Double.MIN_NORMAL}}. We should restructure this API so that values are stored exactly and multiplication is only performed when required.
> This issue was discovered during work on GEOMETRY-124. Use of the new {{Reduce}} class added two more floating point operations to angle normalization and caused a regression in commons-geometry-spherical.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)