Package io.github.skenvy

Class Collatz

  • public final class Collatz
extends Object
    Provides the basic functionality to interact with the Collatz conjecture. The parameterisation uses the same (P,a,b) notation as Conway's generalisations. Besides the function and reverse function, there is also functionality to retrieve the hailstone sequence, the "stopping time"/"total stopping time", or tree-graph.

    • Field Detail

      • DEFAULT_P

        public static final BigInteger DEFAULT_P
        Default value for P, the modulus condition.

      • DEFAULT_A

        public static final BigInteger DEFAULT_A
        Default value for a, the input's multiplicand.

      • DEFAULT_B

        public static final BigInteger DEFAULT_B
        Default value for b, the value added to the multiplied value.

      • KNOWN_CYCLES

        public static final BigInteger[][] KNOWN_CYCLES
        The four known cycles for the standard parameterisation.

      • VERIFIED_MAXIMUM

        public static final BigInteger VERIFIED_MAXIMUM
        The current value up to which the standard parameterisation has been verified.

      • VERIFIED_MINIMUM

        public static final BigInteger VERIFIED_MINIMUM
        The current value down to which the standard parameterisation has been verified.

    • Constructor Detail

      • Collatz

        public Collatz()

    • Method Detail

      • reverseFunction

        public static BigInteger[] reverseFunction​(BigInteger n,
                                           BigInteger p,
                                           BigInteger a,
                                           BigInteger b)
                                    throws Collatz.FailedSaneParameterCheck
        Returns the output of a single application of a Collatz-esque reverse function. If only one value is returned, it is the value that would be divided by P. If two values are returned, the first is the value that would be divided by P, and the second value is that which would undergo the multiply and add step, regardless of which is larger.
        Parameters:
        n - The value on which to perform the reverse Collatz function.
        p - Modulus used to devide n, iff n is equivalent to (0 mod P).
        a - Factor by which to multiply n.
        b - Value to add to the scaled value of n.
        Returns:
        The result of the function's reverse
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • reverseFunction

        public static BigInteger[] reverseFunction​(BigInteger n)
                                    throws Collatz.FailedSaneParameterCheck
        Returns the output of a single application of the Collatz reverse function. If only one value is returned, it is the value that would be divided by 2. If two values are returned, the first is the value that would be divided by 2, and the second value is that which would undergo the 3N+1 step, regardless of which is larger.
        Parameters:
        n - The value on which to perform the reverse Collatz function.
        Returns:
        The result of the function's reverse
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • hailstoneSequence

        public static Collatz.HailstoneSequence hailstoneSequence​(BigInteger initialValue,
                                                          BigInteger p,
                                                          BigInteger a,
                                                          BigInteger b,
                                                          int maxTotalStoppingTime,
                                                          boolean totalStoppingTime)
                                                   throws Collatz.FailedSaneParameterCheck
        Returns a list of successive values obtained by iterating a Collatz-esque function, until either 1 is reached, or the total amount of iterations exceeds maxTotalStoppingTime, unless totalStoppingTime is False, which will terminate the hailstone at the "stopping time" value, i.e. the first value less than the initial value. While the sequence has the capability to determine that it has encountered a cycle, the cycle from "1" wont be attempted or reported as part of a cycle, regardless of default or custom parameterisation, as "1" is considered a "total stop".
        Parameters:
        initialValue - The value to begin the hailstone sequence from.
        p - Modulus used to devide n, iff n is equivalent to (0 mod P).
        a - Factor by which to multiply n.
        b - Value to add to the scaled value of n.
        maxTotalStoppingTime - Maximum amount of times to iterate the function, if 1 is not reached.
        totalStoppingTime - Whether or not to execute until the "total" stopping time (number of iterations to obtain 1) rather than the regular stopping time (number of iterations to reach a value less than the initial value).
        Returns:
        A set of values that form the hailstone sequence.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • hailstoneSequence

        public static Collatz.HailstoneSequence hailstoneSequence​(BigInteger initialValue,
                                                          int maxTotalStoppingTime)
                                                   throws Collatz.FailedSaneParameterCheck
        Returns a list of successive values obtained by iterating the Collatz function, until either 1 is reached, or the total amount of iterations exceeds maxTotalStoppingTime.
        Parameters:
        initialValue - The value to begin the hailstone sequence from.
        maxTotalStoppingTime - Maximum amount of times to iterate the function, if 1 is not reached.
        Returns:
        A set of values that form the hailstone sequence.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • stoppingTime

        public static Double stoppingTime​(BigInteger initialValue,
                                  BigInteger p,
                                  BigInteger a,
                                  BigInteger b,
                                  int maxStoppingTime,
                                  boolean totalStoppingTime)
                           throws Collatz.FailedSaneParameterCheck
        Returns the stopping time, the amount of iterations required to reach a value less than the initial value, or null if maxStoppingTime is exceeded. Alternatively, if totalStoppingTime is True, then it will instead count the amount of iterations to reach 1. If the sequence does not stop, but instead ends in a cycle, the result will be (Double.POSITIVE_INFINITY). If (P,a,b) are such that it is possible to get stuck on zero, the result will be the negative of what would otherwise be the "total stopping time" to reach 1, where 0 is considered a "total stop" that should not occur as it does form a cycle of length 1.
        Parameters:
        initialValue - The value for which to find the stopping time.
        p - Modulus used to devide n, iff n is equivalent to (0 mod P).
        a - Factor by which to multiply n.
        b - Value to add to the scaled value of n.
        maxStoppingTime - Maximum amount of times to iterate the function, if the stopping time is not reached. IF the maxStoppingTime is reached, the function will return null.
        totalStoppingTime - (bool): Whether or not to execute until the "total" stopping time (number of iterations to obtain 1) rather than the regular stopping time (number of iterations to reach a value less than the initial value).
        Returns:
        The stopping time, or, in a special case, infinity, null or a negative.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • stoppingTime

        public static Double stoppingTime​(BigInteger initialValue)
                           throws Collatz.FailedSaneParameterCheck
        Returns the stopping time, the amount of iterations required to reach a value less than the initial value, or null if maxStoppingTime is exceeded. Alternatively, if totalStoppingTime is True, then it will instead count the amount of iterations to reach 1. If the sequence does not stop, but instead ends in a cycle, the result will be (Double.POSITIVE_INFINITY).
        Parameters:
        initialValue - The value for which to find the stopping time.
        Returns:
        The stopping time, or, in a cycle case, infinity.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • treeGraph

        public static Collatz.TreeGraph treeGraph​(BigInteger initialValue,
                                          int maxOrbitDistance,
                                          BigInteger p,
                                          BigInteger a,
                                          BigInteger b)
                                   throws Collatz.FailedSaneParameterCheck
        Returns a directed tree graph of the reverse function values up to a maximum nesting of maxOrbitDistance, with the initialValue as the root.
        Parameters:
        initialValue - The root value of the directed tree graph.
        maxOrbitDistance - Maximum amount of times to iterate the reverse function. There is no natural termination to populating the tree graph, equivalent to the termination of hailstone sequences or stopping time attempts, so this is not an optional argument like maxStoppingTime / maxTotalStoppingTime, as it is the intended target of orbits to obtain, rather than a limit to avoid uncapped computation.
        p - Modulus used to devide n, iff n is equivalent to (0 mod P).
        a - Factor by which to multiply n.
        b - Value to add to the scaled value of n.
        Returns:
        the entire tree graph up to some orbit distance, for the given parameters.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.

      • treeGraph

        public static Collatz.TreeGraph treeGraph​(BigInteger initialValue,
                                          int maxOrbitDistance)
                                   throws Collatz.FailedSaneParameterCheck
        Returns a directed tree graph of the reverse function values up to a maximum nesting of maxOrbitDistance, with the initialValue as the root.
        Parameters:
        initialValue - The root value of the directed tree graph.
        maxOrbitDistance - Maximum amount of times to iterate the reverse function. There is no natural termination to populating the tree graph, equivalent to the termination of hailstone sequences or stopping time attempts, so this is not an optional argument like maxStoppingTime / maxTotalStoppingTime, as it is the intended target of orbits to obtain, rather than a limit to avoid uncapped computation.
        Returns:
        the entire tree graph up to some orbit distance, for the given parameters.
        Throws:
        Collatz.FailedSaneParameterCheck - if P or a are 0.