# Functions

`Collatz.collatz_function`

— Function`collatz_function(n; P=2, a=3, b=1)`

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

**Args**

`n::Integer`

: The value on which to perform the Collatz-esque function

**Kwargs**

`P::Integer=2`

: Modulus used to devide n, iff n is equivalent to (0 mod P).`a::Integer=3`

: Factor by which to multiply n.`b::Integer=1`

: Value to add to the scaled value of n.

**Examples**

```
julia> collatz_function(5)
16
```

```
julia> collatz_function(14, P=7)
2
```

```
julia> collatz_function(15, P=7, a=5, b=3)
78
```

`Collatz.reverse_collatz_function`

— Function`reverse_collatz_function(n; P=2, a=3, b=1)`

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

**Args**

`n::Integer`

: The value on which to perform the reverse Collatz function

**Kwargs**

`P::Integer=2`

: Modulus used to devide n, iff n is equivalent to (0 mod P).`a::Integer=3`

: Factor by which to multiply n.`b::Integer=1`

: Value to add to the scaled value of n.

**Examples**

```
julia> print(reverse_collatz_function(1))
[2]
```

```
julia> print(reverse_collatz_function(4))
[1, 8]
```

```
julia> print(reverse_collatz_function(3, P=-3, a=-2, b=-5))
[-9, -4]
```

`Collatz.hailstone_sequence`

— Function`hailstone_sequence(initial_value; P=2, a=3, b=1, max_total_stopping_time=1000, total_stopping_time=true, verbose=true)`

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".

**Args**

`initial_value::Integer`

: The value to begin the hailstone sequence from.

**Kwargs**

`P::Integer=2`

: Modulus used to devide n, iff n is equivalent to (0 mod P).`a::Integer=3`

: Factor by which to multiply n.`b::Integer=1`

: Value to add to the scaled value of n.`max_total_stopping_time::Integer=1000`

: Maximum amount of times to iterate the function, if 1 is not reached.`total_stopping_time::Bool=true`

: 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).`verbose::Bool=true`

: 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.

**Examples**

```
julia> print(hailstone_sequence(16, verbose=false))
[16, 8, 4, 2, 1]
```

```
julia> print(hailstone_sequence(16))
Any[16, 8, 4, 2, 1, Any[Collatz._CC.TOTAL_STOPPING_TIME, 4]]
```

```
julia> print(hailstone_sequence(761, P=5, a=2, b=3, verbose=false))
[761, 1525, 305, 61, 125, 25, 5, 1]
```

**Example cycle!**

```
julia> print(hailstone_sequence(-56))
Any[-56, -28, Collatz._CC.CYCLE_INIT, Any[-14, -7, -20, -10, -5], Any[Collatz._CC.CYCLE_LENGTH, 5]]
```

```
julia> print(hailstone_sequence(-56, verbose=false))
[-56, -28, -14, -7, -20, -10, -5, -14]
```

`Collatz.stopping_time`

— Function`stopping_time(initial_value; P=2, a=3, b=1, max_stopping_time=1000, total_stopping_time=false)`

Returns the stopping time, the amount of iterations required to reach a value less than the initial value, or nothing 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 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.

**Args**

`initial_value::Integer`

: The value for which to find the stopping time.

**Kwargs**

`P::Integer=2`

: Modulus used to devide n, iff n is equivalent to (0 mod P).`a::Integer=3`

: Factor by which to multiply n.`b::Integer=1`

: Value to add to the scaled value of n.`max_stopping_time::Integer=1000`

: 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 nothing.`total_stopping_time::Bool=false`

: 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).

**Examples**

```
julia> stopping_time(5)
3
julia> stopping_time(27)
96
julia> stopping_time(21, P=5, a=2, b=3, total_stopping_time=true)
Inf
```

`Collatz.tree_graph`

— Function`tree_graph(initial_value, max_orbit_distance; P=2, a=3, b=1, __cycle_prevention=nothing)`

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.

**Args**

`initial_value::Integer`

: The root value of the directed tree graph.`max_orbit_distance::Integer`

: 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.

**Kwargs**

`P::Integer=2`

: Modulus used to devide n, iff n is equivalent to (0 mod P).`a::Integer=3`

: Factor by which to multiply n.`b::Integer=1`

: Value to add to the scaled value of n.

**Internal Kwargs**

`__cycle_prevention::Union{Set{Integer},Nothing}=nothing`

: Used to prevent cycles from precipitatingby keeping track of all values added across previous nest depths.

**Examples**

```
julia> print(tree_graph(1, 3))
Dict{Int64, Dict{Any, Any}}(1 => Dict(2 => Dict{Any, Any}(4 => Dict{Any, Any}(Collatz._CC.CYCLE_INIT => 1, 8 => Dict{Any, Any}()))))
```

```
julia> print(tree_graph(4, 3))
Dict{Int64, Dict{Any, Any}}(4 => Dict(8 => Dict{Any, Any}(16 => Dict{Any, Any}(5 => Dict{Any, Any}(), 32 => Dict{Any, Any}())), 1 => Dict{Any, Any}(2 => Dict{Any, Any}(Collatz._CC.CYCLE_INIT => 4))))
```