Qamomile

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:

@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:

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

Choose the installation style that matches your use case.

Full development environment:

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:

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:

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:

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

Runtime-only environment from source with QURI Parts support:

uv sync --no-dev --extra quri_parts

Runtime-only environment from source with Amazon Braket support:

uv sync --no-dev --extra braket

Runtime-only environment from source with qBraid support:

uv sync --no-dev --extra qbraid

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

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, NVIDIA/cuda-quantum#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:

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

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 and Japanese
• Tutorials: English and Japanese
• API reference: https://jij-inc-qamomile.readthedocs-hosted.com/latest/en/api/
• Repository: https://github.com/Jij-Inc/Qamomile

Contributing

Contributions, bug reports, and feedback are welcome via GitHub Issues and pull requests.

License

Qamomile is released under the Apache 2.0 License.

Citation

If you use Qamomile in your research, please cite:

@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}
}