turner-townsend-backend-assessment/collatz

The Collatz conjecture

Original assessment brief: https://github.com/turner-townsend/backend-assessment/blob/master/README.md#the-collatz-conjecture

A Python program that calculates the number of steps in the Collatz sequence (3n + 1 problem) needed to reach 1.

What is the Collatz conjecture?

The Collatz conjecture is an unsolved mathematical problem that defines a sequence:

• Start with any positive integer n
• If n is even: divide by 2
• If n is odd: multiply by 3 and add 1
• Repeat until n reaches 1

The conjecture states that this sequence will always eventually reach 1, regardless of the starting number.

Requirements

• Python 3.9+
• pytest (for running tests)

Usage

python collatz.py

Examples

Please enter a whole number: 1
Result: 0 steps needed to reach 1
Please enter a whole number: 3
Step #1: odd, multiply by 3 and add 1 -> 10
Step #2: even, divide by 2 -> 5
Step #3: odd, multiply by 3 and add 1 -> 16
Step #4: even, divide by 2 -> 8
Step #5: even, divide by 2 -> 4
Step #6: even, divide by 2 -> 2
Step #7: even, divide by 2 -> 1
Result: 8 steps needed to reach 3
Please enter a whole number: 0
Result: 0 steps needed to reach 0
Please enter a whole number: !£$
ERROR: integer required

Features

• Step-by-step output: Shows each transformation in the sequence
• Interactive: Continuous input until Ctrl+C
• Input validation: Handles invalid input gracefully
• Edge cases: Handles 1, 0, and negative numbers by returning 0 steps

Tests

pytest -v

Example output:

➜  collatz git:(main) ✗ pytest -v
============================================== test session starts ==============================================
platform linux -- Python 3.12.2, pytest-8.3.4, pluggy-1.5.0 -- /home/jamey/.venv/bin/python
cachedir: .pytest_cache
rootdir: /home/jamey/Projects/turner-townsend-backend-assessment/collatz
plugins: mock-3.14.0, asyncio-0.21.2
asyncio: mode=Mode.STRICT
collected 6 items

test_collatz.py::test_calculate_steps_for_1 PASSED                                                        [ 16%]
test_collatz.py::test_calculate_steps_for_2 PASSED                                                        [ 33%]
test_collatz.py::test_calculate_steps_for_3 PASSED                                                        [ 50%]
test_collatz.py::test_calculate_steps_for_6 PASSED                                                        [ 66%]
test_collatz.py::test_calculate_steps_for_large_number PASSED                                             [ 83%]
test_collatz.py::test_calculate_steps_for_zero_and_negative PASSED                                        [100%]

=============================================== 6 passed in 0.01s ===============================================

Design notes

• Class-based structure: Encapsulates the calculation logic for easy testing and reuse
• Combined calculation and display: The calculation method handles both computing steps and showing progress
• Edge case handling: Returns 0 steps for numbers ≤ 1
• User-friendly: Clear step-by-step output shows the mathematical process as it happens