## Install

After following the “Getting Started” instructions (which can also be seen in the README) to download and or install the package, it can be imported with;

library(collatz)
# Optionally
library(gmp)

You can jump right into using the functions in this package with integer inputs, or you can use bigz from the gmp library. Each function, amongst possible other parameters, comes with the default parameters (P=2,a=3,b=1) as optional inputs. In each case, P[=2] is the modulus to check for divisibility of the input by, a[=3] is the factor to multiply the input by, and b[=1] is the value to add to the product of a[=3] and the input. There are two basic commands to start with; the collatz_function and the reverse_function.

## collatz_function

Returns the output of a single application of a Collatz-esque function. Without gmp or parameterisation, we can try something simple like

collatz_function(5)
#>  16
collatz_function(16)
#>  8

If we want change the default parameterisation we can;

collatz_function(4, 5, 2, 3)
#>  11

Or if we only want to change one of them

collatz_function(3, a=-2)
#>  -5

All the above work fine, but the function doesn’t offer protection against overflowing integers by default. To venture into the world of arbitrary integer inputs we can use an as.bigz from gmp. Compare the two;

collatz_function(99999999999999999999)
#> Warning in collatz_function(1e+20): probable complete loss of accuracy in
#> modulus
#>  5e+19
collatz_function(as.bigz("99999999999999999999"))
#> Big Integer ('bigz') :
#>  299999999999999999998

## reverse_function

Calculates the values that would return the input under the Collatz function. Without gmp or parameterisation, we can try something simple like

reverse_function(1)
#> []
#>  2
reverse_function(2)
#> []
#>  4
reverse_function(4)
#> []
#>  8
#>
#> []
#>  1

If we want change the default parameterisation we can;

reverse_function(3, -3, -2, -5)
#> []
#>  -9
#>
#> []
#>  -4

Or if we only want to change one of them

reverse_function(16, a=5)
#> []
#>  32
#>
#> []
#>  3

All the above work fine, but the function doesn’t offer protection against overflowing integers by default. To venture into the world of arbitrary integer inputs we can use an as.bigz from gmp. Compare the two;

reverse_function(99999999999999999999)
#> Warning in reverse_function(1e+20): probable complete loss of accuracy in
#> modulus
#> []
#>  2e+20
reverse_function(as.bigz("99999999999999999999"))
#> []
#> Big Integer ('bigz') :
#>  199999999999999999998

## stopping_time

Calculates the “stopping time”, or optionally the “total” stopping time. Without gmp or parameterisation, we can try something simple like

stopping_time(27)
#>  96
stopping_time(27, total_stopping_time=TRUE)
#>  111

If we want change the default parameterisation we can;

stopping_time(3, 5, 2, 1)
#>  Inf

Or if we only want to change one of them

stopping_time(17, a=5)
#>  Inf

All the above work fine, but the function doesn’t offer protection against overflowing integers by default. To venture into the world of arbitrary integer inputs we can use an as.bigz from gmp. Compare the two;

stopping_time(99999999999999999999)
#> Warning in collatz_function(initial_value, P = P, a = a, b = b): probable
#> complete loss of accuracy in modulus
#> Warning in collatz_function(hailstone\$values[[k]], P = P, a = a, b = b):
#> probable complete loss of accuracy in modulus
#>  1
stopping_time(as.bigz("99999999999999999999"))
#>  114

As an extra note, the original motivation for creating a range of Collatz themed packages came from some earlier scripts for calculating the stopping distances under certain parameterisations. An inconsequential result of which was observing that all of the following, for however high k goes, should equal 96!

stopping_time(27)
#>  96
stopping_time(27+as.bigz("576460752303423488"))
#>  96
stopping_time(27+(2*as.bigz("576460752303423488")))
#>  96
stopping_time(27+(3*as.bigz("576460752303423488")))
#>  96
stopping_time(27+(4*as.bigz("576460752303423488")))
#>  96