Metadata-Version: 2.4
Name: geometric-resonance-engine
Version: 0.1.0
Summary: Hybrid classical+quantum platform centered on fractal geometry as information architecture
Author: Geometric Resonance Engine Contributors
License: MIT
License-File: LICENSE
Keywords: fractal,geometry,quantum,quantum-walk,resonance,sierpinski
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: plotly>=5.18
Requires-Dist: pydantic>=2.5
Requires-Dist: qiskit-ibm-provider>=0.7
Requires-Dist: qiskit>=1.0
Requires-Dist: scipy>=1.11
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: black>=23; extra == 'dev'
Requires-Dist: mypy>=1.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```python
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`:

| Angle  | Phase Δ (rad)      | Gate | Coin key |
|--------|--------------------|------|----------|
| Golden | (3−√5)π ≈ 2.400 | `GoldenAngleRZGate` | `"golden"` |
| Silver | π(2−√2) ≈ 1.840  | `SilverAngleRZGate` | `"silver"` |
| Bronze | 2π(1−1/(2+∛3)) ≈ 2.471 | `BronzeAngleRZGate` | `"bronze"` |

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):

| Angle  | s₂/s₃ (coined walk) | Interpretation |
|--------|---------------------|----------------|
| bronze | **0.488** | Near-Poisson spacing — phase correlations suppressed |
| golden | **≈ 10¹⁰** | Near-degenerate eigenphase pair |
| silver | **≈ 10¹⁰** | Near-degenerate eigenphase pair |

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
| Geometry | Model | Transfer fidelity |
|----------|--------|-------------------|
| hanoi    | staggered | **0.050** (best) |
| ifs      | staggered | 0.006 |
| pascal_mod2 | staggered | 0.003 |
| rule90   | both | 0 (uniform spread) |

Run the sweep:

```bash
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:

```python
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

```bash
pip install -e .
```

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

## Running Tests

```bash
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
