Metadata-Version: 2.4
Name: qsafety-qae
Version: 0.1.2
Summary: Quantum amplitude estimation tools for safety and reliability probability models
Author-email: Ugwiyeon Lee <lyullee@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lyullee/qsafety-qae
Project-URL: Documentation, https://github.com/lyullee/qsafety-qae#readme
Project-URL: Issues, https://github.com/lyullee/qsafety-qae/issues
Keywords: quantum computing,amplitude estimation,safety,reliability,monte carlo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: qiskit
Requires-Dist: qiskit<3,>=2.2; extra == "qiskit"
Requires-Dist: qiskit-aer<1,>=0.17; extra == "qiskit"
Provides-Extra: ibm
Requires-Dist: qsafety-qae[qiskit]; extra == "ibm"
Requires-Dist: qiskit-ibm-runtime<1,>=0.43; extra == "ibm"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# QSafety QAE

`qsafety-qae` is a small research package for testing quantum amplitude
estimation (QAE) on safety and reliability probability models. It separates a
validated probability model from the estimator, simulator, circuit builder,
and optional QPU runner so that examples are reproducible without depending on
the original project directory.

The package supports:

- finite mixtures of fault, failure, or accident-scenario probabilities;
- exact weighted probability calculation;
- classical Monte Carlo and ideal maximum-likelihood QAE (ML-QAE) at the same
  equivalent oracle-query budget;
- Qiskit state preparation, Grover amplification checks, and Aer simulation;
- opt-in IBM Quantum preview and execution with a mandatory confirmation flag.

## Installation

Core estimators require only NumPy:

```bash
python -m pip install qsafety-qae
```

Install optional circuit or IBM Runtime support when needed:

```bash
python -m pip install "qsafety-qae[qiskit]"
python -m pip install "qsafety-qae[ibm]"
```

## Python interface

```python
from qsafety import RiskDistribution, compare_estimators

risk = RiskDistribution(
    weights=[0.25, 0.25, 0.25, 0.25],
    probabilities=[0.0095, 0.0145, 0.0231, 0.0638],
    labels=["very low", "low", "medium", "high"],
)

print(risk.probability)

mc, qae = compare_estimators(
    risk,
    powers=[0, 1, 2],
    shots=1024,
    repeats=1000,
    seed=42,
)
print(mc.rmse, qae.rmse)
```

Build and validate actual Qiskit circuits:

```python
from qsafety.circuits import build_qae_circuits, run_aer, validate_bundle

print(validate_bundle(risk, powers=[0, 1, 2]))
bundle = build_qae_circuits(risk, powers=[0, 1, 2])
result = run_aer(risk, powers=[0, 1, 2], shots=4096, seed=42)
print(result.estimate.probability)
```

## CSV and command-line interface

Input CSV files need one row per scenario or risk stratum:

```csv
label,weight,probability
very_low,0.25,0.0095
low,0.25,0.0145
medium,0.25,0.0231
high,0.25,0.0638
```

```bash
qsafety validate examples/phmsa_risk_strata.csv --label-column label
qsafety compare examples/phmsa_risk_strata.csv --label-column label \
  --powers 0 1 2 --shots 1024 --repeats 1000
qsafety circuits examples/phmsa_risk_strata.csv --label-column label
```

Commands print machine-readable JSON. The circuit command is available only
with the `qiskit` extra.

## IBM Quantum safety guard

`preview_ibm` transpiles circuits but does not submit them. The returned backend
and circuit resources should be reviewed before calling `run_ibm`. Submission
is blocked unless `confirm=True` is passed explicitly.

```python
from qsafety.ibm import preview_ibm, run_ibm

preview = preview_ibm(risk, shots=512, open_plan_only=True)
print(preview.backend, preview.executions, preview.resources)

# This is the only call that submits a QPU workload.
result = run_ibm(preview, confirm=True)
```

Credentials are read by `qiskit-ibm-runtime`; this package never stores API
tokens.

## Interpretation limits

The MC/QAE comparison is an algorithm-level comparison at an equal equivalent
oracle-query budget. It is not a wall-clock speed, energy-use, or end-to-end
quantum-advantage claim. State preparation, transpilation, QPU queue time, and
error mitigation are separate costs. Input-data and model uncertainty can also
be larger than either estimator's sampling error.

The included PHMSA-derived four-stratum file is a compact worked example, not a
pipeline-segment prediction model. It estimates a conditional outcome among
reported incidents and must not be used as an operational safety decision rule.

## Reproducible development

```bash
python -m pip install -e ".[dev,qiskit]"
pytest
python -m build
twine check dist/*
```

Legacy research scripts remain in the repository for traceability. Generated
study data and results stay local and are excluded from the public package.
Stable third-party integrations should use the public `qsafety` interface
documented above.

## License and citation

The software is released under the MIT License. Citation metadata is in
`CITATION.cff`. The version DOI will be added after the first Zenodo archive is
created.
