## 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;

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)
#> [1] 16
collatz_function(16)
#> [1] 8
```

If we want change the default parameterisation we can;

```
collatz_function(4, 5, 2, 3)
#> [1] 11
```

Or if we only want to change one of them

```
collatz_function(3, a=-2)
#> [1] -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
#> [1] 5e+19
collatz_function(as.bigz("99999999999999999999"))
#> Big Integer ('bigz') :
#> [1] 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)
#> [[1]]
#> [1] 2
reverse_function(2)
#> [[1]]
#> [1] 4
reverse_function(4)
#> [[1]]
#> [1] 8
#>
#> [[2]]
#> [1] 1
```

If we want change the default parameterisation we can;

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

Or if we only want to change one of them

```
reverse_function(16, a=5)
#> [[1]]
#> [1] 32
#>
#> [[2]]
#> [1] 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
#> [[1]]
#> [1] 2e+20
reverse_function(as.bigz("99999999999999999999"))
#> [[1]]
#> Big Integer ('bigz') :
#> [1] 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)
#> [1] 96
stopping_time(27, total_stopping_time=TRUE)
#> [1] 111
```

If we want change the default parameterisation we can;

```
stopping_time(3, 5, 2, 1)
#> [1] Inf
```

Or if we only want to change one of them

```
stopping_time(17, a=5)
#> [1] 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] 1
stopping_time(as.bigz("99999999999999999999"))
#> [1] 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)
#> [1] 96
stopping_time(27+as.bigz("576460752303423488"))
#> [1] 96
stopping_time(27+(2*as.bigz("576460752303423488")))
#> [1] 96
stopping_time(27+(3*as.bigz("576460752303423488")))
#> [1] 96
stopping_time(27+(4*as.bigz("576460752303423488")))
#> [1] 96
```