Metadata-Version: 2.4
Name: qamomile
Version: 0.15.1
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: jijmodeling>=2.1.0
Requires-Dist: ommx>=2.3.3
Requires-Dist: protobuf<7,>=5.29
Requires-Dist: sympy>=1.14.0
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.3.0; extra == "qiskit"
Requires-Dist: qiskit-aer>=0.17.2; extra == "qiskit"
Requires-Dist: qiskit-ibm-runtime<1,>=0.40; extra == "qiskit"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.10.8; extra == "visualization"
Provides-Extra: cudaq-cu12
Requires-Dist: cuda-quantum-cu12<0.15,>=0.14; sys_platform == "linux" and extra == "cudaq-cu12"
Provides-Extra: cudaq-cu13
Requires-Dist: cuda-quantum-cu13<0.15,>=0.14; sys_platform == "linux" and extra == "cudaq-cu13"
Requires-Dist: cuda-quantum-cu13<0.15,>=0.14; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "cudaq-cu13"
Provides-Extra: quri-parts
Requires-Dist: quri-parts-core>=0.21.1; extra == "quri-parts"
Requires-Dist: quri-parts-circuit>=0.21.1; extra == "quri-parts"
Requires-Dist: quri-parts-qulacs>=0.21.1; extra == "quri-parts"
Provides-Extra: qbraid
Requires-Dist: qbraid[qiskit]>=0.11.0; extra == "qbraid"
Provides-Extra: hugr
Requires-Dist: hugr<0.17,>=0.16; extra == "hugr"
Requires-Dist: selene-sim<0.3,>=0.2; extra == "hugr"
Requires-Dist: tket-exts<0.13,>=0.12; extra == "hugr"
Requires-Dist: qnexus<0.50,>=0.49; extra == "hugr"
Provides-Extra: braket
Requires-Dist: amazon-braket-sdk<2,>=1.125; extra == "braket"
Dynamic: license-file

# Qamomile

[![PyPI version](https://badge.fury.io/py/qamomile.svg)](https://badge.fury.io/py/qamomile)
![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)

> [!WARNING]
> This repository is actively developed.
> APIs may still change, including breaking changes, while active development continues.

Qamomile is a typed quantum programming SDK for writing quantum kernels in Python, inspecting them as Qamomile IR, estimating resources symbolically, and transpiling them to concrete execution quantum SDKs such as Qiskit, QURI Parts, CUDA-Q, and Amazon Braket. Qiskit circuits can also be executed through qBraid.

The current workflow is:

```text
@qkernel define -> draw() / estimate_resources() -> transpile() -> sample() / run() -> .result()
```

## Why Qamomile?

- Write quantum programs as typed Python functions with `@qkernel`.
- Use typed handles such as `Qubit`, `Bit`, `Float`, `UInt`, and `Observable`.
- Inspect kernels before execution with `draw()` and `estimate_resources()`.
- Build parameterized circuits and reuse a transpiled executable with different runtime bindings.
- Run measured programs with `sample()` and expectation-value programs with `run()`.
- Express circuit structure with classical control flow such as `qmc.range()`, `qmc.items()`, `if`, and `while`.
- Reuse circuit logic with helper kernels and `@composite_gate`.

## Installation

This README describes the current source tree, not the older PyPI release.
If you want this version, install from source.

Requirements:

- Python 3.11+
- `uv`

Clone the repository:

```bash
git clone https://github.com/Jij-Inc/Qamomile.git
cd Qamomile
```

Choose the installation style that matches your use case.

Full development environment:

```bash
uv sync
```

This installs the default development dependency group.
In the current `pyproject.toml`, that gives you Qiskit, circuit visualization,
and test tooling. Optional SDK integrations such as QURI Parts, qBraid,
and CUDA-Q still need their corresponding extras.

Documentation development environment:

```bash
uv sync --group docs
```

The `docs` group includes the default development dependencies and the
credential-free SDK integrations exercised by the documentation suite.

Runtime-only environment from source:

```bash
uv sync --no-dev
```

The compiler core is engine-independent. To run the Qiskit-based Quick Start
and render `draw()` output in a runtime-only environment, install the matching
extras:

```bash
uv sync --no-dev --extra qiskit --extra visualization
```

Runtime-only environment from source with QURI Parts support:

```bash
uv sync --no-dev --extra quri_parts
```

Runtime-only environment from source with Amazon Braket support:

```bash
uv sync --no-dev --extra braket
```

Runtime-only environment from source with qBraid support:

```bash
uv sync --no-dev --extra qbraid
```

Runtime-only environment from source with CUDA-Q v0.14.0 support:

```bash
uv sync --no-dev --extra cudaq-cu12   # for CUDA 12.x
uv sync --no-dev --extra cudaq-cu13   # for CUDA 13.x (or MacOS)
```

CUDA-Q v0.14.0 currently supports Linux, macOS ARM64 (Apple Silicon), and Windows via WSL2. For MacOS, please use `cudaq-cu13`.

> [!NOTE]
> **Why `cudaq-cu12` / `cudaq-cu13` instead of `cudaq`?**
>
> The upstream `cudaq` meta-package provides only an sdist whose `setup.py` dynamically computes `install_requires`.
> This causes `uv pip install cudaq` to silently install the package without its dependencies on the first attempt
> ([astral-sh/uv#12759](https://github.com/astral-sh/uv/issues/12759),
> [NVIDIA/cuda-quantum#3616](https://github.com/NVIDIA/cuda-quantum/issues/3616)).
> To avoid this issue, Qamomile specifies the concrete wheel packages `cuda-quantum-cu12` / `cuda-quantum-cu13` directly
> as optional dependencies, split by CUDA version.

If you prefer an explicit editable install inside your environment, this also works from the cloned repository:

```bash
pip install -e .
pip install -e ".[qiskit,visualization]"  # Qiskit Quick Start + draw()
pip install -e ".[quri_parts]"   # optional
pip install -e ".[braket]"       # optional
pip install -e ".[qbraid]"       # optional
pip install -e ".[cudaq-cu12]"   # optional, CUDA 12.x
pip install -e ".[cudaq-cu13]"   # optional, CUDA 13.x
```

If you intentionally want the latest published release instead, `pip install qamomile` installs the PyPI package, not this work-in-progress branch.

## Quick Start

```python
import math

import qamomile.circuit as qmc
from qamomile.qiskit import QiskitTranspiler


@qmc.qkernel
def biased_coin(theta: qmc.Float) -> qmc.Bit:
    q = qmc.qubit(name="q")
    q = qmc.ry(q, theta)
    return qmc.measure(q)


# Inspect the kernel before execution
biased_coin.draw(theta=0.6)
est = biased_coin.estimate_resources()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)

# Transpile once, keep theta as a runtime parameter
transpiler = QiskitTranspiler()
exe = transpiler.transpile(biased_coin, parameters=["theta"])

# Execute with a concrete binding
result = exe.sample(
    transpiler.executor(),
    shots=256,
    bindings={"theta": math.pi / 4},
).result()

print(result.results)
```

If a kernel returns measured bits, use `sample()`.
If it returns a `qmc.Float` from `qmc.expval(...)`, use `run()` instead.

## Main Packages

- `qamomile.circuit`: the main entry point for typed quantum kernels, gates, control flow, drawing, and resource estimation
- `qamomile.observable`: Hamiltonians and Pauli observables used with expectation-value workflows
- `qamomile.qiskit`: Qiskit transpiler and executor support
- `qamomile.cudaq`: optional CUDA-Q transpiler, executor, and observable conversion (supports both static sampling and runtime control-flow modes)
- `qamomile.qbraid`: optional qBraid executor support for running Qiskit circuits on qBraid-supported devices
- `qamomile.quri_parts`: optional QURI Parts transpiler and executor support
- `qamomile.braket`: optional Amazon Braket transpiler, local/cloud executor, and observable conversion
- `qamomile.optimization`: optimization-oriented functionality retained for continuity with older Qamomile workflows

## Optimization Support

Qamomile still supports the optimization-oriented workflow that older versions focused on.
That functionality lives under `qamomile.optimization`, including QAOA, FQAOA, and QRAO-related modules.
This README focuses on the current circuit-first API, but optimization support remains part of the project.

## Learn More

- Documentation: [English](https://jij-inc-qamomile.readthedocs-hosted.com/latest/en/) and [Japanese](https://jij-inc-qamomile.readthedocs-hosted.com/latest/ja/)
- Tutorials: [English](https://jij-inc-qamomile.readthedocs-hosted.com/latest/en/tutorial/) and [Japanese](https://jij-inc-qamomile.readthedocs-hosted.com/latest/ja/tutorial/)
- API reference: https://jij-inc-qamomile.readthedocs-hosted.com/latest/en/api/
- Repository: [https://github.com/Jij-Inc/Qamomile](https://github.com/Jij-Inc/Qamomile)

## Contributing

Contributions, bug reports, and feedback are welcome via [GitHub Issues](https://github.com/Jij-Inc/Qamomile/issues) and pull requests.

## License

Qamomile is released under the [Apache 2.0 License](LICENSE.txt).

## Citation

If you use Qamomile in your research, please cite:

```bibtex
@INPROCEEDINGS{11249901,
  author={Huang, Wei-Hao and Matsuyama, Hiromichi and Tam, Wai-Hong and Sato, Keisuke and Yamashiro, Yu},
  booktitle={2025 IEEE International Conference on Quantum Computing and Engineering (QCE)},
  title={Qamomile: A Cross-SDK Bridge for Quantum Optimization},
  year={2025},
  volume={02},
  pages={516-517},
  doi={10.1109/QCE65121.2025.10423}
}
```
