Class OrderedTuple

  • All Implemented Interfaces:
    java.lang.Comparable<OrderedTuple>

    @Deprecated
    public class OrderedTuple
    extends java.lang.Object
    implements java.lang.Comparable<OrderedTuple>
    Deprecated.
    as of 3.4, this class is not used anymore and considered to be out of scope of Apache Commons Math
    This class implements an ordering operation for T-uples.

    Ordering is done by encoding all components of the T-uple into a single scalar value and using this value as the sorting key. Encoding is performed using the method invented by Georg Cantor in 1877 when he proved it was possible to establish a bijection between a line and a plane. The binary representations of the components of the T-uple are mixed together to form a single scalar. This means that the 2k bit of component 0 is followed by the 2k bit of component 1, then by the 2k bit of component 2 up to the 2k bit of component t, which is followed by the 2k-1 bit of component 0, followed by the 2k-1 bit of component 1 ... The binary representations are extended as needed to handle numbers with different scales and a suitable 2p offset is added to the components in order to avoid negative numbers (this offset is adjusted as needed during the comparison operations).

    The more interesting property of the encoding method for our purpose is that it allows to select all the points that are in a given range. This is depicted in dimension 2 by the following picture:

    This picture shows a set of 100000 random 2-D pairs having their first component between -50 and +150 and their second component between -350 and +50. We wanted to extract all pairs having their first component between +30 and +70 and their second component between -120 and -30. We built the lower left point at coordinates (30, -120) and the upper right point at coordinates (70, -30). All points smaller than the lower left point are drawn in red and all points larger than the upper right point are drawn in blue. The green points are between the two limits. This picture shows that all the desired points are selected, along with spurious points. In this case, we get 15790 points, 4420 of which really belonging to the desired rectangle. It is possible to extract very small subsets. As an example extracting from the same 100000 points set the points having their first component between +30 and +31 and their second component between -91 and -90, we get a subset of 11 points, 2 of which really belonging to the desired rectangle.

    the previous selection technique can be applied in all dimensions, still using two points to define the interval. The first point will have all its components set to their lower bounds while the second point will have all its components set to their upper bounds.

    T-uples with negative infinite or positive infinite components are sorted logically.

    Since the specification of the Comparator interface allows only ClassCastException errors, some arbitrary choices have been made to handle specific cases. The rationale for these choices is to keep regular and consistent T-uples together.

    • instances with different dimensions are sorted according to their dimension regardless of their components values
    • instances with Double.NaN components are sorted after all other ones (even after instances with positive infinite components
    • instances with both positive and negative infinite components are considered as if they had Double.NaN components
    Since:
    3.0
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private double[] components
      Deprecated.
      Double components of the T-uple.
      private long[] encoding
      Deprecated.
      Ordering encoding of the double components.
      private static long EXPONENT_MASK
      Deprecated.
      Exponent bits mask.
      private static long IMPLICIT_ONE
      Deprecated.
      Implicit MSB for normalized numbers.
      private int lsb
      Deprecated.
      Least Significant Bit scale.
      private static long MANTISSA_MASK
      Deprecated.
      Mantissa bits mask.
      private boolean nan
      Deprecated.
      Not A Number marker.
      private boolean negInf
      Deprecated.
      Negative infinity marker.
      private int offset
      Deprecated.
      Offset scale.
      private boolean posInf
      Deprecated.
      Positive infinity marker.
      private static long SIGN_MASK
      Deprecated.
      Sign bit mask.
    • Constructor Summary

      Constructors 
      Constructor Description
      OrderedTuple​(double... components)
      Deprecated.
      Build an ordered T-uple from its components.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      int compareTo​(OrderedTuple ot)
      Deprecated.
      Compares this ordered T-uple with the specified object.
      private static int computeLSB​(long l)
      Deprecated.
      Compute the least significant bit of a long.
      private static int computeMSB​(long l)
      Deprecated.
      Compute the most significant bit of a long.
      private void encode​(int minOffset)
      Deprecated.
      Encode the T-uple with a given offset.
      boolean equals​(java.lang.Object other)
      Deprecated.
      private static int exponent​(long bits)
      Deprecated.
      Extract the exponent from the bits of a double.
      private int getBit​(int i, int k)
      Deprecated.
      Get a bit from the mantissa of a double.
      double[] getComponents()
      Deprecated.
      Get the components array.
      int hashCode()
      Deprecated.
      private static long mantissa​(long bits)
      Deprecated.
      Extract the mantissa from the bits of a double.
      private static long sign​(long bits)
      Deprecated.
      Extract the sign from the bits of a double.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • SIGN_MASK

        private static final long SIGN_MASK
        Deprecated.
        Sign bit mask.
        See Also:
        Constant Field Values
      • EXPONENT_MASK

        private static final long EXPONENT_MASK
        Deprecated.
        Exponent bits mask.
        See Also:
        Constant Field Values
      • MANTISSA_MASK

        private static final long MANTISSA_MASK
        Deprecated.
        Mantissa bits mask.
        See Also:
        Constant Field Values
      • IMPLICIT_ONE

        private static final long IMPLICIT_ONE
        Deprecated.
        Implicit MSB for normalized numbers.
        See Also:
        Constant Field Values
      • components

        private double[] components
        Deprecated.
        Double components of the T-uple.
      • offset

        private int offset
        Deprecated.
        Offset scale.
      • lsb

        private int lsb
        Deprecated.
        Least Significant Bit scale.
      • encoding

        private long[] encoding
        Deprecated.
        Ordering encoding of the double components.
      • posInf

        private boolean posInf
        Deprecated.
        Positive infinity marker.
      • negInf

        private boolean negInf
        Deprecated.
        Negative infinity marker.
      • nan

        private boolean nan
        Deprecated.
        Not A Number marker.
    • Constructor Detail

      • OrderedTuple

        public OrderedTuple​(double... components)
        Deprecated.
        Build an ordered T-uple from its components.
        Parameters:
        components - double components of the T-uple
    • Method Detail

      • encode

        private void encode​(int minOffset)
        Deprecated.
        Encode the T-uple with a given offset.
        Parameters:
        minOffset - minimal scale of the offset to add to all components (must be greater than the MSBs of all components)
      • compareTo

        public int compareTo​(OrderedTuple ot)
        Deprecated.
        Compares this ordered T-uple with the specified object.

        The ordering method is detailed in the general description of the class. Its main property is to be consistent with distance: geometrically close T-uples stay close to each other when stored in a sorted collection using this comparison method.

        T-uples with negative infinite, positive infinite are sorted logically.

        Some arbitrary choices have been made to handle specific cases. The rationale for these choices is to keep normal and consistent T-uples together.

        • instances with different dimensions are sorted according to their dimension regardless of their components values
        • instances with Double.NaN components are sorted after all other ones (evan after instances with positive infinite components
        • instances with both positive and negative infinite components are considered as if they had Double.NaN components
        Specified by:
        compareTo in interface java.lang.Comparable<OrderedTuple>
        Parameters:
        ot - T-uple to compare instance with
        Returns:
        a negative integer if the instance is less than the object, zero if they are equal, or a positive integer if the instance is greater than the object
      • equals

        public boolean equals​(java.lang.Object other)
        Deprecated.
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Deprecated.
        Overrides:
        hashCode in class java.lang.Object
      • getComponents

        public double[] getComponents()
        Deprecated.
        Get the components array.
        Returns:
        array containing the T-uple components
      • sign

        private static long sign​(long bits)
        Deprecated.
        Extract the sign from the bits of a double.
        Parameters:
        bits - binary representation of the double
        Returns:
        sign bit (zero if positive, non zero if negative)
      • exponent

        private static int exponent​(long bits)
        Deprecated.
        Extract the exponent from the bits of a double.
        Parameters:
        bits - binary representation of the double
        Returns:
        exponent
      • mantissa

        private static long mantissa​(long bits)
        Deprecated.
        Extract the mantissa from the bits of a double.
        Parameters:
        bits - binary representation of the double
        Returns:
        mantissa
      • computeMSB

        private static int computeMSB​(long l)
        Deprecated.
        Compute the most significant bit of a long.
        Parameters:
        l - long from which the most significant bit is requested
        Returns:
        scale of the most significant bit of l, or 0 if l is zero
        See Also:
        computeLSB(long)
      • computeLSB

        private static int computeLSB​(long l)
        Deprecated.
        Compute the least significant bit of a long.
        Parameters:
        l - long from which the least significant bit is requested
        Returns:
        scale of the least significant bit of l, or 63 if l is zero
        See Also:
        computeMSB(long)
      • getBit

        private int getBit​(int i,
                           int k)
        Deprecated.
        Get a bit from the mantissa of a double.
        Parameters:
        i - index of the component
        k - scale of the requested bit
        Returns:
        the specified bit (either 0 or 1), after the offset has been added to the double