collatz.parameterised module#

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.

collatz.parameterised.function(n: int, P: int = 2, a: int = 3, b: int = 1)[source]#

Returns the output of a single application of a Collatz-esque function.

Parameters:

n (int) – The value on which to perform the Collatz-esque function

Keyword Arguments:

  • P (int) – Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.

  • a (int) – Factor by which to multiply n. Default is 3.

  • b (int) – Value to add to the scaled value of n. Default is 1.

collatz.parameterised.hailstone_sequence(initial_value: int, P: int = 2, a: int = 3, b: int = 1, max_total_stopping_time: int = 1000, total_stopping_time: bool = True, verbose: bool = True)[source]#

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 max_total_stopping_time, unless total_stopping_time 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:

initial_value (int) – The value to begin the hailstone sequence from.

Keyword Arguments:

  • P (int) – Modulus used to devide n, iff n is equivalent to (0 mod P) Default is 2.

  • a (int) – Factor by which to multiply n. Default is 3.

  • b (int) – Value to add to the scaled value of n. Default is 1.

  • max_total_stopping_time (int) – Maximum amount of times to iterate the function, if 1 is not reached. Default is 1000.

  • total_stopping_time (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). Default is True.

  • verbose (bool) – If set to verbose, the hailstone sequence will include control string sequences to provide information about how the sequence terminated, whether by reaching a stopping time or entering a cycle. Default is True.

collatz.parameterised.reverse_function(n: int, P: int = 2, a: int = 3, b: int = 1)[source]#

Returns the output of a single application of a Collatz-esque reverse function.

Parameters:

n (int) – The value on which to perform the reverse Collatz function

Keyword Arguments:

  • P (int) – Modulus used to devide n, iff n is equivalent to (0 mod P). Default is 2.

  • a (int) – Factor by which to multiply n. Default is 3.

  • b (int) – Value to add to the scaled value of n. Default is 1.

collatz.parameterised.stopping_time(initial_value: int, P: int = 2, a: int = 3, b: int = 1, max_stopping_time: int = 1000, total_stopping_time: bool = False)[source]#

Returns the stopping time, the amount of iterations required to reach a value less than the initial value, or None if max_stopping_time is exceeded. Alternatively, if total_stopping_time 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 (math.inf). 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:

initial_value (int) – The value for which to find the stopping time.

Keyword Arguments:

  • P (int) – Modulus used to devide n, iff n is equivalent to (0 mod P) Default is 2.

  • a (int) – Factor by which to multiply n. Default is 3.

  • b (int) – Value to add to the scaled value of n. Default is 1.

  • max_stopping_time (int) – Maximum amount of times to iterate the function, if the stopping time is not reached. IF the max_stopping_time is reached, the function will return None. Default is 1000.

  • total_stopping_time (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). Default is False.

collatz.parameterised.tree_graph(initial_value: int, max_orbit_distance: int, P: int = 2, a: int = 3, b: int = 1, __cycle_prevention: Set[int] | None = None)[source]#

Returns nested dictionaries that model the directed tree graph up to a maximum nesting of max_orbit_distance, with the initial_value as the root.

Parameters:

  • initial_value (int) – The root value of the directed tree graph.

  • max_orbit_distance (int) – 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 max_stopping_time / max_total_stopping_time, as it is the intended target of orbits to obtain, rather than a limit to avoid uncapped computation.

Keyword Arguments:

  • P (int) – Modulus used to devide n, iff n is equivalent to (0 mod P) Default is 2.

  • a (int) – Factor by which to multiply n. Default is 3.

  • b (int) – Value to add to the scaled value of n. Default is 1.

Internal Keyword Args:
__cycle_prevention (set[int]): Used to prevent cycles from precipitating

by keeping track of all values added across previous nest depths.