From 09967ad6d7062d58720e1f3b68d19dbcd1da07d3 Mon Sep 17 00:00:00 2001
From: ddidderr <ddidderr@paul.network>
Date: Sun, 26 Apr 2026 13:48:36 +0200
Subject: [PATCH] docs: explain HCN search algorithm

Add a concise README that documents how the program finds highly composite
numbers. The explanation covers the divisor-count formula, why exponent order
lets the search skip arbitrary numbers, and how the implementation generates
and filters record candidates.

Test Plan:
- Not run; documentation-only change.

Refs: N/A
---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a02771
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# hcn
+
+Find highly composite numbers up to a search limit.
+
+```bash
+cargo run --release -- 1000000000
+```
+
+If no limit is given, the default is `1_000_000_000`.
+
+## Algorithm
+
+A number with prime factorization
+
+```text
+n = 2^a * 3^b * 5^c * ...
+```
+
+has
+
+```text
+(a + 1) * (b + 1) * (c + 1) * ...
+```
+
+divisors.
+
+The exact primes do not affect the divisor count; only the exponents do.
+For a fixed exponent list, the smallest possible number is made by putting the
+largest exponent on the smallest prime:
+
+```text
+a >= b >= c >= ...
+```
+
+If a larger exponent appears on a larger prime, swapping those two exponents
+keeps the divisor count unchanged but makes the number smaller.
+
+So a highly composite number cannot have that shape. If it did, the smaller
+swapped number would already have the same number of divisors, so the original
+number would not be the first record.
+
+That means record candidates are only numbers like:
+
+```text
+2^a * 3^b * 5^c * ...  where a >= b >= c >= ...
+```
+
+All other numbers are redundant for finding new records.
+
+The program:
+
+1. Recursively generates numbers from the first primes.
+2. Only tries exponent sequences where each exponent is no larger than the
+   previous one.
+3. Stops a branch as soon as the number exceeds the search limit.
+4. Computes the divisor count directly from the exponents.
+5. Sorts candidates by number and prints each new divisor-count record.
+
+This avoids factoring every number in the range.