### Transpile and Execute Quantum Kernels

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Illustrates the execution pipeline: transpiling the kernel for a specific SDK, executing it with parameter bindings, and retrieving results.

```python
exe = transpiler.transpile(biased_coin, parameters=["theta"])

job = exe.sample(
    transpiler.executor(),
    shots=256,
    bindings={"theta": math.pi / 4},
)
```

--------------------------------

### Inspect and Analyze Quantum Kernels

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Shows how to visualize a quantum kernel circuit and estimate its resource requirements (qubit and gate counts) before execution.

```python
biased_coin.draw(theta=0.6)

est = biased_coin.estimate_resources()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)
```

--------------------------------

### Install Qamomile from source

Source: https://github.com/jij-inc/qamomile/blob/main/README.md

Commands to clone the repository and set up the development environment using uv or pip.

```bash
git clone https://github.com/Jij-Inc/Qamomile.git
cd Qamomile
uv sync
uv sync --no-dev
uv sync --no-dev --extra quri_parts
pip install -e .
pip install -e ".[quri_parts]"
```

--------------------------------

### Serve English Documentation Locally

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Builds and serves the English version of the Qamomile documentation locally. Assumes the necessary build tools are installed. The documentation will be accessible at http://localhost:8000.

```bash
make serve-en
# Then open: http://localhost:8000
```

--------------------------------

### Development and Build Commands for Qamomile

Source: https://github.com/jij-inc/qamomile/blob/main/AGENTS.md

Common CLI commands for project management, including dependency installation, testing, linting, and documentation generation using uv and make.

```bash
uv sync
uv run pytest tests/
uv run ruff check qamomile/
uv run ruff format qamomile/
uv run zuban qamomile/
cd docs2 && make build
```

--------------------------------

### Access SampleResult Convenience Methods

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Shows how to extract statistical insights from a SampleResult object, such as the most common outcomes and probability distributions.

```python
print("most common:", result.most_common(1))
print("probabilities:", result.probabilities())
```

--------------------------------

### Serve Japanese Documentation Locally

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Builds and serves the Japanese version of the Qamomile documentation locally. Assumes the necessary build tools are installed. The documentation will be accessible at http://localhost:8000.

```bash
make serve-ja
# Then open: http://localhost:8000
```

--------------------------------

### Install Dependencies and Run Tests with uv

Source: https://github.com/jij-inc/qamomile/blob/main/CLAUDE.md

Commands for installing project dependencies using 'uv sync' and running various test suites with 'uv run pytest'. This includes options for running all tests, unit tests only, documentation tests only, or specific test files and cases.

```bash
# Install dependencies (using uv)
uv sync

# Run all tests
uv run pytest tests/

# Unit tests only (default, skips docs)
uv run pytest

# Docs tests only
uv run pytest -m docs -v

# All tests (unit + docs)
uv run pytest -m "" -v

# Specific tutorial
uv run pytest -m docs -k "en/tutorial/qaoa" -v

# Run a single test file
uv run pytest tests/core/test_qaoa.py

# Run a specific test
uv run pytest tests/core/test_qaoa.py::test_qaoa_converter -v
```

--------------------------------

### Transpile Qkernel to Native Circuit

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Converts a Qamomile qkernel into a target SDK-native circuit (e.g., Qiskit) for debugging and visual inspection.

```python
qiskit_circuit = transpiler.to_circuit(
    biased_coin,
    bindings={"theta": math.pi / 4},
)
print(qiskit_circuit)
```

--------------------------------

### Manually serving documentation on a different port

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

This command navigates to the build output directory for English documentation and starts a local HTTP server on port 8001. This is an alternative to using the Makefile's 'serve' targets, allowing for manual control over the port and directory.

```bash
cd en/_build/html && python -m http.server 8001
```

--------------------------------

### Install Qamomile SDK via pip

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/index.md

The standard installation method for the Qamomile library using the Python package manager. This command installs the core SDK and its dependencies.

```bash
pip install qamomile
```

--------------------------------

### Jupyter Book `myst.yml` Configuration Example

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

An example configuration file for Jupyter Book, specifying project settings, execution options, and the table of contents structure. It includes paths to markdown and notebook files for tutorials, optimization guides, and API references.

```yaml
version: 1

project:
  title: Qamomile Documentation
  jupyter: true
  execute:
    cache: true

  toc:
    - file: index.md
    - title: Tutorials
      children:
        - title: Foundations
          children:
            - file: tutorial/01_introduction.ipynb
            - file: tutorial/02_type_system.ipynb
            - file: tutorial/03_gates.ipynb
            - file: tutorial/04_superposition_entanglement.ipynb
        - title: Standard Library & Algorithms
          children:
            - file: tutorial/05_stdlib.ipynb
            - ...
        - title: Advanced Topics
          children:
            - file: tutorial/09_resource_estimation.ipynb
            - ...
    - title: Optimization
      children:
        - file: optimization/qaoa.ipynb
        - ...
    - title: API Reference
      file: api/index
      children:
        - file: api/circuit/index
        - file: api/optimization/index
        - ...

site:
  template: book-theme
  options:
    logo: ../assets/qamomile_logo.png
    style: ../assets/custom-theme.css

```

--------------------------------

### Execute Job and Retrieve Results

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Demonstrates how to execute a quantum job, block until completion using .result(), and iterate over the resulting measurement counts.

```python
result = job.result()
for value, count in result.results:
    print(f"  outcome={value}, count={count}")
```

--------------------------------

### Troubleshooting: 'No module named 'qamomile' or Jupyter Book not found

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

This command ensures that all project dependencies, including 'qamomile' and 'jupyter-book', are installed in the current environment. It is a prerequisite for building and running the documentation.

```bash
uv sync
```

--------------------------------

### Define a Quantum Kernel

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Demonstrates how to define a quantum kernel using the @qmc.qkernel decorator. It uses type annotations for parameters and return values, and applies quantum gates to qubit handles.

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

--------------------------------

### Constructing Quantum Circuits with Qamomile Frontend API

Source: https://github.com/jij-inc/qamomile/blob/main/AGENTS.md

Demonstrates the use of the @qm.qkernel decorator to define a quantum circuit and the subsequent transpilation process using a backend-specific transpiler.

```python
import qamomile.circuit as qm

@qm.qkernel
def my_circuit(q: qm.Qubit, theta: qm.Float) -> qm.Qubit:
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

transpiler = QiskitTranspiler()
executable = transpiler.transpile(my_circuit, bindings={"theta": 0.5})
```

--------------------------------

### Define and Execute a Quantum Kernel

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/index.md

Demonstrates how to define a quantum circuit using the @qmc.qkernel decorator and execute it using the Qiskit transpiler. The example shows qubit allocation, gate application, measurement, and sampling results.

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

@qmc.qkernel
def bell_state() -> tuple[qmc.Bit, qmc.Bit]:
    q0 = qmc.qubit(name="q0")
    q1 = qmc.qubit(name="q1")
    q0 = qmc.h(q0)
    q0, q1 = qmc.cx(q0, q1)
    return qmc.measure(q0), qmc.measure(q1)

transpiler = QiskitTranspiler()
exe = transpiler.transpile(bell_state)
result = exe.sample(transpiler.executor(), shots=1000).result()

for outcome, count in result.results:
    print(f"  {outcome}: {count}")
```

--------------------------------

### Create Qubits and Qubit Arrays

Source: https://context7.com/jij-inc/qamomile/llms.txt

Shows how to create single qubits and arrays of qubits using `qmc.qubit()` and `qmc.qubit_array()`. The example demonstrates creating a GHZ state circuit and a single qubit circuit with optional naming.

```python
import qamomile.circuit as qmc

@qmc.qkernel
def ghz_state(n: qmc.UInt) -> qmc.Vector[qmc.Bit]:
    # Create array of n qubits
    q = qmc.qubit_array(n, name="q")

    # Apply H to first qubit
    q[0] = qmc.h(q[0])

    # Entangle with CX chain
    for i in qmc.range(n - 1):
        q[i], q[i + 1] = qmc.cx(q[i], q[i + 1])

    return qmc.measure(q)

# Single qubit creation
@qmc.qkernel
def single_qubit_example() -> qmc.Bit:
    q = qmc.qubit(name="my_qubit")
    q = qmc.h(q)
    return qmc.measure(q)
```

--------------------------------

### Jupytext Configuration for New Tutorial Pages

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Example of the necessary Jupytext and kernel metadata required at the top of a new Python file to be treated as a Jupyter notebook by Jupytext. This includes specifying the format, version, and kernel details.

```python
# ---
# jupyter:
#   jupytext:
#     cell_metadata_filter: -all
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.18.1
#   kernelspec:
#     display_name: qamomile
#     language: python
#     name: qamomile
# ---

# %% [markdown]
# # Your Page Title
# Content goes here...

```

--------------------------------

### Define a Quantum Kernel with Qamomile Frontend API

Source: https://github.com/jij-inc/qamomile/blob/main/CLAUDE.md

Example demonstrating how to define a quantum circuit using Qamomile's frontend API. It utilizes the '@qm.qkernel' decorator and defines operations like Hadamard and RX gates.

```python
import qamomile.circuit as qm

@qm.qkernel
def my_circuit(q: qm.Qubit, theta: qm.Float) -> qm.Qubit:
    q = qm.h(q)
    q = qm.rx(q, theta)
    return q

# Build to IR and transpile
transpiler = QiskitTranspiler()
executable = transpiler.transpile(my_circuit, bindings={"theta": 0.5})
```

--------------------------------

### Build and analyze an iterative oracle skeleton

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/06_reuse_patterns.ipynb

Constructs a QKernel that integrates known gates with stub oracles. The example demonstrates how to perform resource estimation on the resulting structure to track oracle calls and query complexity.

```python
@qmc.qkernel
def iterative_oracle_skeleton(rounds: qmc.UInt) -> qmc.Vector[qmc.Qubit]:
    q = qmc.qubit_array(3, name="q")
    q[0] = qmc.h(q[0])
    q[1] = qmc.h(q[1])
    q[0], q[1] = qmc.cx(q[0], q[1])
    q[0], q[1], q[2] = phase_oracle(q[0], q[1], q[2])
    for i in qmc.range(rounds):
        q[1] = qmc.ry(q[1], 0.3)
        q[1], q[2] = qmc.cx(q[1], q[2])
        q[0], q[1], q[2] = phase_oracle(q[0], q[1], q[2])
        q[0], q[1], q[2] = mixing_oracle(q[0], q[1], q[2])
        q[1], q[2] = qmc.cx(q[1], q[2])
    return q

oracle_est = iterative_oracle_skeleton.estimate_resources().simplify()
print("total gates:", oracle_est.gates.total)
print("oracle_calls:", oracle_est.gates.oracle_calls)
```

--------------------------------

### Composite Gates and Helper Kernels - Qiskit

Source: https://context7.com/jij-inc/qamomile/llms.txt

Demonstrates creating reusable circuit patterns using helper qkernels (inlined) and @composite_gate (shown as boxes) in Qamomile. The examples show how to create GHZ states using both approaches and visualize the resulting circuits.

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

# Helper kernel - inlined into parent circuit
@qmc.qkernel
def entangle_once(q0: qmc.Qubit, q1: qmc.Qubit) -> tuple[qmc.Qubit, qmc.Qubit]:
    q0, q1 = qmc.cx(q0, q1)
    return q0, q1

@qmc.qkernel
def ghz_with_helper(n: qmc.UInt) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(n, name="q")
    q[0] = qmc.h(q[0])

    for i in qmc.range(n - 1):
        q[i], q[i + 1] = entangle_once(q[i], q[i + 1])

    return qmc.measure(q)

# Composite gate - appears as named box in diagrams
@qmc.composite_gate(name="entangle")
@qmc.qkernel
def entangle_link(q0: qmc.Qubit, q1: qmc.Qubit) -> tuple[qmc.Qubit, qmc.Qubit]:
    q0, q1 = qmc.cx(q0, q1)
    return q0, q1

@qmc.qkernel
def ghz_with_composite(n: qmc.UInt) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(n, name="q")
    q[0] = qmc.h(q[0])

    for i in qmc.range(n - 1):
        q[i], q[i + 1] = entangle_link(q[i], q[i + 1])

    return qmc.measure(q)

# Visualize - helper is inlined, composite shows as box
ghz_with_helper.draw(n=4, fold_loops=False)
ghz_with_composite.draw(n=4, fold_loops=False)
```

--------------------------------

### Parameterized Kernels with Bind/Sweep Pattern

Source: https://context7.com/jij-inc/qamomile/llms.txt

Explains how to use parameterized kernels by separating structure parameters (bound at transpile time) from runtime parameters (swept at execution time). This example defines a `rotation_layer` kernel.

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

@qmc.qkernel
def rotation_layer(n: qmc.UInt, theta: qmc.Float) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(n, name="q")

    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
        q[i] = qmc.ry(q[i], theta)

    return qmc.measure(q)

transpiler = QiskitTranspiler()
```

--------------------------------

### Observables and Hamiltonians - Qiskit

Source: https://context7.com/jij-inc/qamomile/llms.txt

Demonstrates building quantum observables using Pauli operators in Qamomile for expectation value calculations. Examples include single Pauli operators, linear combinations, interaction terms, and complex Hamiltonians suitable for VQE.

```python
import qamomile.observable as qmo

# Single Pauli operators
X0 = qmo.X(0)  # Pauli X on qubit 0
Y1 = qmo.Y(1)  # Pauli Y on qubit 1
Z2 = qmo.Z(2)  # Pauli Z on qubit 2

# Linear combinations
H = 0.5 * qmo.X(0) + 0.3 * qmo.Y(1) - 1.0 * qmo.Z(2)

# Interaction terms
H_interaction = qmo.Z(0) * qmo.Z(1)  # ZZ interaction

# Complex Hamiltonian (e.g., for VQE)
H_vqe = (
    -1.0 * qmo.Z(0) * qmo.Z(1)
    + 0.5 * qmo.X(0)
    + 0.5 * qmo.X(1)
    + 0.3 * qmo.Y(0) * qmo.Y(1)
)

print(f"Number of qubits: {H_vqe.num_qubits}")
print(f"Number of terms: {len(H_vqe)}")
print(f"LaTeX: {H_vqe.to_latex()}")
```

--------------------------------

### Standard Library: QFT, IQFT, QPE - Qiskit

Source: https://context7.com/jij-inc/qamomile/llms.txt

Shows how to use built-in Qamomile standard library implementations for Quantum Fourier Transform (QFT), Inverse Quantum Fourier Transform (IQFT), and Quantum Phase Estimation (QPE). Examples include preparing superposition and applying these transforms.

```python
import qamomile.circuit as qmc
from qamomile.circuit.stdlib import qft, iqft, qpe

@qmc.qkernel
def qft_example(n: qmc.UInt) -> qmc.Vector[qmc.Qubit]:
    q = qmc.qubit_array(n, name="q")

    # Apply Hadamard to prepare superposition
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])

    # Apply Quantum Fourier Transform
    q = qft(q)

    return q

@qmc.qkernel
def iqft_example(n: qmc.UInt) -> qmc.Vector[qmc.Qubit]:
    q = qmc.qubit_array(n, name="q")

    for i in qmc.range(n):
        q[i] = qmc.h(q[i])

    # Apply Inverse Quantum Fourier Transform
    q = iqft(q)

    return q

# Visualize QFT circuit
qft_example.draw(n=4, fold_loops=False)
```

--------------------------------

### Implement Conditional Measurement and Correction Loop

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/05_classical_flow_patterns.ipynb

Demonstrates a quantum kernel that repeatedly measures a qubit and conditionally applies an X-gate correction based on the measurement result. This example illustrates the use of while loops and conditional branching within the Qamomile framework.

```python
@qmc.qkernel
def measure_and_correct() -> qmc.Bit:
	q0 = qmc.qubit("q0")
	q1 = qmc.qubit("q1")

	q0 = qmc.h(q0)
	bit = qmc.measure(q0)

	while bit:
		# If bit is 1, apply correction to q1
		if bit:
			q1 = qmc.x(q1)
		else:
			q1 = q1
		# Re-prepare and re-measure
		q0 = qmc.qubit("q0_retry")
		q0 = qmc.h(q0)
		bit = qmc.measure(q0)

	return qmc.measure(q1)
```

```python
exe_combined = transpiler.transpile(measure_and_correct)
qc_combined = exe_combined.compiled_quantum[0].circuit
print(qc_combined)
```

--------------------------------

### Build and Serve Unified GitHub Pages Site

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Commands to build and serve the complete bilingual Qamomile documentation site locally. `make build-site` creates the `_site/` directory with `en/` and `ja/` subdirectories, and `make serve-site` builds and serves it.

```bash
make build-site   # build unified _site/ with en/ and ja/ subdirectories
make serve-site   # build and serve locally at http://localhost:8000
```

--------------------------------

### Initialize Qamomile Transpiler

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/04_execution_models.ipynb

Sets up the Qiskit transpiler environment required for compiling qkernels into executable quantum circuits.

```python
import qamomile.circuit as qmc
import qamomile.observable as qmo
from qamomile.qiskit import QiskitTranspiler

transpiler = QiskitTranspiler()
```

--------------------------------

### Define Multi-Qubit Kernel

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Illustrates the use of qubit_array for multi-qubit allocation and the handling of two-qubit gates like CNOT which return multiple handles.

```python
@qmc.qkernel
def two_qubit_demo() -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(2, name="q")
    q[0] = qmc.h(q[0])
    q[0], q[1] = qmc.cx(q[0], q[1])
    return qmc.measure(q)
```

--------------------------------

### Build and Serve Language-Specific Documentation

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Commands to build and serve either the English or Japanese version of the Qamomile documentation. These commands are useful for previewing changes during development.

```bash
make build-en  # or build-ja for Japanese
make serve-en  # or serve-ja for Japanese
```

--------------------------------

### Handle Affine Type Errors

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/01_your_first_quantum_kernel.ipynb

Demonstrates the error handling behavior when failing to reassign a quantum handle after a gate operation, violating the affine type system.

```python
try:
    @qmc.qkernel
    def bad_rebind() -> qmc.Bit:
        q = qmc.qubit(name="q")
        qmc.h(q)
        q = qmc.x(q)
        return qmc.measure(q)
    bad_rebind.draw()
except Exception as e:
    print(f"Error type: {type(e).__name__}")
    print(f"Error message: {e}")
```

--------------------------------

### Contributing: Previewing documentation changes

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

These commands build and then serve the documentation locally on port 8000. This allows contributors to preview the documentation as it would appear on the website, ensuring that the layout, formatting, and content are as intended before committing changes.

```bash
make serve-en
# or
make serve-ja
```

--------------------------------

### Define and Sample Multi-Qubit Qkernel

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/04_execution_models.ipynb

Demonstrates defining a qkernel that returns multiple bits and executing it using the sample() method to retrieve outcome counts.

```python
@qmc.qkernel
def parity_probe(theta: qmc.Float) -> tuple[qmc.Bit, qmc.Bit]:
    q0 = qmc.qubit(name="q0")
    q1 = qmc.qubit(name="q1")

    q0 = qmc.h(q0)
    q1 = qmc.ry(q1, theta)
    q0, q1 = qmc.cx(q0, q1)

    return qmc.measure(q0), qmc.measure(q1)

parity_probe.draw(theta=0.7)

exe_sample = transpiler.transpile(parity_probe, parameters=["theta"])
sample_result = exe_sample.sample(
    transpiler.executor(),
    shots=256,
    bindings={"theta": 0.7},
).result()

for outcome, count in sample_result.results:
    print(f"  outcome={outcome}, count={count}")
```

--------------------------------

### Build Documentation with Jupyter Book

Source: https://github.com/jij-inc/qamomile/blob/main/CLAUDE.md

Command to build project documentation using Jupyter Book. This command should be run from the directory containing the documentation source files.

```bash
# Build documentation (from docs/en or docs/ja directory)
jupyter-book build .
```

--------------------------------

### Construct Quantum Observables

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/04_execution_models.ipynb

Shows how to build concrete observable values using the qamomile.observable module for expectation value calculations.

```python
import qamomile.observable as qmo

H = qmo.Z(0)                        # Pauli Z on qubit 0
H = qmo.Z(0) * qmo.Z(1)             # ZZ interaction
H = 0.5 * qmo.X(0) + 0.3 * qmo.Y(1) # Linear combination
```

--------------------------------

### Scaling Analysis of QKernel Resources with .substitute() in Python

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/03_resource_estimation.ipynb

Evaluates symbolic resource estimation results for specific parameter values using the .substitute() method. This allows for obtaining concrete gate counts at different scales, aiding in feasibility checks for quantum computations.

```python
# Assuming 'est' is a ResourceEstimate object from a symbolic qkernel
# For example, from scalable_circuit.estimate_resources() in the previous snippet

# Example usage with a hypothetical 'est' object:
est_example = {
    "qubits": "n",
    "gates": {
        "total": "3*n - 1",
        "two_qubit": "n - 1"
    },
    "parameters": {"n": "n", "theta": "theta"}
}

# To make this runnable, we need a mock 'est' object that has a substitute method
class MockSymPyExpr:
    def __init__(self, value):
        self.value = value
    def __int__(self):
        return int(self.value)

class MockGates:
    def __init__(self, total, two_qubit):
        self.total = MockSymPyExpr(total)
        self.two_qubit = MockSymPyExpr(two_qubit)

class MockResourceEstimate:
    def __init__(self, qubits, gates, parameters):
        self.qubits = MockSymPyExpr(qubits)
        self.gates = MockGates(gates['total'], gates['two_qubit'])
        self.parameters = parameters

    def substitute(self, **kwargs):
        n_val = kwargs.get('n')
        if n_val is not None:
            total_gates = 3 * n_val - 1
            two_qubit_gates = n_val - 1
            return MockResourceEstimate(n_val, {"total": total_gates, "two_qubit": two_qubit_gates}, self.parameters)
        return self # Return self if no substitution is made or if n is not provided

# Create a mock 'est' object that mimics the output of scalable_circuit.estimate_resources()
est = MockResourceEstimate("n", {"total": "3*n - 1", "two_qubit": "n - 1"}, {"n": "n", "theta": "theta"})

for n_val in [4, 8, 16, 32]:
    c = est.substitute(n=n_val)
    print(
        f"n={n_val:2d}: {int(c.gates.total):>3} gates total, {int(c.gates.two_qubit):>2} two-qubit"
    )
```

--------------------------------

### Define and execute a quantum kernel

Source: https://github.com/jij-inc/qamomile/blob/main/README.md

Demonstrates defining a quantum kernel using the @qkernel decorator, inspecting resources, and executing the circuit using the Qiskit transpiler.

```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)

biased_coin.draw(theta=0.6)
est = biased_coin.estimate_resources()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)

transpiler = QiskitTranspiler()
exe = transpiler.transpile(biased_coin, parameters=["theta"])

result = exe.sample(
    transpiler.executor(),
    shots=256,
    bindings={"theta": math.pi / 4},
).result()

print(result.results)
```

--------------------------------

### Contributing: Testing documentation changes

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

These commands are used to build the documentation for either English or Japanese. They process the source files (e.g., `.py` and `.ipynb`) and generate the static HTML output for the documentation website. This step is crucial for verifying that changes to the documentation are rendered correctly.

```bash
make build-en
# or
make build-ja
```

--------------------------------

### Initialize Qamomile Transpiler

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/05_classical_flow_patterns.ipynb

Sets up the QiskitTranspiler instance required for compiling and executing Qamomile kernels.

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

transpiler = QiskitTranspiler()
```

--------------------------------

### Jupytext Percent Format Code Example

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

Illustrates the Jupytext percent format for organizing Python code and markdown content within a single file. This format uses `# %%` to delineate code cells and `# %% [markdown]` for markdown cells, making it IDE-friendly and suitable for version control.

```python
# %% [markdown]
# Markdown cells start with this marker

# %% 
# Python code cells start with this marker
print("Hello, Quantum World!")

# %% [markdown]
# You can mix markdown and code cells freely

```

--------------------------------

### Troubleshooting: Port 8000 already in use

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

This command forcefully terminates any running processes that are using the 'python -m http.server' command, which is often used for serving local web content. This is useful when a previous documentation server instance was not properly shut down and is preventing a new one from starting on the same port.

```bash
# Kill existing server
pkill -f "python -m http.server"
```

--------------------------------

### Transpile and Sweep Parameterized Quantum Circuits

Source: https://context7.com/jij-inc/qamomile/llms.txt

Demonstrates how to transpile a quantum circuit with fixed bindings while keeping specific parameters open for runtime sweeping. This allows for efficient execution of the same executable across multiple parameter values.

```python
exe = transpiler.transpile(
    rotation_layer,
    bindings={"n": 4},
    parameters=["theta"],
)

for theta in [0.1, 0.5, 1.0]:
    result = exe.sample(
        transpiler.executor(),
        shots=128,
        bindings={"theta": theta},
    ).result()
    print(f"theta={theta:.1f} -> {result.results}")
```

--------------------------------

### Estimate resources for a QKernel

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/06_reuse_patterns.ipynb

Demonstrates how to invoke the estimate_resources method on a QKernel to retrieve qubit counts and total gate metrics. This approach works even when the internal implementation of the kernel is unknown.

```python
est = algorithm_skeleton.estimate_resources().simplify()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)
```

--------------------------------

### Define Quantum Kernel with @qkernel Decorator

Source: https://context7.com/jij-inc/qamomile/llms.txt

Demonstrates how to define a quantum kernel using the `@qmc.qkernel` decorator. This function creates a Bell state, visualizes the circuit using `draw()`, and estimates resources using `estimate_resources()`.

```python
import qamomile.circuit as qmc

@qmc.qkernel
def bell_state() -> tuple[qmc.Bit, qmc.Bit]:
    q0 = qmc.qubit(name="q0")
    q1 = qmc.qubit(name="q1")
    q0 = qmc.h(q0)
    q0, q1 = qmc.cx(q0, q1)
    return qmc.measure(q0), qmc.measure(q1)

# Visualize the circuit
bell_state.draw()

# Estimate resources without execution
est = bell_state.estimate_resources()
print(f"Qubits: {est.qubits}, Gates: {est.gates.total}")
# Output: Qubits: 2, Gates: 2
```

--------------------------------

### Implement Classical Control Flow and Mid-Circuit Measurement

Source: https://context7.com/jij-inc/qamomile/llms.txt

Illustrates advanced patterns including loops using qmc.range, sparse data iteration with qmc.items, and conditional branching based on mid-circuit measurement results for error correction.

```python
@qmc.qkernel
def conditional_flip() -> qmc.Bit:
    q0 = qmc.qubit("q0")
    q1 = qmc.qubit("q1")
    q0 = qmc.x(q0)
    bit = qmc.measure(q0)
    if bit:
        q1 = qmc.x(q1)
    return qmc.measure(q1)
```

--------------------------------

### Apply Quantum Gates with Affine Type System

Source: https://context7.com/jij-inc/qamomile/llms.txt

Illustrates the application of various single-qubit, multi-qubit, and parameterized quantum gates. It highlights Qamomile's affine type system where gate operations require reassignment of the quantum handle.

```python
import qamomile.circuit as qmc
import math

@qmc.qkernel
def gate_demo(theta: qmc.Float) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(3, name="q")

    # Single-qubit gates
    q[0] = qmc.h(q[0])           # Hadamard
    q[0] = qmc.x(q[0])           # Pauli X
    q[0] = qmc.y(q[0])           # Pauli Y
    q[0] = qmc.z(q[0])           # Pauli Z
    q[0] = qmc.s(q[0])           # S gate
    q[0] = qmc.t(q[0])           # T gate

    # Rotation gates (parameterized)
    q[1] = qmc.rx(q[1], theta)   # RX rotation
    q[1] = qmc.ry(q[1], theta)   # RY rotation
    q[1] = qmc.rz(q[1], theta)   # RZ rotation
    q[1] = qmc.p(q[1], theta)    # Phase gate

    # Two-qubit gates (return both handles)
    q[0], q[1] = qmc.cx(q[0], q[1])    # CNOT
    q[1], q[2] = qmc.cz(q[1], q[2])    # CZ
    q[0], q[1] = qmc.swap(q[0], q[1])  # SWAP
    q[1], q[2] = qmc.rzz(q[1], q[2], theta)  # RZZ

    # Three-qubit gates
    q[0], q[1], q[2] = qmc.ccx(q[0], q[1], q[2])  # Toffoli

    return qmc.measure(q)
```

--------------------------------

### Makefile Targets for Qamomile Documentation

Source: https://github.com/jij-inc/qamomile/blob/main/docs/README.md

This section details the various targets available in the Makefile for managing the Qamomile project's documentation. These commands cover building, syncing Python to Jupyter notebooks, cleaning generated files, serving documentation locally, and regenerating API references.

```makefile
help: Print usage information
build: Full build (both languages)
build-en: Build English documentation
build-ja: Build Japanese documentation
sync: Convert all `.py` → `.ipynb` (both languages)
sync-en: Convert English `.py` → `.ipynb`
sync-ja: Convert Japanese `.py` → `.ipynb`
generate-api: Regenerate API reference from docstrings
copy-api: Copy API docs to language directories
clean: Remove generated files and build outputs
clean-all: Remove everything including execution cache
serve-en: Build and serve English docs (port 8000)
serve-ja: Build and serve Japanese docs (port 8000)
fresh-en: Clean, rebuild, and serve English docs
fresh-ja: Clean, rebuild, and serve Japanese docs
build-site: Build unified site for GitHub Pages
serve-site: Serve unified site locally (port 8000)
```

--------------------------------

### Compute Expectation Values with run()

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/04_execution_models.ipynb

Defines a qkernel using expval and executes it via the run() method, binding the observable at transpile time.

```python
@qmc.qkernel
def z_expectation(theta: qmc.Float, hamiltonian: qmc.Observable) -> qmc.Float:
    q = qmc.qubit(name="q")
    q = qmc.ry(q, theta)
    return qmc.expval(q, hamiltonian)

H = qmo.Z(0)
z_expectation.draw(theta=0.7, hamiltonian=H)

exe_run = transpiler.transpile(
    z_expectation,
    bindings={"hamiltonian": H},
    parameters=["theta"],
)

run_result = exe_run.run(
    transpiler.executor(),
    bindings={"theta": 0.7},
).result()

print("expectation value:", run_result)
print("python type:", type(run_result))
```

--------------------------------

### Substitute concrete values for resource estimation

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/06_reuse_patterns.ipynb

Demonstrates how to substitute symbolic variables like 'rounds' with concrete values to obtain final numeric resource counts from an existing estimation object.

```python
oracle_est_4 = oracle_est.substitute(rounds=4)
print("oracle_calls (rounds=4):", oracle_est_4.gates.oracle_calls)
print("oracle_queries (rounds=4):", oracle_est_4.gates.oracle_queries)
```

--------------------------------

### Symbolic Resource Estimation for Parameterized QKernels in Python

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/03_resource_estimation.ipynb

Estimates resource requirements for quantum circuits with symbolic parameters, returning SymPy expressions that show how costs scale. This allows for analysis of resource scaling without needing specific parameter values. It provides insights into the complexity as parameters change.

```python
import qamomile.circuit as qmc

@qmc.qkernel
def scalable_circuit(n: qmc.UInt, theta: qmc.Float) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(n, name="q")

    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
        q[i] = qmc.ry(q[i], theta)

    for i in qmc.range(n - 1):
        q[i], q[i + 1] = qmc.cx(q[i], q[i + 1])

    return qmc.measure(q)

est = scalable_circuit.estimate_resources()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)
print("single-qubit gates:", est.gates.single_qubit)
print("two-qubit gates:", est.gates.two_qubit)
print("rotation gates:", est.gates.rotation_gates)
print("parameters:", est.parameters)
```

--------------------------------

### Transpile and Execute with QiskitTranspiler

Source: https://context7.com/jij-inc/qamomile/llms.txt

Demonstrates transpiling a qkernel to a Qiskit circuit and executing it. It uses `QiskitTranspiler` to transpile the `biased_coin` kernel and then executes it multiple times with varying `theta` values using `sample()`.

```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)

transpiler = QiskitTranspiler()

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

# Execute with different parameter values (bind/sweep pattern)
for theta_val in [0.1, 0.5, 1.0, math.pi/2]:
    result = exe.sample(
        transpiler.executor(),
        shots=256,
        bindings={"theta": theta_val},
    ).result()

    print(f"theta={theta_val:.2f}: {result.results}")
    print(f"  Most common: {result.most_common(1)}")
    print(f"  Probabilities: {result.probabilities()}")
```

--------------------------------

### Visualize Parameterized Circuit

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/02_parameterized_kernels.ipynb

Visualizes the quantum kernel by binding symbolic parameters to concrete values for rendering.

```python
rotation_layer.draw(n=4, theta=0.3, fold_loops=False)
```

--------------------------------

### Helper QKernel Composition

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/06_reuse_patterns.ipynb

Demonstrates using a standard @qkernel as a helper function. The transpiler automatically inlines these calls, resulting in a flat circuit structure.

```python
@qmc.qkernel
def entangle_once(q0: qmc.Qubit, q1: qmc.Qubit) -> tuple[qmc.Qubit, qmc.Qubit]:
    q0, q1 = qmc.cx(q0, q1)
    return q0, q1

@qmc.qkernel
def ghz_with_helper(n: qmc.UInt) -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(n, name="q")
    q[0] = qmc.h(q[0])
    for i in qmc.range(n - 1):
        q[i], q[i + 1] = entangle_once(q[i], q[i + 1])
    return qmc.measure(q)
```

--------------------------------

### Basic Resource Estimation for Fixed QKernels in Python

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/03_resource_estimation.ipynb

Estimates the qubit and gate counts for a quantum circuit with no parameters. It returns concrete integer values for resource usage. This function is useful for understanding the exact cost of a specific quantum circuit.

```python
import qamomile.circuit as qmc

@qmc.qkernel
def fixed_circuit() -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(3, name="q")

    q[0] = qmc.h(q[0])
    q[0], q[1] = qmc.cx(q[0], q[1])
    q[1], q[2] = qmc.cx(q[1], q[2])

    return qmc.measure(q)

est = fixed_circuit.estimate_resources()
print("qubits:", est.qubits)
print("total gates:", est.gates.total)
print("single-qubit gates:", est.gates.single_qubit)
print("two-qubit gates:", est.gates.two_qubit)
```

--------------------------------

### Repeat-until-success with while loops

Source: https://github.com/jij-inc/qamomile/blob/main/docs/en/tutorial/05_classical_flow_patterns.ipynb

Demonstrates a repeat-until-success protocol using a while loop that re-prepares and measures a qubit until a specific condition is met.

```python
@qmc.qkernel
def repeat_until_zero() -> qmc.Bit:
    q = qmc.qubit("q")
    q = qmc.h(q)  # 50/50 chance of |0⟩ or |1⟩
    bit = qmc.measure(q)

    while bit:
        # Re-prepare and re-measure until we get 0
        q = qmc.qubit("q2")
        q = qmc.h(q)
        bit = qmc.measure(q)

    return bit

exe_while = transpiler.transpile(repeat_until_zero)
qc_while = exe_while.compiled_quantum[0].circuit
print(qc_while)
```