Skip to content

Commit ed20529

Browse files
d4rkd0sd4rkd0s
committed
Update README for clarity and add GitHub Actions workflow for automated builds and releases
1 parent 6667fb0 commit ed20529

File tree

2 files changed

+132
-150
lines changed

2 files changed

+132
-150
lines changed

‎.github/workflows/release.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
name: Build and Release
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
workflow_dispatch: {}
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
build:
13+
name: Build (${{ matrix.target }})
14+
runs-on: ${{ matrix.os }}
15+
strategy:
16+
fail-fast: false
17+
matrix:
18+
include:
19+
- os: ubuntu-latest
20+
target: x86_64-unknown-linux-gnu
21+
bin: rust_collatz_solution
22+
archive: rust_collatz_solution-linux-x86_64.tar.gz
23+
- os: windows-latest
24+
target: x86_64-pc-windows-msvc
25+
bin: rust_collatz_solution.exe
26+
archive: rust_collatz_solution-windows-x86_64.zip
27+
- os: windows-latest
28+
target: i686-pc-windows-msvc
29+
bin: rust_collatz_solution.exe
30+
archive: rust_collatz_solution-windows-i686.zip
31+
32+
steps:
33+
- name: Checkout
34+
uses: actions/checkout@v4
35+
36+
- name: Install Rust (${{ matrix.target }})
37+
uses: dtolnay/rust-toolchain@stable
38+
with:
39+
targets: ${{ matrix.target }}
40+
41+
- name: Build
42+
run: cargo build --release --target ${{ matrix.target }}
43+
44+
- name: Package (Linux)
45+
if: runner.os == 'Linux'
46+
shell: bash
47+
run: |
48+
set -euxo pipefail
49+
mkdir -p package
50+
cp target/${{ matrix.target }}/release/${{ matrix.bin }} package/
51+
cp README.md package/ || true
52+
tar -C package -czf ${{ matrix.archive }} .
53+
54+
- name: Package (Windows)
55+
if: runner.os == 'Windows'
56+
shell: bash
57+
run: |
58+
set -euxo pipefail
59+
mkdir -p package
60+
cp target/${{ matrix.target }}/release/${{ matrix.bin }} package/
61+
cp README.md package/ || true
62+
7z a -tzip ${{ matrix.archive }} package/*
63+
64+
- name: Upload artifact
65+
uses: actions/upload-artifact@v4
66+
with:
67+
name: ${{ matrix.archive }}
68+
path: ${{ matrix.archive }}
69+
70+
release:
71+
name: Create GitHub Release
72+
runs-on: ubuntu-latest
73+
needs: [ build ]
74+
steps:
75+
- name: Compute short SHA
76+
id: vars
77+
shell: bash
78+
run: echo "short_sha=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"
79+
80+
- name: Download all artifacts
81+
uses: actions/download-artifact@v4
82+
with:
83+
path: dist
84+
85+
- name: Create GitHub Release and upload assets
86+
uses: softprops/action-gh-release@v2
87+
with:
88+
name: build-${{ steps.vars.outputs.short_sha }}
89+
tag_name: build-${{ steps.vars.outputs.short_sha }}
90+
draft: false
91+
prerelease: false
92+
files: dist/**/*
93+
env:
94+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
95+

‎README.md‎

Lines changed: 37 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,50 @@
1-
# Rust Collatz Solution
1+
rust_collatz_solution
2+
=====================
23

3-
A high-performance Rust implementation for randomly searching potential counterexamples to the Collatz conjecture using arbitrary-precision arithmetic. **The random search space by default is 2^68 to 2^2000.**
4+
A high‑performance Collatz explorer with big‑integer support and a lightweight visualizer.
45

5-
<img width="500" height="531" alt="image" src="https://github.com/user-attachments/assets/05894ec5-fdf6-407f-ba98-85f0ee8044a4" />
6+
- Arbitrary precision via `num-bigint::BigUint` (explores up to 2^2000 and beyond)
7+
- O(1) memory cycle detection (Floyd’s algorithm)
8+
- Random‑shot mode by default across [2^68, 2^2000−1]
9+
- Minimal disk writes: only writes `solution.txt` when a finding occurs
10+
- Optional 500×500 GUI (minifb) animates trajectories and shows the current seed
611

7-
To run just download the repo and run, `cargo run`.
12+
Quick Start
13+
-----------
814

9-
## Overview
15+
- Run with defaults (random scanning + viz):
16+
- `cargo run --release --`
17+
- More frequent visualization updates:
18+
- `cargo run --release -- --viz-interval 100 --viz-max-steps 3000`
19+
- Sequential (no random), starting at a value:
20+
- `cargo run --release -- --no-random --start 100000000000000000000`
1021

11-
This program searches for numbers that either:
12-
- Enter a nontrivial cycle (not the known 1→4→2→1 loop)
13-
- Create runaway sequences that exceed computational limits
22+
Note: When using `cargo run`, pass program flags after `--` so Cargo doesn’t parse them.
1423

15-
The implementation uses Floyd's cycle-finding algorithm with O(1) memory complexity and supports arbitrary-precision integers via the `num-bigint` crate.
24+
CLI Flags
25+
---------
1626

17-
## Features
27+
- `--start <DECIMAL>`: starting value (decimal string); used when `--no-random`.
28+
- `--count <N>`: stop after testing N starts (for experiments/testing).
29+
- `--solution <PATH>`: path for the single‑line solution file (default `solution.txt`).
30+
- `--random` / `--no-random` (default `--random`): random shots vs sequential scan.
31+
- `--viz` / `--no-viz` (default `--viz`): enable/disable the visualizer.
32+
- `--viz-interval <N>`: send a new seed to the GUI every N starts (default 1000).
33+
- `--viz-max-steps <N>`: sliding window width for the animated line (default 10,000).
1834

19-
- **Arbitrary-precision arithmetic**: Handle extremely large numbers beyond standard integer limits
20-
- **Memory-efficient cycle detection**: Uses Floyd's tortoise-and-hare algorithm
21-
- **Resumable execution**: Automatically resume from the last processed number
22-
- **Random sampling mode**: Test random numbers in configurable ranges
23-
- **Progress tracking**: Real-time progress monitoring with configurable intervals
24-
- **Solution detection**: Automatically saves any discovered counterexamples
25-
- **Real-time visualization**: Optional graphical display of Collatz sequences
35+
Output
36+
------
2637

27-
## Building
38+
- `solution.txt`: written and fsynced on first finding, then the app exits.
39+
- Formats: `NONTRIVIAL_CYCLE_START <n>` or `RUNAWAY_STEPS_OVERFLOW_START <n>`.
2840

29-
### Prerequisites
30-
- Rust (latest stable version recommended)
31-
- Cargo (comes with Rust)
41+
Releases
42+
--------
3243

33-
### Build Commands
44+
This repo includes a GitHub Actions workflow that builds and publishes archives per commit (tagged by short SHA) for:
3445

35-
```bash
36-
# Debug build
37-
cargo build
46+
- Linux x86_64 (GNU)
47+
- Windows x86_64 (MSVC)
48+
- Windows i686 (MSVC)
3849

39-
# Optimized release build (recommended for actual searching)
40-
cargo build --release
41-
42-
# Run tests
43-
cargo test
44-
```
45-
46-
## Running
47-
48-
### Basic Usage
49-
50-
```bash
51-
# Run with default settings (starts at 2^68, runs indefinitely)
52-
cargo run --release
53-
54-
# Run in random sampling mode
55-
cargo run --release -- --random
56-
57-
# Start from a specific number
58-
cargo run --release -- --start 1000000
59-
60-
# Process a limited number of values
61-
cargo run --release -- --count 10000
62-
63-
# Start from specific number and process limited count
64-
cargo run --release -- --start 500 --count 1000
65-
```
66-
67-
### Command Line Options
68-
69-
| Option | Short | Description | Default |
70-
|--------|-------|-------------|---------|
71-
| `--start <N>` | `-s <N>` | Starting number for sequential search | 2^68 or resume point |
72-
| `--count <N>` | `-n <N>` | Maximum numbers to process | Unlimited |
73-
| `--random` | | Enable random sampling mode | Sequential mode |
74-
| `--resume` | | Resume from last progress (default) | Enabled |
75-
| `--no-resume` | | Start fresh, ignore previous progress | |
76-
| `--output <FILE>` | `-o <FILE>` | Progress tracking file | `progress.txt` |
77-
| `--progress <FILE>` | | Alias for `--output` | `progress.txt` |
78-
| `--solution <FILE>` | | Solution output file | `solution.txt` |
79-
| `--progress-interval <N>` | `-pi <N>` | Progress update frequency | 1000 |
80-
| `--viz` | | Enable real-time visualization window | Disabled |
81-
| `--viz-interval <N>` | | Visualization update frequency | 50000 |
82-
| `--viz-max-steps <N>` | | Maximum steps to render in visualization | 10000 |
83-
84-
### Examples
85-
86-
```bash
87-
# Quick test run starting from 1
88-
cargo run --release -- --start 1 --count 100 --no-resume
89-
90-
# Random sampling for 1 million iterations
91-
cargo run --release -- --random --count 1000000
92-
93-
# Resume previous session with custom progress file
94-
cargo run --release -- --output my_progress.txt
95-
96-
# High-frequency progress updates
97-
cargo run --release -- --progress-interval 100
98-
99-
# Start from a very large number
100-
cargo run --release -- --start 123456789012345678901234567890
101-
102-
# Enable visualization for small numbers
103-
cargo run --release -- --start 27 --count 10 --viz
104-
105-
# Visualization with custom update frequency
106-
cargo run --release -- --random --viz --viz-interval 1000 --viz-max-steps 5000
107-
```
108-
109-
## Output Files
110-
111-
### progress.txt
112-
Contains the last processed number. The program automatically resumes from this point when restarted (unless `--no-resume` is specified).
113-
114-
### solution.txt
115-
If a counterexample is found, this file will contain one of:
116-
- `NONTRIVIAL_CYCLE_START <number>` - Found a cycle that doesn't include 1
117-
- `RUNAWAY_STEPS_OVERFLOW_START <number>` - Found a sequence that exceeded step limits
118-
119-
## Algorithm Details
120-
121-
### Collatz Function
122-
For any positive integer n:
123-
- If n is even: n → n/2
124-
- If n is odd: n → 3n + 1
125-
126-
### Cycle Detection
127-
Uses Floyd's cycle-finding algorithm:
128-
1. Initialize tortoise and hare pointers
129-
2. Advance tortoise by 1 step, hare by 2 steps each iteration
130-
3. When they meet, a cycle is detected
131-
4. Determine if the cycle contains 1 (normal) or not (counterexample)
132-
133-
### Random Mode
134-
When `--random` is specified:
135-
- Samples numbers uniformly from the range [2^68, 2^2000 - 1]
136-
- Uses a custom xorshift128+ PRNG for reproducible results
137-
- Useful for statistical sampling of very large number spaces
138-
139-
### Visualization Mode
140-
When `--viz` is specified:
141-
- Opens a 500x500 pixel window showing real-time Collatz sequence plots
142-
- X-axis represents steps in the sequence, Y-axis represents bit-length of values
143-
- White lines trace the trajectory from start to 1 (or until max steps)
144-
- Press ESC to close the visualization window
145-
- Updates at configurable intervals to balance performance and visual feedback
146-
147-
## Performance Tips
148-
149-
1. **Always use `--release`**: Debug builds are significantly slower
150-
2. **Adjust progress interval**: Lower values provide more frequent updates but slight performance overhead
151-
3. **Use SSD storage**: Frequent progress writes benefit from fast disk I/O
152-
4. **Consider random mode**: For very large starting points, random sampling may find counterexamples faster
153-
154-
## Implementation Notes
155-
156-
- Uses `num-bigint` for arbitrary-precision arithmetic
157-
- Implements overflow detection to prevent infinite loops
158-
- All file operations include explicit `sync_all()` calls for crash safety
159-
- Progress is atomic - either fully written or not written at all
160-
161-
## License
162-
163-
This project is open source. Please check the repository for license details.
50+
Each archive includes the compiled executable. See the Releases tab for downloads.

0 commit comments

Comments
 (0)