Metadata-Version: 2.4
Name: westquant-memory-lab
Version: 0.7.0
Summary: Evidence-aware quantum-memory modelling and network integration framework
Author-email: David Vesterlund <david@vesterlundventures.se>
Maintainer-email: David Vesterlund <david@vesterlundventures.se>
License: MIT
Project-URL: Homepage, https://github.com/VesterlundCoder/memory-discover-lab
Project-URL: Documentation, https://github.com/VesterlundCoder/memory-discover-lab/blob/release/v0.7.0/docs/MODEL_CONTRACT.md
Project-URL: Repository, https://github.com/VesterlundCoder/memory-discover-lab
Project-URL: Bug Tracker, https://github.com/VesterlundCoder/memory-discover-lab/issues
Project-URL: Release v0.7.0, https://github.com/VesterlundCoder/memory-discover-lab/tree/release/v0.7.0
Keywords: quantum memory,quantum networks,quantum simulation,reproducible research,provenance,spin coherence,quantum channels,SeQUeNCe,QuNetSim,rare-earth,NV center
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2
Requires-Dist: scipy!=1.16.0,!=1.17.0,<2,>=1.12
Provides-Extra: quantum
Requires-Dist: qutip==5.3.1; extra == "quantum"
Provides-Extra: chemistry
Requires-Dist: pyscf==2.14.0; extra == "chemistry"
Requires-Dist: ase==3.29.0; extra == "chemistry"
Provides-Extra: spin
Requires-Dist: pycce==1.1.1; extra == "spin"
Requires-Dist: pandas<3,>=2.2; extra == "spin"
Provides-Extra: propagation
Requires-Dist: maxwellbloch==0.12.0; extra == "propagation"
Provides-Extra: datasets
Requires-Dist: openpyxl<4,>=3.1; extra == "datasets"
Requires-Dist: pynmrstar<4,>=3.3; extra == "datasets"
Provides-Extra: network
Requires-Dist: sequence==1.2.0; extra == "network"
Requires-Dist: pandas<3,>=2.3.3; extra == "network"
Provides-Extra: all
Requires-Dist: qutip==5.3.1; extra == "all"
Requires-Dist: pyscf==2.14.0; extra == "all"
Requires-Dist: ase==3.29.0; extra == "all"
Requires-Dist: pycce==1.1.1; extra == "all"
Requires-Dist: pandas<3,>=2.2; extra == "all"
Requires-Dist: maxwellbloch==0.12.0; extra == "all"
Requires-Dist: openpyxl<4,>=3.1; extra == "all"
Requires-Dist: pynmrstar<4,>=3.3; extra == "all"
Requires-Dist: sequence==1.2.0; extra == "all"
Requires-Dist: pandas<3,>=2.3.3; extra == "all"
Dynamic: license-file

# WestQuant Memory Discovery Lab

**Evidence-aware quantum-memory modelling and network integration.**

[![PyPI version](https://badge.fury.io/py/westquant-memory-lab.svg)](https://badge.fury.io/py/westquant-memory-lab)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

WestQuant connects versioned experimental source data to typed observations, condition-matched coherence references, explicit quantum channels (Kraus operators with erasure), and native network-simulator adapters (SeQUeNCe and QuNetSim). Its contribution is an executable evidence contract across these interfaces, with retained failure outcomes and reproducible study identities.

> **Software verification is not hardware validation.** The framework preserves distinctions between experimental observations, curated observations, evaluated references, computed results, hypothetical controls, and unknown evidence. It does not claim universal simulator validation, new material discovery, or improved hardware performance.

## Installation

```bash
pip install westquant-memory-lab
```

For the full quantum-memory workflow with all backends:

```bash
pip install "westquant-memory-lab[all]"
```

Optional extras (install only what you need):

| Extra | Packages | Use case |
|---|---|---|
| `quantum` | QuTiP 5.3.1 | Open-system evolution, channel verification |
| `chemistry` | PySCF 2.14.0, ASE 3.29.0 | Electronic structure calculations |
| `spin` | PyCCE 1.1.1, pandas | Spin-bath dynamics, cluster expansion |
| `propagation` | MaxwellBloch 0.12.0 | Optical propagation |
| `datasets` | openpyxl, pynmrstar | Dataset importers |
| `network` | SeQUeNCe 1.2.0, pandas | Native network simulation |
| `all` | All of the above | Complete workflow |

**Requirements:** Python 3.10+. The full workflow with SeQUeNCe requires Python 3.12+.

## Quick start

```bash
# Check your environment
wqml doctor

# Run the bundled Teller et al. baseline (open data)
wqml reproduce examples/teller2025_baseline.json --out baselines/teller2025

# Or run a full pipeline
wqml pipeline examples/pipeline_full.json --out runs/my_lab
```

## Key features

### Evidence-aware data contracts

Every observation retains its evidence kind: `experimental`, `curated_experimental`, `fit_to_experiment`, `evaluated_reference`, `computed`, `hypothetical`, or `unknown`. The framework never promotes a computed result to an experimental measurement, and never converts a bare formula or isotope mass into a coherence time.

### Condition-matched reference queries

Coherence references require material identity, coherence definition, and condition matching (temperature, protocol, isotope, host). No interpolation or extrapolation across missing conditions.

### Explicit quantum channels

The write-store-read channel is constructed as a CPTP map with erasure:

```
E_t(rho) = eta(t) * Phi_t(rho) + (1 - eta(t)) * Tr(rho) |e><e|
```

Kraus operators, Choi matrices, and numerical validity (complete positivity, trace preservation) are checked at each step.

### Native network-simulator adapters

- **SeQUeNCe**: Event-driven simulation with native density-matrix manager
- **QuNetSim**: Layered quantum-network framework with QuTiP density backend

The adapters apply sampled absolute-age channels once to the original input and reject missing age samples — no interpolation or extrapolation.

### Reproducible execution

- SQLite catalog with immutable record identities
- Content hashes for source artifacts
- Configuration and source fingerprints for every run
- Checkpoint and resume logic
- 109 passing tests with no optional skips (v0.7.0)

## Architecture

```
memorylab/
    catalog.py          # SQLite catalog with typed observations
    channels.py         # Kraus operators, Choi matrices, erasure channels
    models.py           # Markov dynamics, finite baths, model dispatch
    spin.py             # Nuclear spin-bath evolution, CPMG, CCE
    network.py          # Network device export and retrieval
    sequence_adapter.py # SeQUeNCe native adapter
    runner.py            # Bounded worker processes, checkpoints
    calibration.py      # Observation binding and condition matching
    t2assessment.py     # T2 inference gates and diagnostics
    t2curves.py         # Curve fitting and model mismatch detection
    experimental.py     # Experimental data reanalysis
    datasets.py         # Source synchronization and verification
    pipeline.py         # Full pipeline orchestration
    cli.py              # Command-line interface (wqml)
    screening/          # Candidate screening and nuclear data
```

## Command reference

```bash
wqml doctor                                    # Check environment and capabilities
wqml datasets <plan.json>                       # Synchronize data sources
wqml catalog <catalog.sqlite>                   # Inspect the SQLite catalog
wqml generate <plan.json>                       # Generate candidate combinations
wqml run <study.json> --out <dir>               # Run a parameter study
wqml simulate <profile.json> --times <list>     # Simulate channel samples
wqml export <samples.json> --out <device.json>  # Export network device
wqml network <device.json> <device.json> <workload.json>  # Run network workload
wqml reproduce <baseline.json> --out <dir>      # Reproduce a bundled baseline
wqml pipeline <plan.json> --out <dir>           # Run the full pipeline
```

## Python API

```python
import numpy as np
from memorylab.network import load_device

# Load an exported memory device
device = load_device("runs/device.json", allow_hypothetical=True)

# Retrieve at a specific storage age
input_state = np.array([[0.5, 0.5], [0.5, 0.5]], dtype=complex)
result = device.retrieve(input_state, age_s=0.01, rng=np.random.default_rng(17))

if result["success"]:
    retrieved_state = result["density_matrix"]
```

## Evidence model

The framework distinguishes seven evidence kinds and enforces their boundaries:

| Evidence kind | Description | Example |
|---|---|---|
| `experimental` | Directly measured | Teller et al. state fidelities |
| `curated_experimental` | Processed from raw experimental data | Inverse-variance calibrated means |
| `fit_to_experiment` | Model fitted to experimental data | Pr decay curve fits |
| `evaluated_reference` | Reviewed reference value | Ortu et al. 230 ms Eu/YSO |
| `computed` | Numerical result | QuTiP channel evolution |
| `hypothetical` | Synthetic control | Markov profile with declared rates |
| `unknown` | Unresolved evidence | Molecular entry without reviewed curve |

## Validated scope

The v0.7.0 release validates:

- 336 state probes across 56 channel-age points (numerical agreement below 10^-15)
- 128 paired SeQUeNCe/QuNetSim comparisons (below 10^-10 tolerance)
- 109 passing tests with no optional skips
- 359 JSON records and 11 exact random-trace arrays checked in replay
- Open rare-earth (Pr³⁺:Y₂SiO₅) and diamond-spin (¹³C/NV) dataset reanalysis

## Limitations

- Matched experimental protocol tomography, material-specific bath validation, and native physical-latency comparison remain explicit requirements for broader predictions
- NetSquid and QuISP adapters are not evaluated in this release
- The framework does not claim universal simulator validation
- No new material or improved hardware performance is claimed

## Documentation

- [Model Contract](docs/MODEL_CONTRACT.md) — Physical model definitions and inference boundaries
- [Data Sources](docs/DATA_SOURCES.md) — Source data provenance and licensing
- [Extending](docs/EXTENDING.md) — How to add new model families and adapters

## Citation

If you use WestQuant in your research, please cite:

```bibtex
@software{vesterlund2026westquant,
  author = {Vesterlund, David},
  title = {{WestQuant Memory Discovery Lab}},
  version = {0.7.0},
  year = {2026},
  url = {https://github.com/VesterlundCoder/memory-discover-lab}
}
```

## License

MIT License. Copyright (c) 2026 David Vesterlund.

## Acknowledgements

WestQuant builds on PySCF, PyCCE, QuTiP, MaxwellBloch, SeQUeNCe, and QuNetSim. The author thanks the cited experimental-data and open-source software contributors for making their work available.
