#' @include utils.R

#' @include collatz_function.R

NULL

#' Hailstone Sequencer

#'

#' Calculates the values of a hailstone sequence, from an initial value.

#'

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

#'

#' @param initial_value (numeric|bigz)

#' The value to begin the hailstone sequence from.

#' @param P (numeric|bigz): Modulus used to divide

#' n, iff n is equivalent to (0 mod P). Default is 2.

#' @param a (numeric|bigz) Factor by which to multiply n. Default is 3.

#' @param b (numeric|bigz) Value to add

#' to the scaled value of n. Default is 1.

#' @param max_total_stopping_time (int) Maximum amount of times to iterate the

#' function, if 1 is not reached. Default is 1000.

#' @param 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.

#' @param 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.

#' @returns A keyed list consisting of a $values list of numeric | bigz

#' along with a $terminalCondition and $terminalStatus

#' @examples

#' # Compute a hailstone sequence, which defaults to the total stopping time;

#' hailstone_sequence(5)

#' # Or only compute down to the regular stopping time;

#' hailstone_sequence(5, total_stopping_time=FALSE)

#' # Remove verbose messaging;

#' hailstone_sequence(5, verbose=FALSE)

#' # It will also stop on finding a cycle;

#' hailstone_sequence(-56)

#' # And can be parameterised;

#' hailstone_sequence(3, -1, 3, 1)

#' # The hailstone sequence can run on `bigz`;

#' hailstone_sequence(27+as.bigz("576460752303423488"))

#' @export

hailstone_sequence <- function(initial_value, P=2, a=3, b=1,

    max_total_stopping_time=1000, total_stopping_time=TRUE, verbose=TRUE){

    # Call out the collatz_function before any magic returns to trap bad values.

    # 0 is always an immediate stop.

        } else {

        }

    }

    # 1 is always an immediate stop, with 0 stopping time.

        } else {

        }

    }

    # Start the hailstone sequence.

        # Check if the next_val hailstone is either the stopping time, total

        # stopping time, the same as the initial value, or stuck at zero.

                } else {

                }

            } else {

            }

        }

        # Here is normally where cyclic <- function(x){x %in% hailstone$values}

        # would be used to determine presence of a new value in previous values

        # but R's in-built tests for set membership all behave differently to

        # other languages when the input itself is a vector, which bigz raw is!

        # e.g. see how meaningless this is: `gmp::numerator(5) %in% list(5)`

        # So we need to always do to the inverse loop traversal and compare,

        # as the compare on list elements against bigz | bigq _does_ work!

        # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

            }

        }

            } else {

            }

        }

        # <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

            } else {

            }

        }

    }

    } else {

    }

}

#' @include utils.R

#' @include reverse_function.R

NULL

#' Tree Graph

#'

#' Determine the Tree Graph to some depth by iteratively reversing values.

#'

#' 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.

#' @param initial_value (int) The root value of the directed tree graph.

#' @param 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 or

#' max_total_stopping_time, as it is the intended target of orbits to obtain,

#' rather than a limit to avoid uncapped computation.

#' @param P (numeric|bigz): Modulus used to divide

#' n, iff n is equivalent to (0 mod P). Default is 2.

#' @param a (numeric|bigz) Factor by which to multiply n. Default is 3.

#' @param b (numeric|bigz) Value to add

#' to the scaled value of n. Default is 1.

#' @param cycle_prevention (set[int]) Used to prevent cycles from precipitating

#' by keeping track of all values added across previous nest depths. Only to be

#' used internally by the function recursing. Does not expect input.

#' @returns A set of nested dictionaries.

#' @examples

#' #Compute a tree graph, which takes both a value to initialise the tree from,

#' # and an "orbit distance" for how many layers deep in the tree to compute;

#' tree_graph(16, 3)

#' # It will also stop on finding a cycle;

#' tree_graph(4, 3)

#' # And can be parameterised;

#' tree_graph(1, 1, -3, -2, -5)

#' # If b is a multiple of a, but not of Pa, then 0 can have a reverse;

#' tree_graph(0, 1, 17, 2, -6)

#' # The tree graph can run on `bigz`;

#' tree_graph((27+as.bigz("576460752303423488")), 3)

#' @export

tree_graph <- function(initial_value, max_orbit_distance, P=2, a=3, b=1, cycle_prevention=list()){

    # Call out the reverse_function before any magic returns to trap bad values.

    # In R, if a numeric is used as the key in a K:V list, it will populate the

    # entire list up to that point as ascending numerics pointing to NULLs.

    # To get around this, we can "as.character(numeric_val)" as it does not

    # do the same backfilling for string keys. Although this yields another

    # problem, that the syntax `list((as.character(some_num))=anything)`

    # complains of `Error: unexpected '=' in "list((as.character(some_num))="`

    # So rather than a syntactically concise one liner, we need a few lines..

    } else {

    }

            }

        }

        }

    }

}

#' @include utils.R

NULL

#' The "inverse"/"reverse" Collatz function

#'

#' Calculates the values that would return the input under the Collatz function.

#'

#' 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.

#' @param n (numeric|bigz) The value on which

#' to perform the reverse Collatz function

#' @param P (numeric|bigz) Modulus used to divide

#' n, iff n is equivalent to (0 mod P) Default is 2.

#' @param a (numeric|bigz) Factor by which to multiply n. Default is 3.

#' @param b (numeric|bigz) Value to add

#' to the scaled value of n. Default is 1.

#' @returns A list of either numeric or bigz type

#' @examples

#' # 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)

#' reverse_function(2)

#' reverse_function(4)

#' # If we want change the default parameterisation we can;

#' reverse_function(3, -3, -2, -5)

#' # Or if we only want to change one of them

#' reverse_function(16, a=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;

#' reverse_function(99999999999999999999)

#' reverse_function(as.bigz("99999999999999999999"))

#' @export

reverse_function <- function(n, P=2, a=3, b=1){

    # Every input can be reversed as the result of "n/P" division, which yields

    # "Pn"... {f(n) = an + b}~={(f(n) - b)/a = n} ~ if n was such that the

    # muliplication step was taken instead of the division by the modulus, then

    # (f(n) - b)/a) must be an integer that is not in (0 mod P). Because we're

    # not placing restrictions on the parameters yet, although there is a better

    # way of shortcutting this for the default variables, we need to always

    # attempt (f(n) - b)/a)

        # bigq does not have a defined use for %%, so must be int or bigz

        # bigz/bigz returns a bigq even if that bigq has denominator 1

        # so we do a divq, "%/%", instead of div, to just get the bigz.

    }

}

#' @include utils.R

NULL

#' The Collatz function

#'

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

#'

#' This function will compute and return the result of applying one iteration

#' of a parameterised Collatz-esque function. Although it will operate with

#' integer inputs, for overflow safety, provide a gmp Big Integer ('bigz').

#'

#' @param n (numeric|bigz) The value on which

#' to perform the Collatz-esque function

#' @param P (numeric|bigz): Modulus used to divide

#' n, iff n is equivalent to (0 mod P). Default is 2.

#' @param a (numeric|bigz) Factor by which to multiply n. Default is 3.

#' @param b (numeric|bigz) Value to add

#' to the scaled value of n. Default is 1.

#' @returns a numeric, either in-built or a bigz from the gmp library.

#' @examples

#' # 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)

#' collatz_function(16)

#' # If we want change the default parameterisation we can;

#' collatz_function(4, 5, 2, 3)

#' # Or if we only want to change one of them

#' collatz_function(3, a=-2)

#' # 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)

#' collatz_function(as.bigz("99999999999999999999"))

#' @export

collatz_function <- function(n, P=2, a=3, b=1){

    # bigq does not have a defined use for %%, so must be int or bigz

    # bigz/bigz returns a bigq even if that bigq has denominator 1

    # so we do a divq, "%/%", instead of div, to just get the bigz.

}

#' Collatz

#'

#' Functions related to the Collatz/Syracuse/3N+1 problem.

#'

#' 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.

#' The only restriction placed on parameters is that both P and a can't be 0.

#'

#' @docType package

#' @name collatz

#' @import gmp

NULL

library(gmp)

# An environment for constants related to the Collatz package, primarily for testing purposes.

Collatz <- new.env()

# The four known cycles for the standard parameterisation, as ints.

Collatz$KNOWN.CYCLES <- list(list(1, 4, 2), list(-1, -2), list(-5, -14, -7, -20, -10),

    list(-17, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34))

lockBinding("KNOWN.CYCLES", Collatz)

# The current value up to which the standard parameterisation has been verified.

Collatz$VERIFIED.MAXIMUM <- as.bigz("295147905179352825856")

lockBinding("VERIFIED.MAXIMUM", Collatz)

# The current value down to which the standard parameterisation has been verified.

# TODO: Check the actual lowest bound.

Collatz$VERIFIED.MINIMUM <- -272

lockBinding("VERIFIED.MINIMUM", Collatz)

# Error message constants

Collatz$SaneParameterErrMsg <- list(P="'P' should not be 0 ~ violates modulo being non-zero.", A="'a' should not be 0 ~ violates the reversability.")

lockBinding("SaneParameterErrMsg", Collatz)

# SequenceState for Cycle Control: Descriptive flags to indicate when some

# event occurs in the hailstone sequences or tree graph reversal, when set to

# verbose, or stopping time check. Create as an S3 class.

Collatz$SequenceState <- list(

    STOPPING_TIME="STOPPING_TIME",

    TOTAL_STOPPING_TIME="TOTAL_STOPPING_TIME",

    CYCLE_INIT="CYCLE_INIT",

    CYCLE_LENGTH="CYCLE_LENGTH",

    MAX_STOP_OUT_OF_BOUNDS="MAX_STOP_OUT_OF_BOUNDS",

    ZERO_STOP="ZERO_STOP")

lockBinding("SequenceState", Collatz)

#' Sane Parameter Check

#'

#' Handles the sanity check for the parameterisation (P,a,b)

#'

#' Required by both the function and reverse function, to assert that they

#' have sane parameters, otherwise will force stop the execution.

#'

#' @param P Modulus used to devide n, iff n is equivalent to (0 mod P).

#' @param a Factor by which to multiply n.

#' @param b Value to add to the scaled value of n.

assert_sane_parameterication <- function(P, a, b) {

    # Sanity check (P,a,b) ~ P absolutely can't be 0. a "could" be zero

    # theoretically, although would violate the reversability (if ~a is 0 then a

    # value of "b" as the input to the reverse function would have a pre-emptive

    # value of every number not divisible by P). The function doesn't _have_ to

    # be reversable, but we are only interested in dealing with the class of

    # functions that exhibit behaviour consistant with the collatz function. If

    # _every_ input not divisable by P went straight to "b", it would simply

    # cause a cycle consisting of "b" and every b/P^z that is an integer. While

    # P in [-1, 1] could also be a reasonable check, as it makes every value

    # either a 1 or 2 length cycle, it's not strictly an illegal operation.

    # "b" being zero would cause behaviour not consistant with the collatz

    # function, but would not violate the reversability, so no check either.

    # " != 0" is redundant for python assertions.

}

#' Stopping Time Terminus

#'

#' Provides the appropriate lambda to use to check if iterations on an initial

#' value have reached either the stopping time, or total stopping time.

#'

#' @param n The initial value to confirm against a stopping time check.

#' @param total_stop If false, the lambda will confirm that iterations of n

#'    have reached the oriented stopping time to reach a value closer to 0.

#'    If true, the lambda will simply check equality to 1.

#' @returns An anonymous function to check for the stopping time.

stopping_time_terminus <- function(n, total_stop) {

	} else {

	}

}

#' @include utils.R

#' @include hailstone_sequence.R

NULL

#' Stopping Time

#'

#' Determine the stopping time, or "total" stopping time, for an initial value.

#'

#' Returns the stopping time, the amount of iterations required to reach a

#' value less than the initial value, or NaN 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 (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.

#' @param initial_value (int): The value for which to find the stopping time.

#' @param P (numeric|bigz): Modulus used to divide

#' n, iff n is equivalent to (0 mod P). Default is 2.

#' @param a (numeric|bigz) Factor by which to multiply n. Default is 3.

#' @param b (numeric|bigz) Value to add

#' to the scaled value of n. Default is 1.

#' @param 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 NaN. Default is 1000.

#' @param 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.

#' @returns An integer numeral if stopped, Inf if a cycle, NaN if OOB, else NA.

#' @examples

#' # Calculates the "stopping time", or optionally the "total" stopping time.

#' # Without `gmp` or parameterisation, we can try something simple like

#' stopping_time(27)

#' stopping_time(27, total_stopping_time=TRUE)

#' # If we want change the default parameterisation we can;

#' stopping_time(3, 5, 2, 1)

#' # Or if we only want to change one of them

#' stopping_time(17, a=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;

#' stopping_time(99999999999999999999)

#' stopping_time(as.bigz("99999999999999999999"))

#' # 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)

#' stopping_time(27+as.bigz("576460752303423488"))

#' stopping_time(27+(2*as.bigz("576460752303423488")))

#' stopping_time(27+(3*as.bigz("576460752303423488")))

#' stopping_time(27+(4*as.bigz("576460752303423488")))

#' @export

stopping_time <- function(initial_value, P=2, a=3, b=1,

    max_stopping_time=1000, total_stopping_time=FALSE){

    # The information is contained in the verbose form of a hailstone sequence.

    # Although the "max_~_time" for hailstones is name for "total stopping" time

    # and the "max_~_time" for this "stopping time" function is _not_ "total",

    # they are handled the same way, as the default for "total_stopping_time"

    # for hailstones is true, but for this, is false. Thus the naming difference

    # For total/regular/zero stopping time, the value is already the same as

    # that present, for cycles we report infinity instead of the cycle length,

    # and for max stop out of bounds, we report None instead of the max stop cap

    # An extra note here is that while other designs use the enum values as the

    # comparitors in the switch, R is very unhappy with non-literal switch keys.

    ))

}