Crate use_collatz

Expand description

§use-collatz

Small Collatz trajectory utilities for `RustUse`.
Dependency-free helpers for exploring Collatz sequences, stopping times, parity patterns, and bounded range verification over positive integers.

§Install

[dependencies]
use-collatz = "0.0.6"

§Foundation

use-collatz provides a deliberately small surface for computing with the Collatz map on positive u64 inputs:

if n is even, the next value is n / 2
if n is odd, the next value is 3n + 1

The Collatz conjecture remains unproven. This crate does not claim to prove it or to settle its global behavior. Instead, it focuses on bounded computational exploration: generating trajectories, measuring stopping behavior, inspecting parity patterns, and summarizing finite inclusive ranges.

Trajectory helpers
collatz_next, collatz_sequence, trajectory_len, and max_value_in_trajectory expose the concrete path followed by a starting value. Stopping-time helpers
stopping_time, total_stopping_time, and reaches_one keep step counts and overflow behavior explicit. Parity and range summaries
CollatzParity, parity_vector, and verify_range support quick trajectory inspection across bounded inputs.

§When to use directly

Choose use-collatz directly when Collatz trajectory analysis is the only math support you need and you want to keep that concern narrow and dependency-free.

Scenario	Use `use-collatz` directly?	Why
You need the explicit trajectory for one starting value	Yes	The crate keeps the sequence utilities small and concrete
You need stopping times or peak values for bounded inputs	Yes	The API centers on direct trajectory metrics without extra abstractions
You want parity patterns for exploratory experiments	Yes	The parity helpers stay aligned with the trajectory surface
You need broader numeric, algebraic, or symbolic abstractions	Usually no	Those belong in adjacent focused crates or the `use-math` facade

§Scope

The current surface is intentionally small and concrete.
All public helpers operate on positive u64 inputs.
Odd steps use checked arithmetic so overflow returns None instead of wrapping.
The crate is for bounded computational exploration, not proof, exhaustive classification, or conjecture claims.

§Examples

§Generate a full trajectory

use use_collatz::{collatz_sequence, total_stopping_time};

assert_eq!(collatz_sequence(6), Some(vec![6, 3, 10, 5, 16, 8, 4, 2, 1]));
assert_eq!(total_stopping_time(6), Some(8));

§Inspect parity and range summaries

use use_collatz::{CollatzParity, parity_vector, verify_range};

assert_eq!(
    parity_vector(6),
    Some(vec![
        CollatzParity::Even,
        CollatzParity::Odd,
        CollatzParity::Even,
        CollatzParity::Odd,
        CollatzParity::Even,
        CollatzParity::Even,
        CollatzParity::Even,
        CollatzParity::Even,
    ])
);

let summary = verify_range(1, 10);

assert_eq!(summary.checked, 10);
assert_eq!(summary.reached_one, 10);
assert_eq!(summary.overflowed, 0);
assert_eq!(summary.max_total_stopping_time, Some((9, 19)));
assert_eq!(summary.max_trajectory_value, Some((7, 52)));

§Status

use-collatz is a concrete pre-1.0 crate in the RustUse math workspace. The API remains intentionally small while adjacent sequence and number-theory crates continue to grow around it. Collatz trajectory utilities for RustUse.

Structs§

CollatzRangeSummary: Summary information for an inclusive range checked with verify_range.

Enums§

CollatzParity: The parity of a positive integer in a Collatz trajectory.

Functions§

collatz_next: Returns the next value in the Collatz trajectory for a positive integer.
collatz_sequence: Returns the full Collatz trajectory from n down to 1.
max_value_in_trajectory: Returns the largest value reached in the trajectory from n to 1.
parity: Returns the parity of a positive input.
parity_vector: Returns the parity pattern for the trajectory from n to 1.
reaches_one: Returns true when the trajectory reaches 1 without overflow.
stopping_time: Returns the number of steps needed to first reach a value smaller than n.
total_stopping_time: Returns the number of steps needed to reach 1.
trajectory_len: Returns the full trajectory length including the starting value and terminal 1.
verify_range: Verifies the inclusive range [start, end] with bounded Collatz exploration.