qledger 0.1.0__tar.gz

qledger-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type check (mypy --strict)
+        run: mypy qledger
+
+      - name: Run tests
+        run: pytest

qledger-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.so
+*.db
+*.sqlite
+*.sqlite3
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.cover
+*.log
+.idea/
+.vscode/
+.claude/settings.local.json
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Private brief — kept locally for sharing, not published to the repo
+OVERVIEW.md

qledger-0.1.0/CITATION.cff

@@ -0,0 +1,46 @@
+# This CITATION.cff lets people cite QLedger correctly.
+# GitHub reads this file and shows a "Cite this repository" button on the repo page,
+# which exports BibTeX/APA automatically. See https://citation-file-format.github.io
+cff-version: 1.2.0
+message: "If you use QLedger in your research or software, please cite it using the metadata below."
+title: "QLedger: The Universal Quantum Experiment Lifecycle Platform"
+abstract: >-
+  QLedger is an open-source Python platform that executes quantum circuits across
+  Qiskit, Cirq, and PennyLane through a universal intermediate representation,
+  versions circuits with Git-like history and diffs, runs standardised benchmarks
+  (Quantum Volume, CLOPS, algorithmic fidelity), profiles hardware noise over time,
+  and persists every experiment in a single portable SQLite file for exact
+  reproducibility.
+type: software
+authors:
+  - given-names: Namash
+    family-names: Aggarwal
+    # orcid: "https://orcid.org/0000-0000-0000-0000"   # add your ORCID iD if you have one
+version: 0.1.0
+date-released: 2026-06-06          # update to your actual release date
+license: MIT
+repository-code: "https://github.com/namashworks/qledger"
+url: "https://github.com/namashworks/qledger"
+keywords:
+  - quantum computing
+  - quantum circuits
+  - reproducibility
+  - experiment tracking
+  - benchmarking
+  - noise characterization
+  - version control
+  - qiskit
+  - cirq
+  - pennylane
+
+# ----------------------------------------------------------------------------
+# OPTIONAL — strongest form of citable credit:
+# Archive a release on Zenodo (https://zenodo.org) to mint a permanent DOI,
+# then uncomment and fill in the lines below. A DOI is what gets you cited in
+# academic papers and gives your work a durable, referenceable identity.
+# ----------------------------------------------------------------------------
+# doi: "10.5281/zenodo.XXXXXXX"
+# identifiers:
+#   - type: doi
+#     value: "10.5281/zenodo.XXXXXXX"
+#     description: "Archived snapshot of QLedger v0.1.0"

qledger-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Contributions are welcome. Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/namashworks/qledger.git
+cd qledger
+pip install -e ".[dev]"
+```
+
+## Development workflow
+
+1. Create a feature branch from `main`.
+2. Write your code and add tests.
+3. Run the full check suite:
+
+```bash
+pytest
+ruff check .
+mypy qledger
+```
+
+4. Open a pull request against `main`.
+
+## Adding a new framework adapter
+
+1. Create `qledger/adapters/<framework>_adapter.py`.
+2. Implement the `BaseAdapter` interface (see `base.py`).
+3. Add the `@AdapterRegistry.register` decorator.
+4. Add the module path to `_ADAPTER_MODULES` in `registry.py`.
+5. Add the framework as an optional dependency in `pyproject.toml`.
+6. Add tests in `tests/integration/`.
+
+## Code style
+
+- [PEP 8](https://peps.python.org/pep-0008/) enforced by Ruff
+- Type annotations on all public functions
+- [NumPy-style](https://numpydoc.readthedocs.io/en/latest/format.html) docstrings
+
+## Tests
+
+All tests use in-memory SQLite (`:memory:`), so they're fast and require no external services. Integration tests that need a quantum framework are in `tests/integration/`.

qledger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Namash Aggarwal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qledger-0.1.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: qledger
+Version: 0.1.0
+Summary: The universal quantum experiment lifecycle platform. Execute circuits across frameworks, track noise, benchmark hardware, and persist everything.
+Project-URL: Homepage, https://github.com/namashworks/qledger
+Project-URL: Repository, https://github.com/namashworks/qledger
+Project-URL: Issues, https://github.com/namashworks/qledger/issues
+Project-URL: Documentation, https://github.com/namashworks/qledger/tree/main/docs
+Author: Namash Aggarwal
+License: MIT
+License-File: LICENSE
+Keywords: benchmarking,cirq,experiment-tracking,noise,pennylane,qiskit,quantum,quantum-computing,reproducibility,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: cirq-core>=1.3; extra == 'all'
+Requires-Dist: pennylane>=0.35; extra == 'all'
+Requires-Dist: qiskit-aer>=0.13; extra == 'all'
+Requires-Dist: qiskit>=1.0; extra == 'all'
+Provides-Extra: cirq
+Requires-Dist: cirq-core>=1.3; extra == 'cirq'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: qiskit-aer>=0.13; extra == 'dev'
+Requires-Dist: qiskit>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.35; extra == 'pennylane'
+Provides-Extra: qiskit
+Requires-Dist: qiskit-aer>=0.13; extra == 'qiskit'
+Requires-Dist: qiskit>=1.0; extra == 'qiskit'
+Description-Content-Type: text/markdown
+
+# QLedger
+
+**The Universal Quantum Experiment Lifecycle Platform.**
+
+Execute circuits across Qiskit, Cirq, and PennyLane. Track noise. Benchmark hardware. Version circuits. Persist everything in a portable SQLite file.
+
+[![CI](https://github.com/namashworks/qledger/actions/workflows/ci.yml/badge.svg)](https://github.com/namashworks/qledger/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+---
+
+## Why QLedger?
+
+The quantum computing ecosystem is **fragmented**. Every framework has its own circuit format, every backend returns results differently, and there's no standard way to track experiments, compare hardware, or reproduce results.
+
+QLedger fixes this with a single platform that:
+
+- **Runs circuits on any framework** — Qiskit, Cirq, PennyLane — through a universal adapter layer
+- **Persists everything** — circuits, results, metadata, seeds, timing, noise profiles — in one portable `.db` file
+- **Versions circuits** — git-like tracking of how your circuits evolve over time
+- **Benchmarks hardware** — Quantum Volume, CLOPS, and algorithmic fidelity benchmarks with standardised scoring
+- **Tracks noise** — capture T1/T2, gate fidelities, and readout errors over time to monitor hardware drift
+- **Enables reproducibility** — every seed, every setting, every result is stored for exact replay
+
+## Installation
+
+> **Note:** PyPI release pending — until then, install from source (see below). The `pip install qledger` commands will work once the first release is published.
+
+```bash
+# Core only (no framework dependencies)
+pip install qledger
+
+# With specific frameworks
+pip install qledger[qiskit]
+pip install qledger[cirq]
+pip install qledger[pennylane]
+pip install qledger[all]
+```
+
+From source:
+
+```bash
+git clone https://github.com/namashworks/qledger.git
+cd qledger
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from qiskit import QuantumCircuit
+from qledger import QLedger
+
+with QLedger("my_research.db") as db:
+    # Create an experiment
+    exp_id = db.create_experiment("Bell States", tags=["entanglement"])
+
+    # Build and run a circuit — everything is saved automatically
+    qc = QuantumCircuit(2, 2)
+    qc.h(0)
+    qc.cx(0, 1)
+    qc.measure([0, 1], [0, 1])
+
+    result = db.run(qc, experiment_id=exp_id, shots=4096, seed_simulator=42)
+
+    print(result.counts)          # {'00': 2009, '11': 2087}
+    print(result.probabilities)   # {'00': 0.490, '11': 0.510}
+    print(result.most_frequent()) # '11'
+    print(result.entropy())       # ~1.000 (near-maximum for 2 equally likely outcomes)
+```
+
+## Core Features
+
+### 1. Universal Circuit IR
+
+Convert between frameworks seamlessly:
+
+```python
+# Qiskit -> Universal -> Cirq
+cirq_circuit = db.convert(qiskit_circuit, from_framework="qiskit", to_framework="cirq")
+```
+
+The `UniversalCircuit` is a framework-agnostic intermediate representation with content hashing, validation, and full serialisation support.
+
+### 2. Cross-Framework Execution
+
+```python
+# Run the same circuit on different backends
+result_qiskit = db.run(qc, framework="qiskit", shots=4096)
+result_cirq = db.run(cirq_circuit, framework="cirq", shots=4096)
+```
+
+### 3. Circuit Versioning
+
+Track circuit evolution like git tracks code:
+
+```python
+# Auto-versioned on every run, or manually:
+db.version_circuit(circuit_id, modified_circuit, message="optimised CX count")
+
+# View history
+log = db.circuit_log(circuit_id)
+
+# Diff between versions
+diff = db.diff_circuit(circuit_id, version_a=1, version_b=3)
+print(diff.summary_text())  # "+2 gates, -1 gates, depth: 5 -> 4"
+
+# Restore any version
+old_circuit = db.checkout_circuit(circuit_id, version=1)
+```
+
+### 4. Standardised Benchmarks
+
+```python
+suite = db.benchmark(framework="qiskit")
+
+# Quantum Volume
+qv = suite.run_quantum_volume(backend=my_backend, max_depth=8)
+print(f"Quantum Volume: {qv.details['quantum_volume']}")
+
+# CLOPS (throughput)
+clops = suite.run_clops(num_circuits=100, shots=1024)
+print(f"CLOPS: {clops.score:.0f}")
+
+# Algorithmic fidelity (GHZ, QFT)
+ghz = suite.run_algorithmic(algorithm="ghz", qubit_range=(2, 10))
+print(f"Average fidelity: {ghz.score:.4f}")
+
+# Compare backends
+comparison = suite.compare_backends("quantum_volume", ["backend_a", "backend_b"])
+```
+
+### 5. Noise Profiling
+
+```python
+# Capture noise from a real backend
+snapshot = db.capture_noise(backend, framework="qiskit")
+
+print(f"Median T1: {snapshot.median_t1_us:.1f} us")
+print(f"Avg CX error: {snapshot.average_cx_error:.4f}")
+print(f"Avg readout error: {snapshot.average_readout_error:.4f}")
+
+# Track drift over time
+history = db.get_noise_history("ibm_kyoto")
+
+# Find the best qubits
+best = db.best_qubits("ibm_kyoto", count=5, metric="t1")
+```
+
+### 6. Batch Execution
+
+```python
+results = db.run_batch(
+    [circuit_1, circuit_2, circuit_3],
+    experiment_name="Parameter Sweep",
+    names=["theta=0.1", "theta=0.5", "theta=1.0"],
+    shots=8192,
+)
+```
+
+### 7. Export
+
+```python
+# Export full experiment as JSON
+data = db.export_experiment(exp_id)
+
+# Includes: experiment metadata, all circuits (as UniversalCircuit JSON),
+# all executions (with counts, timing, seeds), version history
+```
+
+## CLI
+
+```bash
+# List experiments
+qledger experiments
+
+# Show experiment details
+qledger show 1
+
+# List circuits with structural info
+qledger circuits 1
+
+# List executions with results
+qledger executions --backend aer_simulator
+
+# View circuit version history
+qledger versions 1
+
+# View benchmark results
+qledger benchmarks --type quantum_volume
+
+# View noise snapshots
+qledger noise --backend ibm_kyoto
+
+# Export experiment to JSON
+qledger export 1 -o experiment.json
+
+# List available framework adapters
+qledger adapters
+```
+
+## Database Schema
+
+Everything lives in a single SQLite file:
+
+| Table | Purpose |
+|---|---|
+| `experiments` | Named containers with tags and descriptions |
+| `circuits` | UniversalCircuit JSON, content hash, gate counts, depth |
+| `executions` | Counts, probabilities, entropy, backend config, seeds, timing |
+| `circuit_versions` | Version history with diffs and parent hashes |
+| `noise_snapshots` | T1/T2, gate fidelities, readout errors per qubit |
+| `benchmark_results` | QV, CLOPS, algorithmic scores with full parameters |
+
+Foreign keys with `ON DELETE CASCADE`. WAL mode for concurrent reads.
+
+## Architecture
+
+```
+qledger/
+    schema/         # Universal data models (circuit IR, results, noise)
+        gates.py    # 30+ canonical gates with cross-framework aliases
+        circuit.py  # UniversalCircuit with hashing, validation, depth calc
+        result.py   # ExecutionResult with entropy, fidelity computation
+        noise.py    # NoiseSnapshot, QubitProperties, GateFidelity
+    adapters/       # Framework adapters (Qiskit, Cirq, PennyLane)
+        base.py     # Abstract adapter interface
+        registry.py # Lazy auto-discovery registry
+    storage/        # SQLite persistence layer
+    versioning/     # Git-like circuit version tracking with diffs
+    noise/          # Noise profiling and drift analysis
+    benchmarks/     # Quantum Volume, CLOPS, algorithmic benchmarks
+    core/           # Main QLedger engine
+    cli/            # Command-line interface
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest           # 95 tests
+ruff check .     # Lint
+mypy qledger   # Type check
+```
+
+## License
+
+[MIT](LICENSE)