QuantaSight 0.1.0__tar.gz

quantasight-0.1.0/PKG-INFO

@@ -0,0 +1,1492 @@
+Metadata-Version: 2.4
+Name: QuantaSight
+Version: 0.1.0
+Summary: Framework-independent contextual quantum reference and deterministic residual-projection library.
+Author: Onur Kavrık
+Maintainer: Biotronics AI
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy==2.5.3
+Provides-Extra: pennylane
+Requires-Dist: pennylane==0.45.1; extra == "pennylane"
+Requires-Dist: pennylane-lightning==0.45.0; extra == "pennylane"
+Provides-Extra: qiskit
+Requires-Dist: qiskit==2.5.2; extra == "qiskit"
+Requires-Dist: qiskit-aer==0.17.2; extra == "qiskit"
+Provides-Extra: cirq
+Requires-Dist: cirq==1.7.0; extra == "cirq"
+Provides-Extra: plot
+Requires-Dist: matplotlib==3.11.2; extra == "plot"
+Provides-Extra: all
+Requires-Dist: pennylane==0.45.1; extra == "all"
+Requires-Dist: pennylane-lightning==0.45.0; extra == "all"
+Requires-Dist: qiskit==2.5.2; extra == "all"
+Requires-Dist: qiskit-aer==0.17.2; extra == "all"
+Requires-Dist: cirq==1.7.0; extra == "all"
+Requires-Dist: matplotlib==3.11.2; extra == "all"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: maintainer
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+> **Current release:** `0.1.0` (Alpha)
+
+# Quantra
+
+> **Author:** Onur Kavrik
+> **Maintainer:** Biotronics AI
+> **License:** MIT
+
+**Context-aware, framework-independent quantum error correction through
+deterministic reference tracking and residual projection.**
+
+Quantra is a context-aware quantum error-correction framework designed
+around a fundamental distinction: **not every deviation observed during
+quantum computation is an error**. Changes produced legitimately by the
+input data, circuit structure, gate sequence, parameterization, and the
+intended evolution of the quantum state belong to the computational
+context and must be preserved rather than corrected away.
+
+Instead of treating every measured deviation as noise, Quantra tracks
+the expected evolution of the computation within its circuit and data
+context. It parses supported **PennyLane**, **Qiskit**, and **Cirq**
+circuits into a framework-independent intermediate representation and
+constructs an independent deterministic reference trajectory through
+the legitimate circuit evolution. This allows Quantra to distinguish
+context-preserving computational evolution from residual deviations
+observed outside that expected trajectory.
+
+The objective is therefore not merely to suppress deviation, but to
+**correct error without destroying computational context**. Quantra is
+designed to preserve the information encoded by the input and the
+legitimate transformations performed by the circuit while isolating
+the residual component relative to the contextual expected reference.
+Under its deterministic residual-projection contract, the measured
+result is projected exactly back onto that contextual reference, up to
+numerical precision. Consequently, deviations represented by that
+residual are completely eliminated in the correction domain while the
+legitimate data- and circuit-dependent evolution represented by the
+reference is retained.
+
+Formally, for a measured result \(M\) and contextual expected reference
+\(\hat{E}\), Quantra defines
+
+\[
+R = M - \hat{E}
+\]
+
+and performs
+
+\[
+M_{\mathrm{corr}} = M - R.
+\]
+
+Therefore,
+
+\[
+M_{\mathrm{corr}} = \hat{E},
+\]
+
+up to numerical precision. This exact-reference recovery is an
+algebraic property of Quantra's deterministic projection model rather
+than a hardcoded correction percentage.
+
+A particularly important property of this architecture is that the
+correction operation itself does **not require a large statistical
+ensemble of repeated shots**. Quantra can perform its contextual
+residual-projection workflow even when the execution is configured with
+`shots=1`, provided that the measurement semantics and contextual
+reference required by the correction contract are available. This
+makes single-shot operation a first-class execution mode rather than
+requiring repeated measurements merely to define the correction step.
+
+This distinction is potentially important for quantum-hardware
+efficiency. Conventional statistical error-mitigation and
+characterization workflows can require repeated circuit executions to
+estimate expectation values, noise characteristics, or corrected
+quantities. Quantra's deterministic correction stage is structurally
+different: it operates on the individual normalized measurement result
+relative to its independently established contextual reference.
+Reducing dependence on repeated sampling at the correction stage can
+therefore be valuable where QPU executions, queue time, or shot budgets
+are expensive.
+
+Single-shot correction should not, however, be confused with obtaining
+an exact statistical estimate of an unknown quantum probability
+distribution from one physical measurement. Quantra does not claim that
+a single stochastic observation contains such information. Rather, its
+single-shot capability follows from the fact that correction is
+**reference-assisted and context-aware instead of being derived solely
+from statistical reconstruction of repeated noisy measurements**.
+
+Quantra therefore focuses on two complementary quantities:
+
+- **Precise correction ratio**, which quantifies how much of the
+  measured deviation relative to the contextual reference has been
+  removed by correction; and
+- **Context preservation**, which requires legitimate evolution caused
+  by the data and circuit itself to remain part of the expected
+  computation rather than being misclassified as error.
+
+This combination — contextual discrimination, deterministic residual
+projection, exact recovery of the supplied contextual reference, and
+support for correction at single-shot execution — is the central design
+principle behind Quantra.
+
+---
+
+## Contents
+
+- [Overview](#overview)
+- [What Quantra Does](#what-quantra-does)
+- [Scientific Interpretation](#scientific-interpretation)
+- [Supported Frameworks](#supported-frameworks)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Framework Examples](#framework-examples)
+  - [PennyLane](#pennylane)
+  - [Qiskit](#qiskit)
+  - [Cirq](#cirq)
+- [QuantraResult](#quantraresult)
+- [Correction Model](#correction-model)
+- [Measurement Semantics](#measurement-semantics)
+- [Reference Engine](#reference-engine)
+- [Runtime and Device Selection](#runtime-and-device-selection)
+- [Audit and Provenance](#audit-and-provenance)
+- [Visualization](#visualization)
+- [Cross-Framework Behavior](#cross-framework-behavior)
+- [Validated Scenarios](#validated-scenarios)
+- [Current Limitations](#current-limitations)
+- [Error Handling](#error-handling)
+- [Package Architecture](#package-architecture)
+- [Developer Installation](#developer-installation)
+- [Testing](#testing)
+- [Design Principles](#design-principles)
+- [Roadmap](#roadmap)
+- [Citation](#citation)
+- [License](#license)
+- [Disclaimer](#disclaimer)
+
+---
+
+## Overview
+
+Quantra is designed to provide a consistent analysis contract across
+multiple quantum software frameworks.
+
+A typical Quantra workflow is:
+
+```text
+Framework-native circuit
+        |
+        v
+Circuit adaptation
+        |
+        v
+Framework-independent IR
+        |
+        +----------------------+
+        |                      |
+        v                      v
+Deterministic reference     Native execution
+trajectory                     |
+        |                      v
+        |                Measurement result
+        |                      |
+        +----------+-----------+
+                   |
+                   v
+       Semantic normalization
+                   |
+                   v
+          measured / expected
+                   |
+                   v
+       residual = measured - expected
+                   |
+                   v
+       corrected = measured - residual
+                   |
+                   v
+       metrics + provenance + audit
+                   |
+                   v
+              QuantraResult
+```
+
+The current automatic correction domain is the **computational-basis
+probability domain**.
+
+Quantra is intentionally conservative about ambiguous measurement
+semantics. When a framework result cannot be mapped safely into the
+supported correction domain, Quantra fails closed rather than guessing.
+
+---
+
+## What Quantra Does
+
+Quantra currently provides:
+
+- A single high-level public facade: `Quantra.Quantra`
+- PennyLane circuit support
+- Qiskit circuit support
+- Cirq circuit support
+- Framework-independent circuit parsing
+- Canonical circuit event chronology
+- Deterministic pure-state reference propagation
+- Computational-basis probability references
+- Single-shot execution
+- Multi-shot execution
+- Framework-aware sample/count normalization
+- Canonical qubit-order normalization
+- Qiskit classical-bit mapping support
+- PennyLane permuted measurement-wire support
+- Cirq permuted measurement-order support
+- Residual calculation
+- Deterministic residual projection
+- Correction metrics
+- Provenance tracing
+- Observable correction-dataflow leakage auditing
+- Immutable result aggregation
+- Optional result visualization
+- CPU execution
+- Explicit runtime/device selection infrastructure
+- Explicit backend support where supported by the underlying execution
+  path
+
+Quantra does **not** reinterpret arbitrary numeric framework outputs as
+probabilities. Measurement semantics must be supported and unambiguous.
+
+---
+
+## Scientific Interpretation
+
+Quantra's deterministic residual projection is defined by:
+
+\[ R = M - `\hat{E}`{=tex} \]
+
+and
+
+\[ M\_{`\mathrm{corr}`{=tex}} = M - R \]
+
+where:
+
+- \(M\) is the normalized measured result,
+- (`\hat{E}`{=tex}) is the independently propagated contextual
+  expected reference,
+- \(R\) is the residual,
+- (M\_{`\mathrm{corr}`{=tex}}) is the corrected result.
+
+Substitution gives:
+
+\[ M\_{`\mathrm{corr}`{=tex}} = M - (M - `\hat{E}`{=tex}) =
+`\hat{E}`{=tex} \]
+
+Therefore, when the same supplied reference is used in the residual
+definition, exact deterministic projection recovers that reference
+algebraically, up to numerical tolerance.
+
+### Important interpretation of 100% recovery
+
+A reported recovery value of `100.0` in this deterministic projection
+setting means:
+
+> **100% recovery of the contextual expected reference under the
+> deterministic residual-projection definition.**
+
+It must **not** be interpreted as:
+
+- universal physical quantum error correction,
+- proof that an unknown hardware error was inferred from a single
+  shot,
+- proof of fault-tolerant quantum computation,
+- proof that arbitrary QPU noise has been physically removed,
+- a guarantee that an estimated or imperfect reference is physically
+  exact.
+
+The recovery metric is calculated from the pre- and post-correction mean
+absolute errors. It is not hardcoded to 100%.
+
+For nonzero pre-correction error:
+
+\[ `\mathrm{Recovery}`{=tex} = 100 `\left`{=tex}( 1 -
+`\frac{\mathrm{post\_MAE}}`{=tex} {`\mathrm{pre\_MAE}`{=tex}}
+`\right`{=tex}) \]
+
+If the pre-correction error is effectively zero, recovery percentage is
+treated as undefined rather than manufacturing a percentage.
+
+---
+
+## Supported Frameworks
+
+Quantra `0.1.0` targets the following validated framework versions:
+
+  Framework               Validated version
+
+---
+
+  PennyLane                          0.45.1
+  PennyLane Lightning                0.45.0
+  Qiskit                              2.5.2
+  Qiskit Aer                         0.17.2
+  Cirq                                1.7.0
+  NumPy                               2.5.3
+
+The development and regression environment also includes Python 3.14.
+
+The package metadata currently declares Python `>=3.11`.
+
+---
+
+## Installation
+
+The PyPI distribution name is lowercase:
+
+```bash
+pip install quantra
+```
+
+The Python import package is capitalized:
+
+```python
+import Quantra
+```
+
+### Core installation
+
+Install the minimal Quantra core:
+
+```bash
+pip install quantra
+```
+
+### PennyLane support
+
+```bash
+pip install "quantra[pennylane]"
+```
+
+### Qiskit support
+
+```bash
+pip install "quantra[qiskit]"
+```
+
+### Cirq support
+
+```bash
+pip install "quantra[cirq]"
+```
+
+### Plotting support
+
+```bash
+pip install "quantra[plot]"
+```
+
+### Install all supported integrations
+
+```bash
+pip install "quantra[all]"
+```
+
+The `all` extra installs the supported PennyLane, Qiskit, Cirq, Qiskit
+Aer, PennyLane Lightning, and plotting dependencies configured for the
+release.
+
+---
+
+## Quick Start
+
+The public API is intentionally small.
+
+```python
+import Quantra
+
+quantra = Quantra.Quantra(
+    circuit,
+    device="cpu", #"cpu", "gpu" or "qpu"
+    shots=1,
+)
+
+result = quantra.run()
+```
+
+You can then access:
+
+```python
+print(result.measured)
+print(result.expected)
+print(result.residual)
+print(result.corrected)
+
+print(result.pre_mae)
+print(result.post_mae)
+print(result.recovery_percentage)
+
+print(result.audit_clean)
+print(result.reference_mode)
+```
+
+You may also import the facade directly:
+
+```python
+from Quantra import Quantra
+
+quantra = Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+)
+
+result = quantra.run()
+```
+
+---
+
+## Framework Examples
+
+The following examples use only the public Quantra API.
+
+### PennyLane
+
+```python
+import pennylane as qml
+import Quantra
+
+
+dev = qml.device(
+    "default.qubit",
+    wires=3,
+)
+
+
+@qml.qnode(dev)
+def circuit():
+    qml.Hadamard(0)
+    qml.RY(0.37, wires=1)
+    qml.CNOT(wires=[0, 1])
+    qml.RZ(-0.41, wires=2)
+    qml.CNOT(wires=[1, 2])
+
+    return qml.sample(
+        wires=[2, 0, 1]
+    )
+
+
+result = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+).run()
+
+
+print("Measured:")
+print(result.measured)
+
+print("Expected:")
+print(result.expected)
+
+print("Residual:")
+print(result.residual)
+
+print("Corrected:")
+print(result.corrected)
+
+print("Recovery:")
+print(result.recovery_percentage)
+```
+
+Quantra normalizes supported permuted PennyLane measurement-wire
+ordering back into its canonical computational-basis domain.
+
+---
+
+### Qiskit
+
+```python
+from qiskit import QuantumCircuit
+import Quantra
+
+
+circuit = QuantumCircuit(3, 3)
+
+circuit.h(0)
+circuit.ry(0.37, 1)
+circuit.cx(0, 1)
+circuit.rz(-0.41, 2)
+circuit.cx(1, 2)
+
+# Deliberately nontrivial q -> c mapping:
+#
+# q0 -> c2
+# q1 -> c1
+# q2 -> c0
+
+circuit.measure(0, 2)
+circuit.measure(1, 1)
+circuit.measure(2, 0)
+
+
+result = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+).run()
+
+
+print(result.expected)
+print(result.corrected)
+```
+
+Quantra reconstructs the supported terminal qubit-to-classical-bit
+mapping and converts Qiskit's displayed bit ordering into Quantra's
+canonical qubit basis.
+
+---
+
+### Cirq
+
+```python
+import cirq
+import Quantra
+
+
+q0, q1, q2 = cirq.LineQubit.range(3)
+
+circuit = cirq.Circuit(
+    cirq.H(q0),
+    cirq.ry(0.37)(q1),
+    cirq.CNOT(q0, q1),
+    cirq.rz(-0.41)(q2),
+    cirq.CNOT(q1, q2),
+
+    # Deliberately permuted measurement order.
+    cirq.measure(
+        q2,
+        q0,
+        q1,
+        key="result",
+    ),
+)
+
+
+result = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+).run()
+
+
+print(result.expected)
+print(result.corrected)
+```
+
+Quantra preserves the parsed Cirq measurement order and maps the
+resulting samples into the canonical computational-basis domain.
+
+---
+
+## QuantraResult
+
+`Quantra.run()` returns an immutable `QuantraResult` aggregate.
+
+Important public properties include:
+
+```python
+result.measured
+result.expected
+result.residual
+result.corrected
+
+result.pre_mae
+result.post_mae
+result.recovery_percentage
+result.recovery_defined
+
+result.correction_improved
+result.correction_unchanged
+result.correction_worsened
+
+result.shape
+result.size
+result.is_scalar
+
+result.audit_clean
+result.reference_mode
+result.framework
+```
+
+### `measured`
+
+The framework execution result after supported semantic normalization
+into the common computational-basis probability domain.
+
+### `expected`
+
+The deterministic contextual reference probability vector generated
+independently from the parsed circuit.
+
+### `residual`
+
+Defined as:
+
+```python
+residual = measured - expected
+```
+
+### `corrected`
+
+Defined as:
+
+```python
+corrected = measured - residual
+```
+
+### `pre_mae`
+
+Mean absolute error between `measured` and `expected`.
+
+### `post_mae`
+
+Mean absolute error between `corrected` and `expected`.
+
+### `recovery_percentage`
+
+Calculated recovery percentage when the pre-correction error is nonzero.
+
+### `audit_clean`
+
+Indicates whether the configured leakage auditor observed any forbidden
+direct error-injection fields in the correction-stage provenance
+metadata.
+
+A clean audit is a dataflow/provenance statement. It is not proof that
+no hidden information could exist outside the audited interface.
+
+### `reference_mode`
+
+Identifies the reference provenance mode. The current high-level
+automatic pipeline uses:
+
+```text
+simulation
+```
+
+---
+
+## Correction Model
+
+Quantra separates the correction pipeline into explicit stages.
+
+### 1. Measurement
+
+Obtain the framework-native execution result.
+
+### 2. Reference
+
+Propagate the supported circuit independently through the deterministic
+reference engine.
+
+### 3. Semantic normalization
+
+Convert supported measurement outputs into the same computational-basis
+probability representation used by the reference.
+
+### 4. Residual
+
+```python
+residual = measured - expected
+```
+
+### 5. Projection
+
+```python
+corrected = measured - residual
+```
+
+### 6. Metrics
+
+Calculate pre-correction error, post-correction error, and recovery
+percentage.
+
+This separation is intentional. The result object aggregates these
+stages but does not silently recompute or replace their values.
+
+---
+
+## Measurement Semantics
+
+Quantra currently supports automatic correction for supported forms of:
+
+- computational-basis probabilities,
+- samples,
+- counts,
+- framework measurement outputs that can be mapped unambiguously into
+  those domains.
+
+Quantra validates measurement semantics before correction.
+
+### Full terminal measurement
+
+The current automatic correction path requires a supported terminal
+full-qubit measurement.
+
+Partial measurements fail closed.
+
+### Mid-circuit measurement
+
+Automatic correction currently rejects mid-circuit measurement
+semantics.
+
+### Duplicate measured qubits
+
+Duplicate-qubit measurement mappings fail closed.
+
+### Multiple ambiguous outputs
+
+Multiple measurement outputs that cannot be represented safely as one
+supported correction domain fail closed.
+
+### Framework-specific mapping
+
+Quantra does not assume all frameworks use the same display convention.
+
+It contains framework-aware normalization for:
+
+- PennyLane measurement-wire order,
+- Qiskit qubit/classical-bit mapping and displayed bit ordering,
+- Cirq measurement qubit order and measurement keys.
+
+---
+
+## Reference Engine
+
+The deterministic reference engine propagates a pure state through the
+canonical Quantra circuit representation.
+
+The reference trajectory is independent of measurement execution noise
+and is used to construct the contextual expected result.
+
+### Current reference behavior
+
+- Default initial state: (\|0`\ldots`{=tex}0`\rangle`{=tex})
+- Pure-state deterministic propagation
+- Little-endian canonical qubit convention
+- Measurement events are observational checkpoints
+- Measurement collapse is not performed in the current reference mode
+- State snapshots are immutable
+- Final computational-basis probabilities are available to the facade
+
+An optional initial state can be supplied:
+
+```python
+result = quantra.run(
+    initial_state=my_initial_state
+)
+```
+
+The supplied state must satisfy the reference engine's dimensional and
+normalization requirements.
+
+### Supported gate families
+
+The current reference engine includes support for the gate families
+exercised by Quantra's present circuit contract, including:
+
+- Identity
+- Pauli X
+- Pauli Y
+- Pauli Z
+- Hadamard
+- S / S-dagger
+- T / T-dagger
+- SX / SX-dagger
+- RX
+- RY
+- RZ
+- Phase
+- CNOT / CX
+- CY
+- CZ
+- Controlled phase
+- CRX
+- CRY
+- CRZ
+- Toffoli / CCX
+- SWAP
+- Fredkin / CSWAP
+
+Barrier/delay-style operations may be represented as no-ops where
+supported by the parser/reference contract.
+
+Unsupported operations fail explicitly rather than being approximated
+silently.
+
+---
+
+## Runtime and Device Selection
+
+Quantra separates circuit adaptation from execution runtime selection.
+
+Typical CPU execution:
+
+```python
+result = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1000,
+).run()
+```
+
+Automatic runtime selection:
+
+```python
+result = Quantra.Quantra(
+    circuit,
+    device="auto",
+    shots=1000,
+).run()
+```
+
+The runtime layer distinguishes:
+
+- CPU
+- GPU
+- QPU
+
+### CPU
+
+CPU execution is the safe local fallback.
+
+### GPU
+
+GPU execution is selected only when the relevant runtime path is
+available and usable. An explicit GPU request should fail rather than
+silently pretending GPU execution occurred when no usable GPU path
+exists.
+
+---
+
+### QPU
+
+Quantra is designed to extend its deterministic contextual
+reference-projection workflow to real QPU execution through an
+appropriately configured backend and framework integration.
+
+Under Quantra's deterministic residual-projection contract, when the
+contextual expected reference is correctly established and the QPU
+measurement semantics are correctly mapped into the same canonical
+domain, the correction step projects the measured result exactly onto
+that reference, up to numerical precision.
+
+In other words, the correction itself is deterministic. The principal
+challenge in a real-QPU workflow is not the residual-projection
+operation, but establishing a correct end-to-end integration between
+the physical backend, circuit semantics, measurement mapping, and the
+reference used by Quantra.
+
+A QPU deployment therefore requires particular care with:
+
+- backend and provider configuration,
+- authentication and provider credentials,
+- physical/logical qubit mapping,
+- transpilation and backend-specific circuit transformations,
+- measurement and classical-bit ordering,
+- shot/result decoding,
+- and selection or construction of the appropriate reference strategy.
+
+When these components are correctly aligned, Quantra applies the same
+reference-projection contract used by its framework-independent
+correction pipeline to QPU-derived measurements.
+
+The important distinction is that exact recovery of the supplied
+contextual reference is a property of Quantra's deterministic
+projection model. It should not, by itself, be interpreted as proof
+that every unknown physical error mechanism of an arbitrary quantum
+processor has been identified or that the hardware has become
+fault-tolerant.
+
+Real-QPU integration can therefore be more demanding than simulation:
+the mathematical correction contract remains deterministic, while the
+quality and physical interpretation of the result depend on the
+correctness of the backend integration and, critically, on the
+reference supplied to the correction process.
+
+## Audit and Provenance
+
+Quantra records provenance for the major stages of the high-level
+pipeline:
+
+- circuit parsing,
+- reference generation,
+- measurement execution,
+- residual calculation,
+- residual projection,
+- metric calculation.
+
+The provenance trace records dataflow facts such as stage, action,
+source, and selected metadata.
+
+### Leakage audit
+
+The leakage auditor checks correction-stage metadata for configured
+direct error-injection fields such as injection maps, injected angles,
+injection seeds, explicit ground-truth errors, and similar oracle-style
+fields.
+
+The contextual expected reference itself is **not** classified as direct
+injection leakage. Quantra is explicitly reference-assisted.
+
+Therefore:
+
+```python
+result.audit_clean
+```
+
+means that no configured forbidden direct injection field was observed
+in the audited correction metadata.
+
+It does not prove:
+
+- absence of all possible hidden information,
+- causal independence outside the recorded interface,
+- blind inference of unknown physical noise.
+
+---
+
+## Visualization
+
+Install plotting support:
+
+```bash
+pip install "quantra[plot]"
+```
+
+Quantra includes result visualization support for compatible real scalar
+or one-dimensional results.
+
+The visualization layer is intentionally separate from correction and
+does not recalculate the correction metrics.
+
+---
+
+## Cross-Framework Behavior
+
+Quantra's canonical representation is designed so that mathematically
+equivalent supported circuits can produce the same deterministic
+reference domain across frameworks.
+
+A pre-release real-use cross-framework validation was performed using
+the public facade with the same logical three-qubit circuit implemented
+independently in:
+
+- PennyLane,
+- Qiskit,
+- Cirq.
+
+The circuit included:
+
+- Hadamard,
+- RY rotation,
+- CNOT,
+- RZ rotation,
+- a second CNOT,
+- intentionally different framework measurement mappings.
+
+The public API was used as:
+
+```python
+import Quantra
+
+result = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+).run()
+```
+
+The validation confirmed deterministic reference parity and
+corrected-result parity across the three framework implementations.
+
+With `shots=1`, the measured sample itself is stochastic and therefore
+is **not expected to be identical across independent framework
+executions**. Cross-framework deterministic parity should be assessed on
+deterministic quantities such as the independently generated reference,
+while sampled quantities must be interpreted according to shot
+statistics.
+
+---
+
+## Validated Scenarios
+
+The development regression suite has exercised scenarios including:
+
+- PennyLane parsing and execution
+- Qiskit parsing and execution
+- Cirq parsing and execution
+- single-shot execution
+- multi-shot execution
+- deterministic reference trajectories
+- injected-error integration scenarios
+- contextual trajectory scenarios
+- Qiskit reversed classical mappings
+- PennyLane permuted measurement-wire order
+- Cirq permuted measurement order
+- partial-measurement rejection
+- mid-circuit-measurement rejection
+- ambiguous/multiple-output rejection
+- residual identity checks
+- deterministic projection identity checks
+- recovery metric calculation
+- provenance generation
+- correction-dataflow leakage audit
+- full regression testing
+- public-facade cross-framework use
+
+These validations establish software behavior for the tested contracts.
+They are not a substitute for hardware-specific physical validation.
+
+---
+
+## Current Limitations
+
+Quantra `0.1.0` is an alpha release.
+
+Important current limitations include:
+
+### Correction domain
+
+The automatic high-level correction domain is currently
+computational-basis probabilities.
+
+### Reference model
+
+The current automatic high-level reference is simulation-based
+deterministic pure-state propagation.
+
+### Measurement collapse
+
+The reference trajectory does not currently implement measurement
+collapse.
+
+### Mid-circuit measurement
+
+Mid-circuit measurement is currently rejected by the automatic
+correction path.
+
+### Partial measurement
+
+Partial terminal measurement is currently rejected by the automatic
+correction path.
+
+### Arbitrary observables
+
+Arbitrary expectation-value or observable outputs are not automatically
+treated as computational-basis probabilities.
+
+### Arbitrary channels
+
+Unsupported channels/noise operations are not silently approximated by
+the reference engine.
+
+### Symbolic parameters
+
+Unbound/symbolic parameters must satisfy the current parser/reference
+binding contract. Unsupported unresolved parameters fail explicitly.
+
+### Hardware claims
+
+The current software validation must not be interpreted as proof of
+universal QPU-level error correction, fault tolerance, or arbitrary
+unknown-noise reconstruction.
+
+### Reference assistance
+
+The deterministic correction method is reference-assisted. It is not
+presented as blind reconstruction of an unknown ideal state from a
+single noisy observation.
+
+---
+
+## Error Handling
+
+Quantra intentionally fails closed when it cannot establish a safe
+semantic mapping.
+
+High-level exceptions include:
+
+```python
+Quantra.QuantraError
+Quantra.UnsupportedMeasurementSemanticsError
+Quantra.MeasurementReferenceMismatchError
+```
+
+### `UnsupportedMeasurementSemanticsError`
+
+Raised when a framework-native result or circuit measurement contract
+cannot safely be interpreted in the currently supported correction
+domain.
+
+Examples include unsupported mid-circuit measurements, partial
+measurements, or ambiguous output semantics.
+
+### `MeasurementReferenceMismatchError`
+
+Raised when the measured representation and reference representation
+cannot be reconciled safely, for example because their dimensions or
+validated measurement widths differ.
+
+---
+
+## Package Architecture
+
+The current source tree is organized into focused components:
+
+```text
+Quantra/
+├── Quantra/
+│   └── __init__.py
+│
+├── quantra.py
+│
+├── adapter/
+│   ├── detector.py
+│   ├── introspection.py
+│   ├── capabilities.py
+│   └── universal.py
+│
+├── circuit/
+│   ├── ir.py
+│   ├── parser.py
+│   └── graph.py
+│
+├── reference/
+│   ├── engine.py
+│   └── trajectory.py
+│
+├── measurement/
+│   ├── executor.py
+│   ├── runtime.py
+│   └── single_shot.py
+│
+├── correction/
+│   ├── residual.py
+│   ├── projector.py
+│   └── metrics.py
+│
+├── audit/
+│   ├── record.py
+│   ├── provenance.py
+│   └── leakage.py
+│
+├── result/
+│   ├── result.py
+│   └── visualization.py
+│
+├── tests/
+├── setup.py
+├── README.md
+└── LICENSE
+```
+
+The distribution name and import name intentionally differ:
+
+```text
+Distribution name: quantra
+Import package:    Quantra
+```
+
+Thus:
+
+```bash
+pip install quantra
+```
+
+corresponds to:
+
+```python
+import Quantra
+```
+
+---
+
+## Developer Installation
+
+For local development, clone or obtain the source tree and create a
+virtual environment.
+
+Example:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Upgrade packaging tools:
+
+```bash
+python -m pip install --upgrade pip setuptools wheel
+```
+
+Install the project with all supported integrations:
+
+```bash
+pip install -e ".[all]"
+```
+
+Then verify the public import:
+
+```bash
+python -c "import Quantra; print(Quantra.__version__)"
+```
+
+Expected release version:
+
+```text
+0.1.0
+```
+
+---
+
+## Testing
+
+The test suite is designed to be executed from the project root.
+
+```bash
+python -m pytest -v
+```
+
+For measurement-semantic regression specifically:
+
+```bash
+python -m pytest tests/test_measurement_semantics.py -v
+```
+
+The project also uses public-API consumer-style validation to ensure the
+high-level facade can be exercised without importing internal Quantra
+components.
+
+### Recommended pre-release validation
+
+Before publishing a release:
+
+1. Run the complete regression suite.
+2. Build the source distribution and wheel.
+3. Create a fresh virtual environment outside the repository.
+4. Install the generated wheel.
+5. Verify `import Quantra`.
+6. Install/use the desired framework extra.
+7. Execute independent PennyLane, Qiskit, and Cirq consumer examples.
+8. Confirm deterministic cross-framework reference parity for
+   mathematically equivalent supported circuits.
+
+Do not treat a repository-root `PYTHONPATH` test as a substitute for the
+final installed-wheel consumer test.
+
+---
+
+## Design Principles
+
+Quantra follows several design principles.
+
+### Framework independence
+
+Framework-native circuits are converted into a common internal
+representation before deterministic reference propagation.
+
+### Explicit semantics
+
+Numeric output alone is not enough to establish measurement meaning.
+
+### Fail closed
+
+Ambiguous measurement contracts are rejected rather than guessed.
+
+### Deterministic reference separation
+
+Reference propagation is separated from framework execution.
+
+### Canonical basis mapping
+
+Framework-specific bit/wire conventions are normalized into a common
+canonical basis.
+
+### Immutable analytical results
+
+Reference snapshots, residual results, projection results, metrics,
+provenance, audits, and final results are designed around immutable
+result objects.
+
+### Calculated metrics
+
+Recovery percentages are calculated from errors rather than hardcoded.
+
+### Provenance-aware correction
+
+Correction stages record their declared data sources and actions.
+
+### Scientific restraint
+
+Algebraic recovery of a supplied contextual reference is distinguished
+from physical claims about arbitrary hardware noise.
+
+---
+
+## Roadmap
+
+Potential future development areas include:
+
+- additional circuit operations,
+- richer symbolic-parameter support,
+- broader control-flow semantics,
+- additional measurement domains,
+- additional observable semantics,
+- additional reference modes,
+- clean-execution reference workflows,
+- user-supplied reference workflows,
+- estimated-reference workflows,
+- broader GPU execution validation,
+- provider-specific QPU integrations,
+- hardware experiments,
+- hardware-specific benchmarks,
+- imperfect-reference benchmarks,
+- noise-model benchmarks,
+- larger cross-framework parity suites,
+- expanded visualization,
+- API stabilization,
+- packaging and documentation improvements.
+
+Roadmap items are development directions, not guarantees of current
+functionality.
+
+---
+
+## Citation
+
+A formal Quantra research-paper citation is not included in version
+`0.1.0` unless and until the associated publication metadata is
+available.
+
+For software attribution in the meantime, use the project name, version,
+author, and release location, for example:
+
+```text
+Quantra, version 0.1.0.
+Author: Onur Kavrik.
+Maintainer: Biotronics AI.
+```
+
+Once a paper, DOI, or archival software identifier is available, this
+section can be updated with the canonical citation.
+
+---
+
+## License
+
+Quantra is distributed under the **MIT License**.
+
+See the repository's `LICENSE` file for the complete license text.
+
+---
+
+## Disclaimer
+
+Quantra is research and developer software.
+
+The deterministic residual-projection mechanism is reference-assisted.
+Exact recovery of the supplied contextual expected reference under the
+deterministic residual definition is an algebraic property of that
+definition and must not be interpreted as a universal physical quantum
+error-correction guarantee.
+
+Results obtained in simulation do not by themselves establish equivalent
+performance on real quantum hardware.
+
+Users are responsible for validating Quantra, the underlying quantum
+framework, backend configuration, reference strategy, circuit semantics,
+numerical assumptions, and hardware behavior for their own application.
+
+---
+
+## Minimal Example
+
+```python
+import Quantra
+import pennylane as qml
+
+
+dev = qml.device(
+    "default.qubit",
+    wires=2,
+)
+
+
+@qml.qnode(dev)
+def circuit():
+    qml.Hadamard(0)
+    qml.CNOT(wires=[0, 1])
+
+    return qml.sample(
+        wires=[0, 1]
+    )
+
+
+quantra = Quantra.Quantra(
+    circuit,
+    device="cpu",
+    shots=1,
+)
+
+
+result = quantra.run()
+
+
+print("Measured:")
+print(result.measured)
+
+print("Expected:")
+print(result.expected)
+
+print("Residual:")
+print(result.residual)
+
+print("Corrected:")
+print(result.corrected)
+
+print("Pre-MAE:", result.pre_mae)
+print("Post-MAE:", result.post_mae)
+print(
+    "Recovery:",
+    result.recovery_percentage,
+)
+
+print(
+    "Audit clean:",
+    result.audit_clean,
+)
+```
+
+---
+
+**Quantra 0.1.0 --- contextual reference, framework-independent
+execution semantics, and deterministic residual projection.**