# E126: Hexagonal number spiral structure

**size 101: 10,201 numbers and 1,252 primes**
```{figure} ../_static/experiments/e126_hero_101.png
:width: 80%
:alt: Hexagonal number spiral preview (size 101)
```

**size 201: 40,401 numbers and 4,236 primes**
```{figure} ../_static/experiments/e126_hero_201.png
:width: 80%
:alt: Hexagonal number spiral preview (size 201)
```

**size 301: 90,601 numbers and 8,769 primes**
```{figure} ../_static/experiments/e126_hero_301.png
:width: 80%
:alt: Hexagonal number spiral preview (size 301)
```

**size 401: 160,801 numbers and 14,752 primes**
```{figure} ../_static/experiments/e126_hero_401.png
:width: 80%
:alt: Hexagonal number spiral preview (size 401)
```

**size 999: 998,001 numbers and 78,359 primes**
```{figure} ../_static/experiments/e126_hero_999.png
:width: 80%
:alt: Hexagonal number spiral preview (size 999)
```
*Prime counts shown are $\pi(\text{size}^2)$, i.e., the number of primes $\le \text{size}^2$.*

**Tags:** `number-theory`, `quantitative-exploration`, `visualization`  
See: {doc}`../tags`.

## Highlights

- Arranges integers on a **hexagonal lattice** using a centered spiral enumeration.
- Parameterizable run: vary `--size` from the command line (default: `301`).
- Writes reproducible artifacts (`params.json`, `report.md`, and figures) into `out/e126/`.

## Goal

Render a **hexagonal number spiral** and highlight primes to reveal lattice-aligned structures,
then compare how that structure changes as `size` increases.

## Background (quick refresher)

### What is a hexagonal number spiral?

A **hexagonal number spiral** places integers on a hexagonal grid, starting at the center with $1$ and then spiraling outward.
Compared to the square-lattice Ulam spiral, the hex lattice emphasizes different geometric alignments and may reveal
different-looking prime structures. See {cite}`Kurzweg2020HexagonalIntegerSpiral`.

### Optional background pages

- {doc}`../background/prime-numbers`
- {doc}`../background/quadratic-polynomials`
- {doc}`../background/eulers-prime-generating-polynomial`

## Research question

Which geometric structures appear when primes are highlighted on a hexagonal spiral, and how stable are they
as `size` increases (i.e., as we include integers up to $\text{size}^2$)?

## Why this qualifies as a mathematical experiment

- **Finite procedure:** enumerate a finite spiral placement for integers $1,\dots,\text{size}^2$ and run a deterministic primality test up to $\text{size}^2$.
- **Observable(s):** lattice-aligned streaks/clusters and how visibility changes with `size`.
- **Parameter space:** `size` (and, if you extend it, coordinate convention / rendering choices).
- **Outcome:** figures and a short report capturing the key observation and caveats.
- **Reproducibility:** outputs saved to `out/e126/` with a parameter snapshot.

## Experiment design

- **Computation:** map integers $1,\dots,\text{size}^2$ to hex-lattice coordinates using a centered spiral enumeration; mark primes.
- **Coordinates:** integers are mapped to axial hex coordinates $(q,r)$ on a hex grid and embedded into the plane via $x = q + \tfrac{1}{2}r$ and $y = \tfrac{\sqrt{3}}{2}r$.
- **Prime classification:** primes are computed using a sieve up to $\text{size}^2$.

- **Outputs:** one or more scatter plots of prime points on the hex lattice (composites omitted).
- **Artifacts written:**
  - `figures/fig_01_hex_spiral*.png` (main figure) and `figures/e126_hero_<size>.png` (published hero)
  - `params.json`
  - `report.md`

## How to run

```bash
make run EXP=e126
```

Override the experiment size:

```bash
make run EXP=e126 ARGS="--size 501"
```

Direct invocation (always works):

```bash
uv run --extra dev python -m mathxlab.experiments.e126 --out out/e126 --size 501
```

## Notes / pitfalls

- Different conventions exist for hex-spiral enumeration; changing the convention can change visible structures.
- Larger `size` means more numbers ($\text{size}^2$) and a longer run time.
- “Looks-true” trap: lattice-aligned streaks do not prove a statement about primes.

## Extensions

- Overlay ring boundaries (or distance-from-center contours) to relate features to the spiral geometry.
- Add simple quantitative overlays: density by hex-ring index or by lattice direction.
- Compare hex vs. square spirals at matched `N` (same number of integers).

## Published run snapshot

If this experiment is included in the docs gallery, include the published snapshot (report + params).

```{include} ../reports/e126.md
:start-after: "<!-- REPORT:BEGIN -->"
:end-before: "<!-- REPORT:END -->"
```

::: {dropdown} params.json (snapshot)
:open:

```{literalinclude} ../params/e126.json
:language: json
```

:::

## References

- Hex spiral background and construction ideas: {cite}`Kurzweg2020HexagonalIntegerSpiral`.
- Exposition connecting multiple prime visualizations: {cite}`Brockmann2019PrimeTime`.
- Recreational-math context and “pattern traps”: {cite}`gardner1983martin`, {cite}`hoffman1989archimedes`.

See also {doc}`../references`.

## Related experiments

- {doc}`e024` (Ulam spiral structure)
- {doc}`e124` (Klauber triangle structure)
- {doc}`e125` (Sacks spiral structure)
- {doc}`e127` (Quadratic prime-run atlas ($n^2 + a n + b$))
- {doc}`e128` (Quadratic modular obstructions (Euler-type))
- {doc}`e129` (Euler lucky constants for $n^2 + n + b$)

## Parameters (example)

- size: `301` (implied total integers: `1..90,601`)

### Recommended `size` range

The hex spiral run includes integers $1,\dots,\text{size}^2$, so runtime and memory scale roughly with $\text{size}^2$ (because about $\text{size}^2$ integers are classified as prime/not-prime).

A practical range that works well for most runs:

- **Minimum (still meaningful):** `size = 101`
- **Default / recommended:** `size = 301`
- **Comfortable upper range on typical laptops (varies):** `size = 999`
- **Above ~`size = 1501`:** expect noticeably higher runtime (and potentially memory pressure), depending on the machine and the primality implementation.

**Rule of thumb:** start with `301`, then try `501`, `701`, `901`. Increase further only if runtime remains acceptable.

## Summary

We enumerate a hex-lattice spiral placement for the first 90,601 positive integers and highlight primes.
At this scale, lattice-aligned structures can be visible: some directions show denser prime “streaks” than others.

## Key observations

- Prime points show directional structure aligned to the hex lattice.
- Some structures are subtle and become easier to see with larger `size` and careful marker sizing.

## Interpretation

The hex spiral is an alternative geometry for indexing the same integers.
As with the Ulam spiral, geometric placement can visually emphasize prime-rich progressions or polynomial-like sequences.
This is a strong exploratory tool — but not evidence of a global law of primes.

## Caveats

- Different enumeration conventions change the picture.
- Finite window: patterns can look stronger/weaker depending on the chosen `size` and zoom level.
- Visualization choices matter: marker size, DPI, and axis limits can hide or exaggerate structure.