### Program Initialization with `start`

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog

The `start` function initializes a program's starting point, aliased as an empty ListOfLocations. It guides the subsequent steps for building the atomic geometry and specifying level coupling.

```APIDOC
## `start` `module-attribute`

```python
start = ListOfLocations()
```

A Program starting point, alias of empty [`ListOfLocations`][bloqade.ir.location.list.ListOfLocations].
* Next possible steps to build your program are:
* Specify which level coupling to address with:
  * `start.rydberg`: for [`Rydberg`][bloqade.builder.coupling.Rydberg] Level coupling
  * `start.hyperfine`: for [`Hyperfine`][bloqade.builder.coupling.Hyperfine] Level coupling
  * LOCKOUT: You cannot add atoms to your geometry after specifying level coupling.
* continue/start building your geometry with:
  * `start.add_position()`: to add atom(s) to current register. It will accept:
    * A single coordinate, represented as a tuple (e.g. `(5,6)`) with a value that can either be:
      * integers: `(5,6)`
      * floats: `(5.1, 2.5)`
      * strings (for later variable assignment): `("x", "y")`
      * [`Scalar`][bloqade.ir.scalar.Scalar] objects: `(2*cast("x"), 5+cast("y"))`
    * A list of coordinates, represented as a list of types mentioned previously.
    * A numpy array with shape (n, 2) where n is the total number of atoms
```

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

### Complete Bloqade Analog Example

Source: https://bloqade.quera.com/latest/analog

A comprehensive example demonstrating the setup, emulation, and hardware submission of a Rabi oscillation program using Bloqade Analog.

```python
from math import pi
from bloqade.analog.atom_arrangement import Honeycomb

geometry = Honeycomb(2, lattice_spacing = 10.0)
rabi_program = (
  geometry
  .rydberg.rabi.amplitude.uniform
  .constant(value=pi/2, duration=1.0)
)
emulation_results = rabi_program.bloqade.python().run(100)
bitstring_counts = emulation_results.report().counts()

hardware_rabi_program = (
  geometry
  .rydberg.rabi.amplitude.uniform
  .piecewise_linear(values = [0, pi/2, pi/2, 0], durations = [0.06, 1.0, 0.06])
)
hardware_results = hardware_rabi_program.braket.aquila.run_async(100)
hardware_bitstring_counts = hardware_results.report().counts()

```

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

### Initialize Program Start

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir

Use `start = ListOfLocations()` to initialize an empty program. Subsequent steps involve specifying level coupling (rydberg, hyperfine) or adding atoms using `start.add_position()`.

```python
start = ListOfLocations()

```

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

### Install uv Package Manager

Source: https://bloqade.quera.com/latest/install

Install the uv tool for managing development environments.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

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

### Install Bloqade Analog

Source: https://bloqade.quera.com/latest/analog

Install the Bloqade package using pip.

```bash
pip install bloqade

```

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

### Install Bloqade Packages

Source: https://bloqade.quera.com/latest/digital

Commands to install the full Bloqade package, the circuit submodule only, or the submodule with optional dependencies.

```bash
pip install bloqade
```

```bash
pip install bloqade-circuit
```

```bash
pip install bloqade-circuit[cirq,qasm2,stim]
```

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

### Install Bloqade SDK

Source: https://bloqade.quera.com/latest

Use pip to install the Bloqade package in your Python environment.

```bash
pip install bloqade
```

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

### Load Cirq Circuit Example

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/cirq_utils/lowering

Basic usage example for loading a Cirq circuit and printing its IR.

```python
# from cirq's "hello qubit" example
import cirq
from bloqade.cirq_utils import load_circuit

# Pick a qubit.
qubit = cirq.GridQubit(0, 0)

# Create a circuit.
circuit = cirq.Circuit(
    cirq.X(qubit)**0.5,  # Square root of NOT.
    cirq.measure(qubit, key='m')  # Measurement.
)

# load the circuit as squin
main = load_circuit(circuit)

# print the resulting IR
main.print()
```

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

### Execute Kernel with DynamicMemorySimulator

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/pyqrack/device

Example showing how to define a kernel and execute it using the DynamicMemorySimulator.

```python
# Define a kernel
@qasm2.main
def main():
    q = qasm2.qreg(2)
    c = qasm2.creg(2)

    qasm2.h(q[0])
    qasm2.cx(q[0], q[1])

    qasm2.measure(q, c)
    return q

# Create the simulator object
sim = DynamicMemorySimulator()

# Execute the kernel
qubits = sim.run(main)
```

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

### Build Documentation with Just

Source: https://bloqade.quera.com/latest/contrib

Builds the project documentation using the 'just' command. This command should be installed via 'uv sync'.

```bash
just doc

```

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

### Install Bloqade Sub-packages

Source: https://bloqade.quera.com/latest/install

Install optional sub-packages for extended functionality.

```bash
pip install bloqade[qasm2]
```

```bash
pip install bloqade-analog
```

```bash
pip install bloqade[qbraid]
```

```bash
pip install bloqade[stim]
```

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

### Install Bloqade QASM2 support

Source: https://bloqade.quera.com/latest/digital/compilation

Use this command to install the necessary dependencies for QASM2 functionality.

```bash
pip install bloqade[qasm2]
```

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

### Import required libraries

Source: https://bloqade.quera.com/latest/digital/examples/tsim/magic_state_distillation

Initial setup for the simulation environment including stim, numpy, and bloqade modules.

```python
# fmt: off
import stim
import numpy as np
from typing import Literal
import matplotlib.pyplot as plt

from bloqade import squin
from bloqade.squin import kernel
from bloqade.tsim import Circuit
```

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

### Setup pre-commit Hooks

Source: https://bloqade.quera.com/latest/install

Initialize pre-commit hooks to ensure code quality before committing.

```bash
pre-commit install
```

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

### Parallelize Usage Example

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/pragmas

Example of initializing a register and applying parallelization.

```python
>>> reg = start.add_position((0,0)).rydberg.rabi.uniform.amplitude.constant(1.0, 1.0)
```

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

### Initialize Program Start Point

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog

Initializes the starting point for a Bloqade program. Use this to begin defining atom geometry and level coupling.

```python
start = ListOfLocations()
```

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

### Install bloqade-analog with pip

Source: https://bloqade.quera.com/latest/analog/home/migration

Install the bloqade-analog package using pip. This is the primary method for adding the package to your Python environment.

```bash
pip install bloqade-analog

```

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

### Install Pre-commit Hooks

Source: https://bloqade.quera.com/latest/contrib

Installs pre-commit hooks to run linter checks before committing changes. If checks fail, the commit will be rejected.

```bash
pre-commit install

```

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

### Get Start Time of Slice

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/control/traits/slice

Retrieves the start time of a sliced object. This property returns a Scalar expression representing the start time.

```python
start: Scalar
```

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

### Select Backend for Execution

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Choose the backend for running the quantum program. Options include Braket (`braket`), Bloqade emulator (`bloqade`), or a specified device string (`device`).

```python
...piecewise_constant([durations], [values]).braket
```

```python
...piecewise_constant([durations], [values]).bloqade
```

```python
...piecewise_constant([durations], [values]).device
```

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

### Define Main Entry Point

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/pauli_exponentiation

Sets up the quantum register and invokes the Pauli exponential function.

```python
@qasm2.extended
def main():
    register = qasm2.qreg(4)
    pauli_exponential((register[0], register[1], register[2]), "ZXY", 0.5)
```

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

### Ramp Waveform Example

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

This example demonstrates how to ramp a waveform up to a specific value, hold it, and then ramp it down using `piecewise_linear`. It shows the initial setup for creating a drive.

```python
>>> prog = start.add_position((0,0)).rydberg.detuning.uniform
# ramp our waveform up to a certain value, hold it
# then ramp down. In this case, we ramp up to 2.0 rad/us in 0.3 us,
```

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

### Example Usage of Linear Waveform

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Illustrates how to start waveform construction by adding a position and then applying a linear detuning field.

```python
>>> prog = start.add_position((0,0)).rydberg.detuning.uniform
```

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

### Importing Required Libraries

Source: https://bloqade.quera.com/latest/digital/tutorials/auto_parallelism

Initializes the environment with necessary libraries for quantum circuit construction and visualization.

```python
import warnings

import cirq
import numpy as np
import matplotlib.pyplot as plt
import bloqade.cirq_utils as utils
from cirq.contrib.svg import SVGCircuit

from bloqade import squin, cirq_utils

warnings.filterwarnings("ignore")
```

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

### Get Aquila Capabilities and Use Max Rabi Frequency

Source: https://bloqade.quera.com/latest/analog/reference/hardware-capabilities

Retrieve hardware capabilities for the Aquila machine and use the maximum Rabi frequency to construct a Rabi waveform. Ensure `bloqade` is installed.

```python
from bloqade import get_capabilities, piecewise_linear

# get capabilities for Aquila
aquila_capabilities = get_capabilities()

# obtain maximum Rabi frequency as Decimal
max_rabi = aquila_capabilities.capabilities.rydberg.global_.rabi_frequency_max

# use that value in constructing a neat Rabi waveform
rabi_wf = piecewise_linear(durations = [0.5, 1.0, 0.5], values = [0, max_rabi, max_rabi, 0])
```

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

### Initialize Environment and Parameters

Source: https://bloqade.quera.com/latest/digital/examples/squin/deutsch_squin

Imports necessary modules and sets the number of bits for the algorithm.

```python
import random
from typing import Any

from bloqade.types import Qubit
from kirin.dialects import ilist
from bloqade.pyqrack import StackMemorySimulator

from bloqade import squin

n_bits = 2
```

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

### SliceTrait - start property

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/control/traits

Retrieves the start time of the sliced object.

```APIDOC
## GET /websites/bloqade_quera/traits/SliceTrait/start

### Description
Gets the start time of the sliced object.

### Method
GET

### Endpoint
/websites/bloqade_quera/traits/SliceTrait/start

### Parameters
This endpoint does not accept any parameters.

### Response
#### Success Response (200)
- **start** (Scalar) - The starting time of the sliced object as a Scalar Expression.

#### Response Example
```json
{
  "start": "Scalar Expression"
}
```
```

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

### Create Geometry from Scratch

Source: https://bloqade.quera.com/latest/quick_start/analog

Initialize a geometry from scratch by adding positions directly using bloqade.analog.start.

```python
from bloqade.analog import start

my_geometry = start.add_position([(1,2), (3,4), (5,6)])
```

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

### Piecewise Constant Usage Example

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Example of creating a staircase waveform.

```python
>>> prog = start.add_position((0,0)).rydberg.rabi.phase.uniform
# create a staircase, we hold 0.0 rad/us for 1.0 us, then
```

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

### ProgramStart.apply

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/start

Applies a pre-built sequence to a specific atom arrangement geometry.

```APIDOC
## apply

### Description
Apply a pre-built sequence to a program. This allows you to build a program independent of any geometry and then apply the program to said geometry.

### Parameters
#### Request Body
- **sequence** (SequenceExpr) - Required - The pre-built sequence to apply to the geometry.

### Response
- **SequenceBuilder** - Returns a SequenceBuilder object that allows for further configuration such as assignment, backend selection, or parallelization.
```

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

### Select Braket Backend

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Select the Braket backend for running the program, either the local emulator or QuEra hardware remotely.

```python
...apply(waveform).braket
```

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

### bitstrings Return Example

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/base

An example of the list of ndarrays returned by the bitstrings method.

```python
[array([[1, 1],
        [1, 1],
        [1, 1],
        ...,
        [1, 1],
        [1, 1],
        [1, 0]], dtype=int8)]
```

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

### Simulate Kernels with PyQrack

Source: https://bloqade.quera.com/latest/digital/tutorials/circuits_with_bloqade

Initializes a simulator emulator and executes a task to obtain results.

```python
from bloqade.pyqrack import StackMemorySimulator, DynamicMemorySimulator

# StackMemorySimulator - static number of qubits
# DynamicMemorySimulator - dynamic number of qubits, but slower. Use if you don't know how many qubits you need in advance.
emulator = StackMemorySimulator(min_qubits=8)

task = emulator.task(GHZ_state_factory, args=(4,))
results = task.run()
```

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

### Execute a kernel on a local simulator

Source: https://bloqade.quera.com/latest/digital/simulator_device/tasks

Instantiate a device and create a task to run a quantum kernel locally.

```python
from bloqade.pyqrack import StackMemorySimulator
from bloqade import squin

@squin.kernel
def main():
    q = squin.qalloc(2)

    squin.gate.h(q[0])
    squin.gate.cx(q[0], q[1])

    return q

sim = StackMemorySimulator(min_qubits=2)
task = sim.task(main)
result = task.run()
```

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

### POST /run

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/device

Runs a quantum kernel synchronously and returns the direct result.

```APIDOC
## POST /run

### Description
Runs the kernel and returns the result.

### Method
POST

### Endpoint
/run

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **kernel** (Method) - Required - The kernel method to run.
- **args** (tuple[Any, ...]) - Optional - Positional arguments to pass to the kernel method. Defaults to ().
- **kwargs** (dict[str, Any] | None) - Optional - Keyword arguments to pass to the kernel method. Defaults to None.

### Request Example
```json
{
  "kernel": "your_kernel_method",
  "args": [1, 2],
  "kwargs": {"param": "value"}
}
```

### Response
#### Success Response (200)
- **RetType** (Any) - The result of the kernel execution.

#### Response Example
```json
{
  "result": "some_value"
}
```
```

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

### POST /run

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/routine/bloqade

Executes the current quantum program using the Bloqade Python backend with specified simulation parameters.

```APIDOC
## POST /run

### Description
Run the current program using bloqade python backend.

### Method
POST

### Endpoint
/run

### Parameters
#### Query Parameters
- **shots** (int) - Required - number of shots after running state vector simulation
- **args** (Tuple[LiteralType, ...]) - Optional - The values for parameters defined
- **name** (Optional[str]) - Optional - Name to give this run. Defaults to None.
- **blockade_radius** (float) - Optional - Use the Blockade subspace given a particular radius. Defaults to 0.0.
- **waveform_runtime** (str) - Optional - Use Numba to compile the waveforms. Defaults to 'interpret'.
- **interaction_picture** (bool) - Optional - Use the interaction picture when solving schrodinger equation. Defaults to False.
- **cache_matrices** (bool) - Optional - Reuse previously evaluated matrcies when possible. Defaults to False.
- **multiprocessing** (bool) - Optional - Use multiple processes to process the batches. Defaults to False.
- **num_workers** (Optional[int]) - Optional - Number of processes to run with multiprocessing. Defaults to None.
- **solver_name** (str) - Optional - Which SciPy Solver to use. Defaults to 'dop853'.
- **atol** (float) - Optional - Absolute tolerance for ODE solver. Defaults to 1e-07.
- **rtol** (float) - Optional - Relative tolerance for adaptive step in ODE solver. Defaults to 1e-14.
- **nsteps** (int) - Optional - Maximum number of steps allowed per integration step. Defaults to 2147483647.

### Raises
- **ValueError** - Cannot use multiprocessing and cache_matrices at the same time.

### Response
#### Success Response (200)
- **LocalBatch** (LocalBatch) - Batch of local tasks that have been executed.

### Request Example
```json
{
  "shots": 1000,
  "name": "my_run",
  "blockade_radius": 0.5,
  "interaction_picture": true
}
```

### Response Example
```json
{
  "tasks": [
    {
      "id": "task_1",
      "status": "completed"
    }
  ]
}
```
```

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

### Pseudocode example of gate-based circuit construction

Source: https://bloqade.quera.com/latest/analog/reference/overview

Illustrates the similarity between Bloqade's builder syntax and common gate-based quantum SDK patterns.

```python
# this is strictly pseudocode
circuit = init_qubits(n_qubits)
# note the dots!
circuit.x(0).z(1).cnot(0, 1)...
```

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

### Define a Bloqade program using builder syntax

Source: https://bloqade.quera.com/latest/analog/reference/overview

Demonstrates the dot-intensive syntax used to define atom positions and Rabi amplitude parameters.

```python
from bloqade import start

prog = start.add_position((0,0)).rydberg.rabi.amplitude.uniform.constant(1,1)
```

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

### Initialize ProgramStart Builder

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/start

Initializes the ProgramStart node, which serves as the base for building a quantum program. It accepts an optional parent builder.

```python
ProgramStart(parent: Optional[Builder] = None)

def __init__(
    self,
    parent: Optional["Builder"] = None,
) -> None:
    self.__parent__ = parent
```

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

### Get Finished Tasks from Batch

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/batch

Creates a RemoteBatch object containing tasks with any of the following status codes: 'Completed', 'Failed', 'Unaccepted', 'Partial', 'Cancelled'. Use this to get all tasks that have reached a terminal state.

```python
def get_finished_tasks(self) -> "RemoteBatch":
    """
    Create a RemoteBatch object that
    contain finished tasks from current Batch.

    Tasks consider finished with following status codes:

    1. Failed
    2. Unaccepted
    3. Completed
    4. Partial
    5. Cancelled

    Return:
        RemoteBatch

    """
    # statuses that are in a state that will
    # not run going forward for any reason
    statuses = ["Completed", "Failed", "Unaccepted", "Partial", "Cancelled"]
    return self.get_tasks(*statuses)
```

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

### QRegGet Statement

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/qasm2/dialects/core/stmts

Get a qubit from a quantum register.

```APIDOC
## QRegGet

### Description
Get a qubit from a quantum register.

### Parameters
- **idx** (Int) - Required - The index of the qubit in the register.
- **reg** (QReg) - Required - The quantum register.

### Response
- **result** (Qubit) - The qubit at position idx.
```

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

### CRegGet Statement

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/qasm2/dialects/core/stmts

Get a bit from a classical register.

```APIDOC
## CRegGet

### Description
Get a bit from a classical register.

### Parameters
- **idx** (Int) - Required - The index of the bit in the register.
- **reg** (CReg) - Required - The classical register.

### Response
- **result** (Bit) - The bit at position idx.
```

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

### Run QFT Circuit on Simulator

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/qft

Instantiate the StackMemorySimulator and run the main function to execute the QFT circuit. The final state of the qubits is then printed.

```python
device = StackMemorySimulator(min_qubits=3)
qreg = device.run(main)
print(qreg)
```

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

### GET retrieve

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/batch

Retrieves missing task results for the RemoteBatch.

```APIDOC
## GET retrieve

### Description
Retrieves missing task results. This method updates the status of tasks and only pulls results for tasks that have completed.

### Method
GET

### Response
- **RemoteBatch** (object) - Returns the current RemoteBatch instance.
```

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

### Execute a quantum kernel with PyQrack

Source: https://bloqade.quera.com/latest/digital/tutorials/circuits_with_bloqade

Initializes a StackMemorySimulator and runs a GHZ state factory task.

```python
from bloqade.pyqrack import StackMemorySimulator, DynamicMemorySimulator # StackMemorySimulator - static number of qubits # DynamicMemorySimulator - dynamic number of qubits, but slower. Use if you don't know how many qubits you need in advance. emulator = StackMemorySimulator(min_qubits=8) task = emulator.task(GHZ_state_factory, args=(4,)) results = task.run() # The results are the same ResultType as the kernel return. # In this case, it is a list of qubits. print(results)
```

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

### Select Bloqade Backend

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Select the Bloqade backend for running the program, using the local emulator.

```python
...apply(waveform).bloqade
```

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

### GET show

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/base

Triggers an interactive visualization of the task report.

```APIDOC
## GET show

### Description
Displays an interactive visualization of the current task report.
```

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

### Sync Development Dependencies

Source: https://bloqade.quera.com/latest/install

Install dependencies based on the type of contribution.

```bash
# For contributing to code
uv sync --group dev
# For contributions to documentation
uv sync --group doc
# For just getting everything mentioned above
uv sync --all-groups
```

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

### GET /state_vector

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/pyqrack/task

Retrieves the current state vector of the quantum simulator.

```APIDOC
## GET /state_vector

### Description
Returns the state vector of the simulator.

### Method
GET

### Endpoint
/state_vector

### Parameters
None

### Request Body
None

### Response
#### Success Response (200)
- **state_vector** (list[complex]) - A list representing the complex amplitudes of the quantum state.

#### Response Example
```json
{
  "state_vector": [
    "0.707+0j",
    "0+0.707j"
  ]
}
```
```

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

### Initialize PyQrackSimulatorBase

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/pyqrack/device

Constructor for the base PyQrack simulation device.

```python
PyQrackSimulatorBase(
    options: PyQrackOptions = _default_pyqrack_args(),
    *,
    loss_m_result: Measurement = Measurement.One,
    rng_state: Generator = np.random.default_rng()
)
```

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

### GET tasks_metric

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/batch

Retrieves the current status metrics for tasks in the batch.

```APIDOC
## GET tasks_metric

### Description
Retrieves the current status metrics for tasks, returning a pandas DataFrame containing task IDs, statuses, and shot counts.

### Method
GET

### Response
#### Success Response (200)
- **DataFrame** (pd.DataFrame) - A DataFrame with columns ["task ID", "status", "shots"] indexed by task ID.
```

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

### Get Markdown Representation

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/base

Access the markdown representation of the underlying dataframe.

```python
markdown: str
```

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

### GET /fetch_results

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/exclusive

Fetches the final results of a completed task from AirTable.

```APIDOC
## GET /fetch_results

### Description
Fetch the task results from the AirTable.

### Method
GET

### Parameters
#### Query Parameters
- **task_id** (str) - Required - The task id to be queried.

### Response
#### Success Response (200)
- **response** (object) - The response from the AirTable.
```

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

### Run on Braket Emulator or QuEra Hardware

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Selects the Braket backend for running the program, supporting local emulation or remote execution on QuEra hardware.

```python
...slice(start, stop).braket
```

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

### Import Bloqade and PyQrack Modules

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/qft

Import the qasm2 module from bloqade and the StackMemorySimulator from bloqade.pyqrack. These are necessary for defining and simulating quantum circuits.

```python
import math

from bloqade.pyqrack import StackMemorySimulator

from bloqade import qasm2
```

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

### GET /query_task_status

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/exclusive

Queries the current status of a specific task from AirTable.

```APIDOC
## GET /query_task_status

### Description
Query the task status from the AirTable.

### Method
GET

### Parameters
#### Query Parameters
- **task_id** (str) - Required - The task id to be queried.

### Response
#### Success Response (200)
- **response** (object) - The response from the AirTable.
```

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

### Generalize GHZ kernel with a for loop

Source: https://bloqade.quera.com/latest/digital/dialects_and_kernels/squin

This example demonstrates using a for loop within a SQUIN kernel to generalize operations, such as creating a GHZ state for an arbitrary number of qubits. It requires importing the 'squin' library.

```python
from bloqade import squin

@squin.kernel
def ghz(n: int):
    q = squin.qalloc(n)

    squin.h(q[0])
    for i in range(n - 1):
        squin.cx(q[i], q[i + 1])
```

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

### GET parse_register

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/parse/trait

Parses the atom arrangement or parallel register configuration.

```APIDOC
## GET parse_register

### Description
Parses the arrangement of atoms in the program.

### Response
#### Success Response (200)
- **atom_arrangement** (Union[AtomArrangement, ParallelRegister]) - The parsed atom arrangement or parallel register.

#### Errors
- **ValueError** - If the register cannot be parsed.
```

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

### GET parse_circuit

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/parse/trait

Parses the analog circuit definition from the program builder.

```APIDOC
## GET parse_circuit

### Description
Parses the analog circuit from the program.

### Response
#### Success Response (200)
- **analog_circuit** (AnalogCircuit) - The parsed analog circuit object.

#### Errors
- **ValueError** - If the circuit cannot be parsed.
```

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

### Initialize DeviceTaskExpectMixin

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/task

Constructor signature for the DeviceTaskExpectMixin class.

```python
DeviceTaskExpectMixin(
    kernel: Method[Params, RetType],
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
)
```

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

### GET n_atoms

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/parse/trait

Retrieves the total number of atoms in the program register.

```APIDOC
## GET n_atoms

### Description
Returns the number of atoms in the program. If the register is of type ParallelRegister, the count is extracted from its internal register.

### Response
#### Success Response (200)
- **n_atoms** (int) - The number of atoms in the parsed register.

#### Errors
- **ValueError** - If the register type is unsupported.
```

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

### Batch Simulation and State Analysis

Source: https://bloqade.quera.com/latest/digital/tutorials/circuits_with_bloqade

This example shows how to perform batch simulations using `task.batch_run` and analyze the resulting quantum state with `task.batch_state`. It's useful for randomized outputs where averaging over many runs is required.

```python
# Define the emulator and task
emulator = StackMemorySimulator(min_qubits=1)
task = emulator.task(coinflip)
results = task.batch_run(shots=1000)
state = task.batch_state(shots=1000)
print("Results:", results)
print("State:", state)
```

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

### Waveform: Linear

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/control/waveform

Represents a linear waveform with a specified start, stop, and duration.

```APIDOC
## Linear

Bases: `Instruction`

### Description
Represents a linear waveform with a specified start, stop, and duration.

### Constructor
```python
Linear(
    start: ScalarType,
    stop: ScalarType,
    duration: ScalarType,
)
```

### Grammar
```
<linear> ::= 'linear' <scalar expr> <scalar expr>
```

### Functionality
f(t=0:duration) = start + (stop-start)/duration * t

### Parameters
Name | Type | Description | Default  
---|---|---|---
`start` |  `Scalar` |  start value |  _required_
`stop` |  `Scalar` |  stop value |  _required_
`duration` |  `Scalar` |  the time span of the linear waveform. |  _required_

### Source Code
```python
@beartype
def __init__(self, start: ScalarType, stop: ScalarType, duration: ScalarType):
    object.__setattr__(self, "start", cast(start))
    object.__setattr__(self, "stop", cast(stop))
    object.__setattr__(self, "duration", cast(duration))
```
```

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

### Get Qubit ID

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/qubit/stdlib/simple

Retrieves the global, unique ID of a specific qubit.

```python
get_qubit_id(qubit: Qubit) -> int
```

```python
@kernel
def get_qubit_id(qubit: Qubit) -> int:
    """Get the global, unique ID of the qubit.

    Args:
        qubit (Qubit): The qubit of which you want the ID.

    Returns:
        qubit_id (int): The global, unique ID of the qubit.
    """
    ids = broadcast.get_qubit_id(ilist.IList([qubit]))
    return ids[0]
```

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

### Emit and Print QASM2 Code

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/qft

Import QASM2 emitter and pretty-printer, then emit the QASM2 code for the main function and print the Abstract Syntax Tree (AST).

```python
from bloqade.qasm2.emit import QASM2  # noqa: E402
from bloqade.qasm2.parse import pprint  # noqa: E402

target = QASM2()
ast = target.emit(main)
pprint(ast)
```

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

### Circuit Class Initialization

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/stim/circuit

Information on how to initialize the Circuit class, including its parameters and inheritance.

```APIDOC
## Circuit

### Description
This class inherits from `stim.Circuit`. For the full API reference of the underlying circuit class, see: https://github.com/quantumlib/Stim/blob/main/doc/python_api_reference_vDev.md#stim.Circuit

### Method
`__init__`

### Endpoint
N/A (Class constructor)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example usage (assuming 'kernel' is a defined ir.Method object)
# from bloqade.stim.circuit import Circuit
# circuit = Circuit(kernel=my_kernel)
```

### Response
#### Success Response (200)
N/A (Class constructor)

#### Response Example
N/A (Class constructor)

### Constructor Parameters
- **kernel** (`Method`) - Required - The kernel to compile into a stim.Circuit.
```

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

### Get Measurement ID

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/qubit/stdlib/simple

Retrieves the global, unique ID of a measurement result.

```python
get_measurement_id(measurement: MeasurementResult) -> int
```

```python
@kernel
def get_measurement_id(measurement: MeasurementResult) -> int:
    """Get the global, unique ID of the measurement result.

    Args:
        measurement (MeasurementResult): The previously taken measurement of which you want to know the ID.
    Returns:
        measurement_id (int): The global, unique ID of the measurement.
    """
    ids = broadcast.get_measurement_id(ilist.IList([measurement]))
    return ids[0]
```

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

### GET /register_properties

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/location

Retrieves metadata and structural properties of the current atom arrangement.

```APIDOC
## GET /register_properties

### Description
Returns the current state of the register, including counts of atoms, sites, and dimensions.

### Method
GET

### Response
#### Success Response (200)
- **n_atoms** (int) - Number of filled sites.
- **n_dims** (int) - Number of dimensions in the register.
- **n_sites** (int) - Total number of sites.
- **n_vacant** (int) - Number of empty sites.
```

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

### Initialize Graph

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/qaoa

Create a random 3-regular graph with 32 nodes for the MaxCut problem.

```python
N = 32
G = nx.random_regular_graph(3, N, seed=42)
```

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

### POST /__call__ (Local Execution)

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/routine/braket

Compiles a quantum routine into a LocalBatch and runs it on the local emulator. This method is synchronous and will wait for results.

```APIDOC
## POST /__call__ (Local Execution)

### Description
Compiles to a LocalBatch, which contains tasks to run on the local emulator. This method is synchronous and will wait until remote results are finished.

### Method
POST

### Endpoint
/__call__

### Parameters
#### Query Parameters
- **shots** (int) - Optional - number of shots, defaults to 1
- **args** (LiteralType) - Optional - additional arguments for args variables.
- **name** (str | None) - Optional - custom name of the batch, defaults to None
- **multiprocessing** (bool) - Optional - enable multi-process, defaults to False
- **num_workers** (int | None) - Optional - number of workers to run the emulator, defaults to None

### Response
#### Success Response (200)
- **LocalBatch** (object) - Represents the batch of tasks executed on the local emulator.

### Request Example
```json
{
  "shots": 10,
  "args": ["arg1", "arg2"],
  "name": "my_local_batch",
  "multiprocessing": true,
  "num_workers": 4
}
```

### Response Example
```json
{
  "results": [
    {"state": "0", "probability": 0.5},
    {"state": "1", "probability": 0.5}
  ]
}
```
```

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

### Target Hyperfine Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Start targeting the Hyperfine level coupling for interactions.

```python
...apply(waveform).hyperfine
```

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

### show()

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/parse/trait

Displays the current program being defined with the given arguments and batch ID.

```APIDOC
## show()

### Description
Display the current program being defined with the given arguments and batch ID.

### Parameters
- **args** (list) - Optional - Additional arguments for display.
- **batch_id** (int) - Optional - The batch ID to be displayed. Defaults to 0.
```

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

### Target Rydberg Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Start targeting the Rydberg level coupling for interactions.

```python
...apply(waveform).rydberg
```

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

### Initialize BraketDeviceRoute

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/backend/braket

Initializes the BraketDeviceRoute builder. Use this as a base for specifying Braket hardware.

```python
BraketDeviceRoute(parent: Optional["Builder"] = None)
```

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

### Get Failed Tasks

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/task/batch

Retrieves a RemoteBatch object containing tasks that have failed or were unaccepted.

```APIDOC
## GET /api/tasks/failed

### Description
Create a RemoteBatch object that contain failed tasks from current Batch. Failed tasks have the following status codes: 1. Failed 2. Unaccepted

### Method
GET

### Endpoint
/api/tasks/failed

### Parameters
#### Query Parameters
- **status_codes** (string) - Required - Comma-separated list of status codes to filter tasks by (e.g., "Failed,Unaccepted").

### Response
#### Success Response (200)
- **RemoteBatch** (object) - An object representing a batch of failed tasks.

#### Response Example
```json
{
  "tasks": {
    "task_id_3": {
      "status": "Failed",
      "error": "..."
    },
    "task_id_4": {
      "status": "Unaccepted",
      "reason": "..."
    }
  }
}
```
```

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

### Create and Visualize a GHZ Circuit

Source: https://bloqade.quera.com/latest/digital/examples/interop/noisy_ghz

Initializes a 3-qubit GHZ circuit and renders it as an SVG.

```python
ghz_circuit_3 = ghz_circuit(3)
SVGCircuit(ghz_circuit_3)
```

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

### Target Hyperfine Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Starts targeting the Hyperfine level coupling for the current waveform.

```python
...poly([coeffs], duration).hyperfine
```

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

### Target Rydberg Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Starts targeting the Rydberg level coupling for the current waveform.

```python
...poly([coeffs], duration).rydberg
```

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

### Initialize BasicLatticeValidation

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/compiler/analysis/hardware/lattice

Constructor for the validation visitor, requiring QuEraCapabilities to define hardware constraints.

```python
BasicLatticeValidation(capabilities: QuEraCapabilities)
```

```python
def __init__(self, capabilities: QuEraCapabilities):
    self.capabilities = capabilities
```

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

### Initialize GeminiTwoZoneNoiseModel

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/cirq_utils/noise/model

Configures a noise model for two-zone Gemini architectures.

```python
GeminiTwoZoneNoiseModel(
    check_input_circuit: bool = True,
    scaling_factor: float = 1.0,
    cz_paired_correlated_rates: ndarray | None = None,
    cz_paired_error_probabilities: dict | None = None,
    *,
    local_px: float = 0.0004102,
    local_py: float = 0.0004102,
    local_pz: float = 0.0004112,
    local_loss_prob: float = 0.0,
    local_unaddressed_px: float = 2e-07,
    local_unaddressed_py: float = 2e-07,
    local_unaddressed_pz: float = 1.2e-06,
    local_unaddressed_loss_prob: float = 0.0,
    global_px: float = 6.5e-05,
    global_py: float = 6.5e-05,
    global_pz: float = 6.5e-05,
    global_loss_prob: float = 0.0,
    cz_paired_gate_px: float = 0.0006549,
    cz_paired_gate_py: float = 0.0006549,
    cz_paired_gate_pz: float = 0.003184,
    cz_gate_loss_prob: float = 0.0,
    cz_unpaired_gate_px: float = 0.0005149,
    cz_unpaired_gate_py: float = 0.0005149,
    cz_unpaired_gate_pz: float = 0.002185,
    cz_unpaired_loss_prob: float = 0.0,
    mover_px: float = 0.000806,
    mover_py: float = 0.000806,
    mover_pz: float = 0.002458,
    move_loss_prob: float = 0.0,
    sitter_px: float = 0.0003066,
    sitter_py: float = 0.0003066,
    sitter_pz: float = 0.0004639,
    sit_loss_prob: float = 0.0
)
```

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

### Target Hyperfine Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Starts targeting the Hyperfine level coupling for the current drive.

```python
prog.constant(value, duration).hyperfine
```

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

### Execute a simple Kirin kernel

Source: https://bloqade.quera.com/latest/digital/tutorials/circuits_with_bloqade

Demonstrates direct execution of a kernel using the default Kirin interpreter for basic logic.

```python
def foo(x: int, y: int) -> bool: return x < y assert foo(1, 2)
```

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

### Target Rydberg Level Coupling

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/builder/waveform

Starts targeting the Rydberg level coupling for the current drive.

```python
prog.constant(value, duration).rydberg
```

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

### Linear Waveform Definition

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir

Defines a linear waveform with a start value, stop value, and duration.

```APIDOC
## Linear

### Description
Creates a linear waveform defined by f(t=0:duration) = start + (stop-start)/duration * t.

### Parameters
- **start** (Scalar) - Required - Start value
- **stop** (Scalar) - Required - Stop value
- **duration** (Scalar) - Required - The time span of the linear waveform.
```

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

### Execute circuit on PyQrack backend

Source: https://bloqade.quera.com/latest/digital/examples/qasm2/repeat_until_success

Initializes the PyQrack quantum emulation backend and executes a defined circuit.

```python
from bloqade.pyqrack import PyQrack  # noqa: E402

device = PyQrack()
device.run(postselect_main)
```

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

### Initialize ParallelRegister

Source: https://bloqade.quera.com/latest/reference/bloqade-analog/src/bloqade/analog/ir/location

Base class for starting a program in Bloqade, used for building quantum operations.

```python
ParallelRegister(parent: Optional[Builder] = None)


```

```python
def __init__(
    self,
    parent: Optional["Builder"] = None,
) -> None:
    self.__parent__ = parent


```

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

### StackMemorySimulator Usage

Source: https://bloqade.quera.com/latest/reference/bloqade-circuit/src/bloqade/pyqrack/device

Demonstrates defining a kernel, executing it with the simulator, and retrieving state information.

```python
# Define a kernel
@qasm2.main
def main():
    q = qasm2.qreg(2)
    c = qasm2.creg(2)

    qasm2.h(q[0])
    qasm2.cx(q[0], q[1])

    qasm2.measure(q, c)
    return q

# Create the simulator object
sim = StackMemorySimulator(min_qubits=2)

# Execute the kernel
qubits = sim.run(main)
```

```python
ket = sim.state_vector(main)

from pyqrack.pauli import Pauli
expectation_vals = sim.pauli_expectation([Pauli.PauliX, Pauli.PauliI], qubits)
```