Metadata-Version: 2.4
Name: QuantaSight
Version: 0.1.2
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.2` (Alpha)

# QuantaSight

> **Author:** Onur Kavrik
> **Maintainer:** Biotronics AI
> **License:** MIT

**Context-aware, framework-independent quantum error correction through
deterministic reference tracking and residual projection.**

quantasight 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, quantasight 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 quantasight 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**. quantasight 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}\), quantasight 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 quantasight'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**. quantasight 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. quantasight'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. quantasight 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**.

quantasight 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 quantasight.

---

## Contents

- [Overview](#overview)
- [What quantasight Does](#what-quantasight-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)
- [quantasightResult](#quantasightresult)
- [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

quantasight is designed to provide a consistent analysis contract across
multiple quantum software frameworks.

A typical quantasight 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
              QuantaSightResult
```

The current automatic correction domain is the **computational-basis
probability domain**.

quantasight is intentionally conservative about ambiguous measurement
semantics. When a framework result cannot be mapped safely into the
supported correction domain, quantasight fails closed rather than guessing.

---

## What quantasight Does

quantasight currently provides:

- A single high-level public facade: `QuantaSight.QuantaSight`
- 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

quantasight does **not** reinterpret arbitrary numeric framework outputs as
probabilities. Measurement semantics must be supported and unambiguous.

---

## Scientific Interpretation

quantasight'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

Quantasight `0.1.2` 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 quantasight
```

The Python import package is capitalized:

```python
import quantasight
```

### Core installation

Install the minimal quantasight core:

```bash
pip install quantasight
```

### PennyLane support

```bash
pip install "quantasight[pennylane]"
```

### Qiskit support

```bash
pip install "quantasight[qiskit]"
```

### Cirq support

```bash
pip install "quantasight[cirq]"
```

### Plotting support

```bash
pip install "quantasight[plot]"
```

### Install all supported integrations

```bash
pip install "quantasight[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 quantasight

quantasight = quantasight.quantasight(
    circuit,
    device="cpu", #"cpu", "gpu" or "qpu"
    shots=1,
)

result = quantasight.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 quantasight import quantasight

quantasight = QuantaSight(
    circuit,
    device="cpu",
    shots=1,
)

result = quantasight.run()
```

---

## Framework Examples

The following examples use only the public quantasight API.

### PennyLane

```python
import pennylane as qml
import quantasight


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 = quantasight.quantasight(
    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)
```

quantasight normalizes supported permuted PennyLane measurement-wire
ordering back into its canonical computational-basis domain.

---

### Qiskit

```python
from qiskit import QuantumCircuit
import quantasight


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 = quantasight.quantasight(
    circuit,
    device="cpu",
    shots=1,
).run()


print(result.expected)
print(result.corrected)
```

quantasight reconstructs the supported terminal qubit-to-classical-bit
mapping and converts Qiskit's displayed bit ordering into quantasight's
canonical qubit basis.

---

### Cirq

```python
import cirq
import quantasight


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 = quantasight.quantasight(
    circuit,
    device="cpu",
    shots=1,
).run()


print(result.expected)
print(result.corrected)
```

quantasight preserves the parsed Cirq measurement order and maps the
resulting samples into the canonical computational-basis domain.

---

## quantasightResult

`quantasight.run()` returns an immutable `quantasightResult` 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

quantasight 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

quantasight currently supports automatic correction for supported forms of:

- computational-basis probabilities,
- samples,
- counts,
- framework measurement outputs that can be mapped unambiguously into
  those domains.

quantasight 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

quantasight 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 quantasight 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 = quantasight.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 quantasight'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

quantasight separates circuit adaptation from execution runtime selection.

Typical CPU execution:

```python
result = quantasight.quantasight(
    circuit,
    device="cpu",
    shots=1000,
).run()
```

Automatic runtime selection:

```python
result = quantasight.quantasight(
    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

quantasight is designed to extend its deterministic contextual
reference-projection workflow to real QPU execution through an
appropriately configured backend and framework integration.

Under quantasight'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 quantasight.

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, quantasight 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 quantasight'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

quantasight 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. quantasight 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 "quantasight[plot]"
```

quantasight 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

quantasight'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 quantasight

result = quantasight.quantasight(
    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

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

quantasight intentionally fails closed when it cannot establish a safe
semantic mapping.

High-level exceptions include:

```python
quantasight.quantasightError
quantasight.UnsupportedMeasurementSemanticsError
quantasight.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
quantasight/
├── quantasight/
│   └── __init__.py
│
├── quantasight.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: quantasight
Import package:    quantasight
```

Thus:

```bash
pip install quantasight
```

corresponds to:

```python
import quantasight
```

---

## 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 quantasight; print(quantasight.__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 quantasight
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 quantasight`.
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

quantasight 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 quantasight 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
quantasight, 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

quantasight is distributed under the **MIT License**.

See the repository's `LICENSE` file for the complete license text.

---

## Disclaimer

quantasight 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 quantasight, the underlying quantum
framework, backend configuration, reference strategy, circuit semantics,
numerical assumptions, and hardware behavior for their own application.

---

## Minimal Example

```python
import quantasight
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]
    )


quantasight = quantasight.quantasight(
    circuit,
    device="cpu",
    shots=1,
)


result = quantasight.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,
)
```

---

**quantasight 0.1.0 --- contextual reference, framework-independent
execution semantics, and deterministic residual projection.**
