Butterfly: reproducible periodicity-hub dynamics

This repository turns a 2012 study of Rössler periodicity hubs into a modern program of numerical research with recorded protocols and results. It combines parameter-plane atlases, invariant-orbit continuation, Floquet analysis, chaotic-saddle reconstruction, independent integrators, and explicit negative results.

The project began with Timothy D. Jones's Topological origins of a bi-parameter periodicity hub for the Rössler attractor. Its current purpose is broader: determine which historical claims reproduce, strengthen the mechanisms that survive, correct those that do not, and build methods that can transfer to other strange attractors.

This is an active research repository, not a completed reproduction or an existence proof. The September 2026 audit records corrected software bugs, a retracted Floquet-zero interpretation, and the limits of the current evidence. The next research steps prioritize independent validation and public reproducibility.

For an accessible introduction, the manuscript now puts a short illustrated article before the detailed technical supplement, preserving all earlier figures and adding independent-validation, accuracy, and symbolic-chain diagrams. The main article is organized around the original symbolic reinjection mechanism: why an extra inner return should connect neighboring periods into shrimp chains. It presents that hypothesis before the methods and results, then distinguishes tests of its ingredients from validation of the connections themselves. The core-data replay guide documents the first downloadable-input workflow: one atlas panel and two numerical candidate checks, with explicit limits on what is reproduced.

What the computations currently show

• The source-derived symbolic chain is an explicit reproduction target. A local operational alphabet passes independent checks, but the 23 critical words and their window-to-window connections remain unverified. Testing the predicted p -> p+1 insertion is the central mechanism priority; deeper p -> 2p cascades do not establish it. An independent exact quadratic-map control now reproduces the in-scope unimodal word list and its order under a predeclared notation mapping. This is finite combinatorial support, not verification of the Rössler centers, third-branch words, or connecting arrows. The initial direct-fold experiment tests all 26 candidate intervals with two solvers: ten searches qualify across eight finite-return curve families, while sixteen intervals remain unresolved. Section-grazing jumps and ill-conditioned input curves must not be mistaken for the missing critical geometry. The full event-sheet screen now reproduces all 78 sampled points but flags sixteen intervals for large return-time changes; the ten passing intervals match the qualified fold searches. Accurate points alone do not certify a continuous symbolic map. The first contact localization now finds a primitive six-return cycle close to one measured fold in the full state, across all four representations and both solvers. This closes one numerical gap, not the second critical point, C/D labels or a chain arrow. The latest fresh-response correction restores that local contact after parameter transport: all 513 integrations audit and all sixteen full-state contact/prediction comparisons pass. The earlier projection-only match remains a failed baseline. This is numerical proximity to one fold, not a second critical point or symbolic arrow. Full raw evidence remains local; compact audit receipts and generated figures are available in the repository.
• The shrimp and periodic-window skeleton evolves coherently over eleven sampled planes, b = 0.10, ..., 0.30, within a = 0.05–0.40 and c = 1–20. These are finite-time, single-initial-condition recurrence maps; unresolved pixels are not automatically chaotic.
• The reported Jones hub has the claimed local saddle-focus equilibrium. The Hopf-born period-1 family reaches the reported hub neighborhood, and four numerically localized supercritical period doublings with stable children are independently qualified on that path.
• A separate equilibrium-manifold calculation gives a nearby numerical homoclinic candidate. At fixed c = 10.3084, two integrators and boundary-radius checks place it near a = 0.182643608174. Finding this candidate does not exclude a different connection at the printed a = 0.1798.
• A different endpoint/collocation formulation now reproduces that initial candidate near a ≈ 0.1826436, after passing analytic controls. Its measured tolerance sensitivity is about 4.1e-8 in a; this is not a rigorous error bound or confirmation of the later turn. See EXP-475.
• The stricter radius-by-tolerance grid remains incomplete: five cases pass, one reaches the mesh-refinement cap, and three are skipped. The largest-radius sequence shows tolerance contraction, but neither endpoint-radius comparison is qualified. EXP-476 preserves the failure and documents rounding-sensitive tiny mesh intervals.
• Eighty-one recorded homoclinic candidates—including 78 gauge-aligned pseudo-arclength points—trace the same computed branch. The sampled minimum is about 1.75e-5 above the historical fixed-a section. Its fine turn geometry remains provisional because the ill-conditioned solve has no parameter-error bound. More points on the same branch are not independent confirmations. The figure below retains the 80-point manuscript checkpoint.
• A second orbit family is resolved through eight finite period doublings. These calculations substantially strengthen the finite cascade, but do not prove universality or a global logistic-map conjugacy.
• The Jones and Barrio–Blesa–Serrano papers are treated as independent, near-simultaneous co-discoveries of the return-map topology transition's role in periodicity-hub organization.

The project does not yet claim the printed homoclinic coordinate, uniqueness of the homoclinic connection, global nonintersection, a complete topological explanation of the (a,c) plane, or a computer-assisted existence proof. Those boundaries are part of the result, not fine print.

A visual tour

The symbolic chain behind the proposed spiral mechanism

This redraw retains the 23-word construction from Jones's original Figure 6. Arrow styles distinguish the source's matched transitions, visual-only link, lower-period connections, and period doubling. It shows the historical claim we aim to test; it does not present those arrows as newly reproduced results. The decisive computed figure will join the parameter path, return geometry, corrected orbits, and predicted extra symbol in one window-to-window test.

A newly localized fold/cycle proximity point

The first two points fail the unchanged criterion; the third passes in both solvers and all curve representations, with primitive-period safeguards intact. This measured anchor supports the next branch-dictionary study. It does not already reproduce Jones's C/D words or insertion arrows.

The second object is still separated from that cycle

The same-parameter boundary test completed 136 integrations. Six of eight nominations pass the complete local extra-return checks; two retain near-tangent solver disagreement. The measured pre-grazing inputs do not meet the proximity criterion at any cycle event. This rules out treating our one-fold calibration point as an already verified two-object contact; it neither verifies nor debunks Jones's symbolic chains.

The higher-precision follow-up now supplies an audited decimal reference at all 32 side inputs. It also finds an additional limitation of ordinary paired-solver agreement. This strengthens the numerical foundation, not the still-unverified symbolic-chain claim. The complete polynomial census then checks all 239,072 stored segments: both precision configurations recover the complete accepted sequence, with no unresolved root regions. This is a statement about the numerical polynomials, not an all-root theorem for the flow.

From broad parameter scans to individual shrimp

The left panel gives the global b = 0.2 recurrence atlas. The right panel is a 50-times-finer view of the period-6 landmark band, with corrected-orbit components overlaid instead of inferred solely from pixels.

The Jones homoclinic mechanism under direct numerical audit

Accepted roots, rejected steps, the first local a minimum, the historical section gap, and the fixed numerical defect gate appear in one receipt-bound figure. Failed correctors and conditioning rejections remain visible.

A deep, independently checked returning-arm cascade

Numerically localized real--1 events, stable primitive children, two independent integrators, and finite spacing ratios resolve the returning cascade through a stable period-768 child. Later high-precision work extends the connected finite chain while retaining the boundary between finite evidence and universality.

All 34 manuscript figures and their regeneration commands are indexed in paper/figures/README.md. The animated multi-b atlas is documented under paper/supplement/.

Reproducibility model

Every promoted result is organized around a prospective experiment manifest and a machine-readable receipt:

experiments/manifests/       frozen numerical protocols
artifacts/EXP-*/             full local outputs and raw receipts
docs/experiments/receipts/   compact receipts tracked by Git
docs/findings/               scientific interpretations and claim boundaries
docs/claim-ledger.md         claim-by-claim state of the evidence
docs/updates/                chronological research checkpoints
paper/                       manuscript, bibliography, figures, and supplements

Source commit, solver configuration, acceptance gates, input hashes, and failed checks travel with the result. Negative experiments are preserved so a later narrative cannot silently erase an inconvenient method failure.

The source, manifests, compact receipts, and finished figures are public. Most raw artifacts/ inputs are currently local and are not distributed in this repository. Tests, the CPU smoke check, and manuscript compilation can run from a clean checkout; most historical figure-regeneration commands need those additional inputs. The core bundle supplies an explicit nine-file data/protocol subset for a first public replay and independent-pilot inspection; it is not the full campaign archive. Hashes alone do not provide the remaining missing data.

Quick start

The modern research stack requires Python 3.12 or newer. With uv installed:

uv sync --locked --extra dev
.venv/bin/butterfly verify
.venv/bin/python -m pytest -q

RunPod workflows read RUNPOD_API_KEY from the environment or .env. If you need that workflow, copy the template without overwriting an existing file:

cp -n .env-example .env

See .env-example for required and optional placeholders. Local CPU work requires no API keys. The populated .env file is ignored by Git and must never be committed.

The command-line interface also exposes frozen CPU scans, resumable tiled scans, and Lyapunov-spectrum receipts:

.venv/bin/butterfly --help

Check and build the continuously updated paper with:

.venv/bin/python scripts/check_paper_references.py
latexmk -cd -pdf -interaction=nonstopmode -halt-on-error paper/manuscript.tex

GPU execution is used where large independent ensembles justify it. The Float64 CPU/GPU parity requirements and task-owned RunPod lifecycle are documented in docs/compute/runpod-strategy.md.

Where to read next

• docs/README.md — entry point to the living scientific record.
• docs/next-steps.md — current priorities and acceptance criteria after the public-repository audit.
• docs/claim-ledger.md — historical claim versus current evidence and required closure test.
• docs/TODO.md — active execution queue.
• docs/updates/README.md — chronological progress reports.
• paper/README.md — manuscript build, visual inventory, citation discipline, and writing rules.
• paper/manuscript.tex — current article source.

Legacy MPI program

The original C/MPI parameter-plane scanner remains in src/, hdrs/, and the top-level Makefile as part of the project's computational history. It was written for GNU Make and Linux MPI clusters and contains site-specific build defaults. New scientific work uses the tested Python package and frozen experiment pipeline above unless a legacy reproduction explicitly requires the original scanner.

License

GNU General Public License v2. See LICENSE.