Geometric Resonance Engine

GRE — a Python library and research platform for fractal-graph quantum information architecture, built around the Sierpinski triangle as a canonical information geometry. It models quantum walks on fractal graphs, extracts resonance descriptors and attractor signatures from the walk operator spectrum, and maintains a curated corpus of prior experimental data.

Core Research Questions

• Does the Sierpinski graph produce a depth-invariant fixed point at 1/φ ≈ 0.618?
• Can fractal geometry serve as a decoherence-free subspace architecture?
• Which of 7 independent mathematical routes to the Sierpinski triangle converges experimentally?
• How do metallic coin angles (golden, silver, bronze) affect quantum walk spectral dynamics on fractal graphs?

Architecture

gre/
├── core/           Data models: Node, Edge, GraphModel, CircuitModel
├── fractals/       Generators: FractalRegistry, 7 Sierpinski routes
├── simulation/     QuantumWalkSimulator (coined + staggered), entropy metrics
├── quantum/       Circuit mapping: FractalGateLibrary, QuantumWalkCircuitBuilder
├── compiler/       GRC pipeline: GeometryCompiler, ResonanceDescriptorComputer,
│                   AttractorSignatureClassifier, ResonanceDescriptor, WalkResult
├── benchmark/      Metallic-triad sweep: metallic_triad.py (48-combination grid)
└── research/       Corpus: HardwareRunRecord, SierpinskiExperimentRecord,
                    CalibrationSnapshot, provenance chain, query API

The GRC Pipeline

GeometryCompiler.compile() is the main entry point:

from gre.compiler.compiler import GeometryCompiler

compiler = GeometryCompiler()
result = compiler.compile(
    "sierpinski",
    level=4,
    route="ifs",
    strategies=["coined"],          # "coined" or "staggered"
    coin="golden",                # hadamard | grover | fourier | golden | silver | bronze
    walk_steps=20,
    initial_node=0,
)
rd  = result.resonance_descriptor   # spectral_gap, eigenphase_spacing_ratio, …
att = result.attractor_signature    # entropy_trajectory, transfer_class, …

Returns a CompilationResult containing graph structure, symmetry sectors, multiscale partitions, per-strategy walk results, resonance fingerprints, and attractor labels.

Metallic-Angle Triad

Three metallic angles are implemented as single-qubit phase gates registered in FractalGateLibrary:

Each gate implements to_matrix() = diag(1, e^{iΔ}) and is registered as a Qiskit gate in FractalGateLibrary.GATES.

Benchmark Sweep Results

The 48-combination sweep (3 angles × 4 routes × 2 levels × 2 walk models) produces the following key findings:

What the coin angle does NOT change

• Spectral gap (λ₂ of Laplacian): identical at 0.09801 — purely a graph-topological property
• Participation ratio: identical at 26.64 — dominated by graph structure
• Transfer fidelity: identical per geometry — the underlying graph determines transport properties

What the coin angle DOES change

• Eigenphase spacing ratio s₂/s₃ of the unitary walk operator U = S·(C⊗I):

Bronze separates clearly (s₂/s₃ < 1). Golden and silver produce almost identical enormous ratios — their eigenphase degeneracy is a topological artifact of the fractal geometry rather than a coin-specific effect.

Per-geometry transfer fidelity

Run the sweep:

python -m gre.benchmark.metallic_triad

Output saved to tests/test_compiler_fixtures_data/metallic_triad_sweep.json and _summary.json.

Research Corpus

The corpus (imports/) contains 48 artifacts across 6 projects:

• IBM Quantum hardware runs on ibm_herron (kingston, fez), ibm_eagle, ibm_falcon, and simulators
• Sierpinski experiments at recursion levels 3–6 across 5 routes (IFS, Pascal, Rule 90, Hanoi, chaos game)
• Calibration snapshots with physical T1/T2 data for ibmq_perth and ibmq_guadalupe
• Phi-encoding circuits (merkaba, tmt projects)

Query the corpus:

from gre.research import load_corpus, query_runs

corpus, catalog, stats = load_corpus()

# Find all ibm_kingston runs
runs = query_runs(backend="ibm_kingston")
for r in runs:
    print(f"{r.metadata.experiment_id}: fidelity={r.fidelity}")

# Compare new result against historical runs
from gre.research import compare_to_generated
comparison = compare_to_generated(graph_nodes=33, depth=3, backend="ibmq_qasm_simulator")

See docs/corpus_taxonomy.md for evidence classification (historical_real / synthetic_seed / derived_summary) and validation tier definitions.

Installation

pip install -e .

Requirements: Python 3.10+, Qiskit 1.x, NumPy, SciPy, Pydantic 2.x

Running Tests

pytest tests/ -v

Current: 119 tests passing.

Key Design Decisions

• Continuous-time CTQW via normalized Laplacian exponential — always unitary, no staggering collapse
• Dyadic rational vertex deduplication — scale = 2^level prevents hash collisions
• Metallic angles as registered Qiskit gates — single-step primitives in FractalGateLibrary, decomposed to RZ at transpile time
• Eigenphase spacing ratio s₂/s₃ — the coin-sensitive discriminator; distinguishes bronze from golden/silver despite their similar near-degenerate spectra
• Evidence taxonomy — historical_real vs synthetic_seed vs derived_summary, with validation tiers raw → normalized → benchmarked → measured