# three-square-balance

This repository supports one object: the **spread-record locations** of the
three-square minimal spread, published as OEIS [A395008](https://oeis.org/A395008).

[Open the interactive visualization](https://nmicic.github.io/three-square-balance/viz/index.html).

For each positive integer n that is a sum of three squares — equivalently n not of
the form 4^a(8b+7), by Legendre's criterion — write

    n = x^2 + y^2 + z^2,   x >= y >= z >= 0.

The **minimal spread** is

    s3(n) = min over all such representations of (x - z),

the spread of the most balanced three-square representation of n. It is the natural
three-square analogue of a balance measure: s3(n) = 0 exactly when n = 3*m^2 (then
x = y = z = m), and it grows as n is forced away from three equal squares.

The sequence documented here is the list of numbers k where s3(k) reaches a new
record value:

    1, 4, 10, 16, 37, 58, 64, 130, 148, 232, 256, 445, 520, 592, 928, 1024, ...

Exactly 65 record locations occur for k < 10^9. The last verified record below that
bound is 973078528, with s3 = 28672.

## Scaling Reason

For every nonnegative k for which s3(k) is defined,

    s3(4k) = 2 * s3(k),

Reason: every representation of 4k has all three parts even. A square is 0 or 1
(mod 4), and three of them sum to 0 (mod 4) only as 0 + 0 + 0, so a, b, c are all
even and 4k = a^2+b^2+c^2 is exactly 4 times a representation of k. Consequently
each primitive record location has a forced scaling orbit k, 4k, 16k, ..., and the
verified record sequence below 10^9 is the increasing merge of the surviving terms
from the six primitive records

    1, 10, 37, 58, 130, 445.

Seed 10 contributes only its first term (40, 160, ... are overtaken by the 37
chain); the other five seeds contribute their full 4^j chains. That these six
primitive seeds are complete — no seventh — is exhaustively verified for k < 10^9
and is the only part of the description that is conjectural beyond that bound.

## Main Sequence

- `sequences/spread-record-locations/` — definition, b-file (65 verified terms,
  offset 1), and a short PARI/GP scanner.
- `data/records_to_1e9_COMPLETE.txt` — retained exact scan: the 65 record
  locations and their spread values for k < 10^9.
- `data/record_decompositions_verified.txt` — canonical minimal-spread triples
  (x, y, z) for those 65 verified records.

## Programs

- `src/threesquare.c` — fast exact OpenMP engine for s3(n): record scans,
  b-file output, and tuple dumps. Long record scans are signal-safe and resumable.
- `src/validate_s3.c` — an **independent** validator (ascending-x search, single
  thread) that reimplements s3 from scratch, so agreement with `threesquare.c`
  (descending search) is a genuine cross-check, not a shared bug. It confirms the
  doubling law, the six-seed closure, and the b-file.
- `src/threesquare.py` — small pure-Python reference for s3(n) and the minimal
  triple.
- `src/records.gp` — PARI/GP: a definitional record scanner and the constructive
  six-seed chain description, with a self-test that the two agree.
- `loda/A395008.asm` — [LODA](https://loda-lang.org) assembly program for
  A395008, in the format used by the loda-programs collection. It stores
  a(1)..a(12) and applies the observed recurrence a(n) = 4*a(n-5) for n >= 13.
  See `loda/README.md`; `sh loda/check.sh` verifies it against the b-file.

Build and run the checks:

    cd src
    make
    make check

On macOS, Apple clang needs libomp (`brew install libomp`); see the comment at the
top of `src/Makefile`.

## Visualization

`viz/index.html` visualizes three-square shape directions, the all-representable
cloud, and the 65 verified spread-record locations:

[https://nmicic.github.io/three-square-balance/viz/index.html](https://nmicic.github.io/three-square-balance/viz/index.html)

See `viz/README.md`.

## Archive

`archive/` holds an exploratory companion object (the record spread *values*) that is
not part of the spread-record-location focus. It is kept for reproducibility context;
the active repository surface is intentionally the single sequence above.

## License

Apache-2.0. See `LICENSE`.