### Basic Circuit Construction

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates the fundamental way to construct a quantum circuit in Qiskit. This is the starting point for most quantum programs.

```python
from qiskit import QuantumCircuit

# Construct a quantum circuit with 2 qubits and 2 classical bits
qc = QuantumCircuit(2, 2)

# Add a H gate to the first qubit
qc.h(0)

# Add a CX gate between the first and second qubit
qc.cx(0, 1)

# Measure the qubits and store the results in the classical bits
qc.measure([0, 1], [0, 1])

# Print the circuit
print(qc)
```

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

### Basic Logging Example

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to set up basic logging to track the execution flow of a Qiskit program. Useful for understanding the sequence of operations and identifying where issues might arise.

```python
import logging

logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

def my_function():
    logging.info("Starting my_function")
    # ... function logic ...
    logging.info("Finished my_function")

my_function()
```

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

### Tracing with `qiskit.providers.aer.AerSimulator`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

This example demonstrates tracing capabilities using the `AerSimulator`. It allows for more detailed inspection of intermediate states and operations during circuit execution.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.aer import AerSimulator

# Create a quantum circuit
qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Use AerSimulator with tracing enabled
backend = AerSimulator(method='statevector', max_job_size=None)
traced_backend = backend.with_tracing()

# Transpile and run the circuit
transpiled_qc = transpile(qc, traced_backend)
traced_backend.run(transpiled_qc).result()
```

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

### Advanced Logging Configuration

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Provides an example of a more advanced logging setup, allowing for different log levels and handlers. This is useful for managing detailed logs during complex debugging sessions.

```python
import logging

# Create logger
logger = logging.getLogger('my_app')
logger.setLevel(logging.DEBUG)

# Create console handler and set level to info
ch = logging.StreamHandler()
ch.setLevel(logging.INFO)

# Create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# Add formatter to ch
ch.setFormatter(formatter)

# Add ch to logger
logger.addHandler(ch)

logger.debug('This is a debug message')
logger.info('This is an info message')
logger.warning('This is a warning message')
```

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

### Inspecting Circuit Structure with `qiskit.QuantumCircuit.draw()`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

This example shows how to visualize a quantum circuit using the `draw()` method. It's a fundamental step for debugging and understanding circuit logic.

```python
from qiskit import QuantumCircuit

# Create a quantum circuit
qc = QuantumCircuit(3)
pc.h(0)
pc.cx(0, 1)
pc.cx(1, 2)
pc.measure_all()

# Draw the circuit
print(qc.draw(output='text'))
```

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

### Sample with Bound Inputs

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.Samplex.html

Shows how to sample from a samplex after binding the required input values using the `inputs.bind()` method. This example samples 123 randomizations.

```python
# after binding required values, we can sample 123 randomizations
samplex.sample(
    inputs.bind(parameter_values=[0.1, 0.2]),
    num_randomizations=123,
)

```

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

### Debugging with `qiskit.providers.fake_provider`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Illustrates debugging using a fake backend from `qiskit.providers.fake_provider`. This is useful for testing circuit logic without relying on actual hardware or a full simulator setup.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.fake_provider import FakeManhattan

qc = QuantumCircuit(2, 2)
nc.h(0)
nc.cx(0, 1)
nc.measure([0, 1], [0, 1])

# Use a fake backend for debugging
backend = FakeManhattan()

transpiled_qc = transpile(qc, backend)
job = backend.run(transpiled_qc, shots=1)
result = job.result()
print(result.get_counts())

```

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

### Drawing Circuit with Latex

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Draws a quantum circuit using LaTeX for high-quality, publication-ready diagrams. Requires a LaTeX installation.

```python
from qiskit import QuantumCircuit
from qiskit.visualization import circuit_drawer

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

circuit_drawer(qc, output='latex')

```

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

### Define a Circuit with Tagged Boxes

Source: https://qiskit.github.io/samplomatic/guides/debug_tracing.html

This example demonstrates how to create a QuantumCircuit and add boxes with `Tag` and `InjectNoise` annotations. These tags are used by Samplomatic's tracing tools.

```python
from qiskit.circuit import QuantumCircuit

from samplomatic import InjectNoise, Tag, Twirl, build

circuit = QuantumCircuit(4, 4)

with circuit.box([Twirl(), Tag("cx_ab")]):
    circuit.cx(0, 1)

with circuit.box([Twirl(), InjectNoise("cx_noise"), Tag("cx_cd")]):
    circuit.cx(2, 3)

with circuit.box([Twirl(), Tag("meas_box")]):
    circuit.measure(range(4), range(4))

circuit.draw("mpl")

```

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

### Advanced Tracing with `qiskit.providers.aer.AerSimulator` and `method='density_matrix'`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

This example utilizes the `AerSimulator` with the `density_matrix` method for tracing. This method is suitable for simulating mixed states and provides detailed information about the system's evolution.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.aer import AerSimulator

# Create a quantum circuit
qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Use AerSimulator with density_matrix method
backend = AerSimulator(method='density_matrix')

# Transpile and run the circuit
transpiled_qc = transpile(qc, backend)
result = backend.run(transpiled_qc).result()

# Inspect the result (e.g., get the density matrix)
# print(result.get_density_matrix(qc))
```

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

### Setup Circuit with Boxes and Operations

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Constructs a quantum circuit with multiple boxed sections, each containing specific operations like rotations, CNOT gates, Hadamard gates, and measurements. It also includes classical registers and applies various samplomatic operations like Twirl, InjectNoise, and ChangeBasis within these boxes.

```Python
import matplotlib.pyplot as plt
import numpy as np
from qiskit.circuit import ClassicalRegister, Parameter, QuantumCircuit, QuantumRegister
from qiskit.quantum_info import Operator, Pauli, PauliLindbladMap

from samplomatic import ChangeBasis, InjectNoise, Twirl, build

# our circuit has two classical registers named alpha and beta
circuit = QuantumCircuit(
    QuantumRegister(4), alpha := ClassicalRegister(3, "alpha"), beta := ClassicalRegister(1, "beta")
)

# the first box is only twirled
with circuit.box([Twirl()]):
    for idx in range(4):
        circuit.rx(Parameter(f"a{idx}"), idx)
    circuit.cz(0, 1)
    circuit.cz(1, 2)

# the second box is twirled, and has noise injected
with circuit.box([Twirl(), InjectNoise(ref="ref1", modifier_ref="mod_ref1")]):
    circuit.h(1)
    circuit.cz(1, 2)

# the third box is twirled, and has different noise injected
with circuit.box([Twirl(), InjectNoise(ref="ref2", modifier_ref="mod_ref2")]):
    circuit.rx(0.1, range(4))
    circuit.cz(0, 1)
    circuit.cz(1, 2)

# the fourth box is the same as the second, but with a different modifer ref
with circuit.box([Twirl(), InjectNoise(ref="ref1", modifier_ref="mod_ref3")]):
    circuit.h(1)
    circuit.cz(1, 2)

circuit.barrier()

# the final two boxes twirl, and add a basis change in one case
with circuit.box([Twirl(), ChangeBasis(ref="conclude")]):
    circuit.measure(range(3), alpha)

with circuit.box([Twirl()]):
    circuit.measure([3], beta)

circuit.draw("mpl")
```

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

### Example Expectation Values Output

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

This is the expected output format for the comparison of expectation values between the base circuit and randomized circuits.

```text
  EVs from base circuit: [0.7819611  0.93553883 0.99500417]
EVs from randomizations: [0.7824 0.9348 0.9962]
```

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

### Free Dimensions Binding Example Output

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

Displays the free and bound dimensions after binding 'pauli_lindblad_maps' and 'local_scales', showing 'num_terms_ref2' is constrained.

```text
All free dimensions: {'num_terms_ref1', 'num_terms_ref2'}
Current constraints: {'num_terms_ref2': 2}

```

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

### Combine Boxing Pass Manager with Barrier-based ISA Boxing

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

Demonstrates combining a preset pass manager with a boxing pass manager for barrier-based ISA boxing. The boxing pass manager runs as a post-scheduling step, ensuring barriers guide stratification.

```python
preset_pm = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2], [2, 3], [3, 4], [4, 0]],
    optimization_level=1,
)
preset_pm.post_scheduling = generate_boxing_pass_manager()

boxed_heisenberg = preset_pm.run(heisenberg)
boxed_heisenberg.draw("mpl", scale=0.5, fold=100)
```

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

### Print Samplex Summary

Source: https://qiskit.github.io/samplomatic/guides/debug_tracing.html

Use `print(samplex)` to get a quick text summary of the node count, required inputs, and promised outputs of a Samplex object.

```python
template, samplex = build(circuit)
print(samplex)
```

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

### Simulating a Circuit and Getting Counts

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Simulates a quantum circuit using the QASM simulator and retrieves the measurement counts. This is a common workflow for verifying circuit behavior.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

provider = BasicProvider()
backend = provider.get_backend('qasm_simulator')

# Compile and run the circuit
compiled_circuit = transpile(qc, backend)
job = backend.run(compiled_circuit, shots=1024)
result = job.result()

counts = result.get_counts(qc)
print(counts)

```

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

### Drawing Circuit with Text (Latex)

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Draws a quantum circuit using text-based output, suitable for environments where graphical rendering is not available. This specific example uses LaTeX for rendering.

```python
from qiskit import QuantumCircuit
from qiskit.visualization import circuit_drawer

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

circuit_drawer(qc, output='text')

```

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

### Using a Debugger (Conceptual Example)

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

While direct integration of a Python debugger like `pdb` within Qiskit's core execution might be complex, you can use it to debug your Python code that *uses* Qiskit. Set breakpoints to step through your script.

```python
import pdb
from qiskit import QuantumCircuit

def complex_qiskit_operation(data):
    qc = QuantumCircuit(2)
    qc.h(0)
    # ... more Qiskit operations ...
    
    # Set a breakpoint to inspect variables before proceeding
    pdb.set_trace()
    
    # Simulate or run the circuit
    result = "some_result"
    return result

# Example usage
# complex_qiskit_operation([1, 0, 1, 0])
```

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

### Configure Plotly for Sphinx Gallery

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Ensures Plotly outputs are correctly rendered within Sphinx Gallery documentation. This is a setup step for visualization.

```python
# Without this cell, plotly outputs do not appear in the docs. We hide this cell from itself being
# rendered in the docs by editing its metadata to contain the tags ["remove-input", "remove-output"]
import plotly.io as pio

pio.renderers.default = "sphinx_gallery"
```

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

### Simulating a Circuit and Getting Unitary

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Simulates a quantum circuit to obtain its unitary matrix representation. This is useful for understanding the overall transformation performed by the circuit, especially for smaller circuits.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)

provider = BasicProvider()
backend = provider.get_backend('unitary_simulator')

# Compile and run the circuit
compiled_circuit = transpile(qc, backend)
job = backend.run(compiled_circuit)
result = job.result()

unitary = result.get_unitary(qc)
print(unitary)

```

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

### Specify Basis Change with Qubit Ordering

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Specifies a basis change using the qubit ordering convention. This example demonstrates how to define rotations for specific qubits based on their order.

```python
samplex.inputs().bind(basis_changes={"conclude": (basis_change := [2, 3, 1])})
basis_change
```

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

### Simulating a Circuit and Getting Statevector

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Simulates a quantum circuit using the statevector simulator to obtain the final quantum statevector. This provides detailed information about the amplitudes of all possible basis states.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)

provider = BasicProvider()
backend = provider.get_backend('statevector_simulator')

# Compile and run the circuit
compiled_circuit = transpile(qc, backend)
job = backend.run(compiled_circuit)
result = job.result()

statevector = result.get_statevector(qc)
print(statevector)

```

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

### Debugging with `qiskit.utils.QuantumInstance`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Shows how to set up a `QuantumInstance` for running circuits, which encapsulates backend and execution options. This is a precursor to using higher-level Qiskit algorithms.

```python
from qiskit import QuantumCircuit
from qiskit.utils import QuantumInstance
from qiskit.providers.basic_provider import BasicProvider

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

provider = BasicProvider()
backend = provider.get_backend('qasm_simulator')

# Create a QuantumInstance
qi = QuantumInstance(backend, shots=1024)

# Run the circuit using the QuantumInstance
result = qi.execute(qc).result()
counts = result.get_counts(qc)
print(counts)

```

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

### find_unreachable_nodes

Source: https://qiskit.github.io/samplomatic/_sources/api/auto/samplomatic.graph_utils.find_unreachable_nodes.rst.txt

This function takes a graph and a starting node as input and returns a set of nodes that are unreachable from the starting node. It's a utility function for graph analysis.

```APIDOC
## find_unreachable_nodes

### Description
Finds unreachable nodes in a graph starting from a given node.

### Signature
`find_unreachable_nodes(graph, start_node)`

### Parameters
* **graph** (dict) - The graph represented as an adjacency list (dictionary).
* **start_node** (any) - The node from which to start the traversal.

### Returns
* set - A set of nodes that are unreachable from the `start_node`.
```

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

### find_unreachable_nodes

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.graph_utils.find_unreachable_nodes.html

Finds all nodes in a directed graph that are not reachable from a given set of starting node indices.

```APIDOC
## find_unreachable_nodes

### Description
Finds all nodes from the graph that are not reachable from the start nodes.

### Method
N/A (Python function)

### Endpoint
N/A (Python function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- **unreachable_nodes** (set[int]) - A set of the unreachable node indices.

#### Response Example
N/A
```

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

### Build Samplex and Template from Circuit

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.Samplex.html

Demonstrates how to build a Samplex and a template circuit pair from a base circuit with annotated box instructions using the build() function. The resulting Samplex's DAG can then be drawn.

```python
from samplomatic import build, Twirl
from qiskit import QuantumCircuit

circuit = QuantumCircuit(2)
with circuit.box([Twirl()]):
   circuit.cz(0, 1)
with circuit.box([Twirl()]):
    circuit.measure_all()

template, samplex = build(circuit)
samplex.draw()
```

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

### Basic Debugging with `qiskit.utils.QuantumInstance`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to use `QuantumInstance` for basic debugging by setting `shots=1` to trace a single execution. This is useful for understanding the exact state transitions of a circuit.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.aer import AerSimulator
from qiskit.utils import QuantumInstance

qc = QuantumCircuit(2, 2)
nc.h(0)
nc.cx(0, 1)
nc.measure([0, 1], [0, 1])

# Use AerSimulator with shots=1 for debugging
aer_sim = AerSimulator()
qi = QuantumInstance(aer_sim, shots=1, seed_transpile_for_debug=12345, seed_sim=12345)

transpiled_qc = transpile(qc, qi)
result = qi.run(transpiled_qc).result()
print(result.get_counts())

```

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

### Get Style Method for CollectTemplateValues

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.nodes.CollectTemplateValues.html

Retrieves the plotting style for the CollectTemplateValues node. This is useful for visualization purposes.

```python
node.get_style()
```

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

### Running a Circuit on a Simulator

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Shows how to execute a Qiskit quantum circuit on a local simulator and retrieve the results.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Use the basic simulator provider
provider = BasicProvider()
backend = provider.get_backend('basic_simulator')

# Compile the circuit for the backend
transpiled_circuit = transpile(qc, backend)

# Run the circuit on the simulator
job = backend.run(transpiled_circuit)
result = job.result()

# Get the counts
counts = result.get_counts(qc)
print(f"\nTotal counts are: {counts}")
```

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

### PreCollect.get_style

Source: https://qiskit.github.io/samplomatic/_sources/api/auto/samplomatic.pre_samplex.PreCollect.rst.txt

Retrieves the style configuration for the PreCollect object. This method can be used to get information about how the data is formatted or processed.

```APIDOC
## PreCollect.get_style

### Description
Retrieves the style configuration for the PreCollect object. This method can be used to get information about how the data is formatted or processed.

### Method
(Not specified in source, likely a Python method call)

### Endpoint
(Not applicable, this is a Python class method)

### Parameters
(Parameters are not explicitly detailed in the source.)

### Request Example
(Not applicable for a Python method)

### Response
(The return type or value is not explicitly detailed in the source.)

ERROR HANDLING:
(Error handling details are not provided in the source.)
```

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

### Build and Inspect Samplex Inputs

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.Samplex.html

Demonstrates building a samplex from a circuit and inspecting its required inputs using the `inputs()` method. It shows that 'a' and 'b' parameters require float64 arrays.

```python
from samplomatic import build, Twirl
from qiskit.circuit import QuantumCircuit, Parameter

# quickly make a circuit and build it to construct an example simplex
circuit = QuantumCircuit(2)
with circuit.box([Twirl()]):
    circuit.rx(Parameter("a"), 0)
    circuit.rx(Parameter("b"), 0)
    circuit.cz(0, 1)
with circuit.box([Twirl()]):
    circuit.measure_all()

template, samplex = build(circuit)

# query the samplex for the expected inputs at sample time, and note that we
# are required to pass a length-2 vector of floats for 'a' and 'b' (alphabetical)
print(inputs := samplex.inputs())

```

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

### Basic Circuit Construction

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates the fundamental way to construct a quantum circuit in Qiskit, including adding qubits, classical bits, and gates.

```python
from qiskit import QuantumCircuit

# Construct a quantum circuit with 2 qubits and 2 classical bits
qc = QuantumCircuit(2, 2)

# Add a H gate to the first qubit
qc.h(0)

# Add a CX gate between the first and second qubit
qc.cx(0, 1)

# Add a measurement from the first qubit to the first classical bit
qc.measure(0, 0)

# Add a measurement from the second qubit to the second classical bit
qc.measure(1, 1)

print(qc)
```

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

### Debugging with `qiskit.utils.QuantumInstance`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates using `QuantumInstance` for debugging, allowing for detailed inspection of simulation parameters and results.

```python
from qiskit import QuantumCircuit
from qiskit.providers.basic_provider import BasicProvider
from qiskit.utils import QuantumInstance

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Set up a QuantumInstance for debugging
backend = BasicProvider().get_backend('basic_simulator')
qi = QuantumInstance(backend, shots=1024, seed_transpile_basis_gates=['h', 'cx'], seed_simulator=42)

# Run the circuit with the QuantumInstance
result = qi.execute(qc).result()
counts = result.get_counts(qc)
print(counts)

```

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

### Free Dimensions Example Output

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

Shows the expected output when inspecting free and bound dimensions, indicating 'num_randomizations' is a free dimension.

```text
All free dimensions: {'num_randomizations'}
Current constraints: {'num_randomizations': 3}

```

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

### Simulating a Circuit

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Shows how to simulate a quantum circuit using Qiskit's built-in simulators and retrieve the results.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Get a backend (simulator)
provider = BasicProvider()
backend = provider.get_backend('basic_simulator')

# Transpile the circuit for the backend
transpiled_qc = transpile(qc, backend)

# Run the simulation
job = backend.run(transpiled_qc, shots=1024)
result = job.result()

# Get the counts
counts = result.get_counts(qc)
print(counts)
```

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

### Generate Boxing Pass Manager

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.transpiler.generate_boxing_pass_manager.html

Creates a PassManager to box circuit operations. This example demonstrates basic usage with default parameters.

```python
from qiskit.circuit import QuantumCircuit
from samplomatic.transpiler import generate_boxing_pass_manager

# Create a simple circuit to test with
circuit = QuantumCircuit(3)
circuit.cz(0, 1)
circuit.cz(1, 2)
circuit.measure_all()

pm = generate_boxing_pass_manager()

boxed_circuit = pm.run(circuit)
boxed_circuit.draw("mpl")

```

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

### Tracing Circuit Execution with `qiskit.compiler.transpile`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Shows how to use the `transpile` function with specific options to trace the compilation process of a quantum circuit. This helps in understanding how the circuit is transformed into an executable form for a given backend.

```python
from qiskit import QuantumCircuit
from qiskit.compiler import transpile
from qiskit.providers.fake_provider import FakeManhattan

qc = QuantumCircuit(2)
pc.h(0)
pc.cx(0, 1)

backend = FakeManhattan()
transpiled_qc = transpile(qc, backend, optimization_level=0, seed_transpiler=42)

print(transpiled_qc.draw())
```

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

### Samplex with dictionary inputs

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Shows how to provide inputs to the `samplex.sample` method as a standard Python dictionary. The method internally binds these dictionary items to validate inputs.

```python
inputs = {
    "pauli_lindblad_maps": {
        "ref1": PauliLindbladMap.identity(2),
        "ref2": PauliLindbladMap.identity(4),
    },
    "basis_changes": {"conclude": [0, 1, 2]},
    "parameter_values": np.linspace(0, 1, 4),
}
outputs = samplex.sample(inputs, num_randomizations=3)
```

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

### Using the AerSimulator with Options

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to use the AerSimulator from Qiskit Aer, allowing for advanced simulation options and different simulation methods.

```python
from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

# Use AerSimulator
backend = AerSimulator(method='automatic')

# Compile and run the circuit
compiled_circuit = transpile(qc, backend)
job = backend.run(compiled_circuit, shots=1024)
result = job.result()

counts = result.get_counts(qc)
print(counts)

```

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

### Generate PassManager to Group Only Measurements

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

This example demonstrates creating a `PassManager` where only measurements are grouped into boxes, while two-qubit gates are not. This is achieved by setting `enable_gates` to `False`.

```python
boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=False,
    enable_measures=True,
)
transpiled_circuit = boxing_pass_manager.run(circuit)
transpiled_circuit.draw("mpl", scale=0.8)
```

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

### Running a Circuit on a Simulator

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Illustrates how to execute a quantum circuit on a local simulator provided by Qiskit Aer. This is essential for testing and debugging circuits without needing real quantum hardware.

```python
from qiskit import QuantumCircuit
from qiskit.providers.basic_provider import BasicProvider

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Get a basic simulator backend
backend = BasicProvider().get_backend('basic_simulator')

# Execute the circuit on the simulator
job = backend.run(qc)
result = job.result()

# Get the counts of the measurement outcomes
counts = result.get_counts(qc)
print(counts)
```

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

### Bind PauliLindbladMap and Local Scales

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Binds a PauliLindbladMap and local scales to Samplex inputs. This example demonstrates how both can share a common free dimension for the number of terms.

```python
# both the PauliLindbladMap and the local scales imply 2 terms, so that the free dimension
# 'num_terms_noise2' is satisfied
inputs = samplex.inputs().bind(
    pauli_lindblad_maps={"ref2": PauliLindbladMap.from_list([("XXYZ", 0.1), ("IIXX", 0.2)])},
    local_scales={"mod_ref2": [1, 2]},
)
print("All free dimensions:", inputs.free_dimensions)
print("Current constraints:", inputs.bound_dimensions)
```

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

### Debugging with `qiskit.utils.optionals`

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to conditionally import optional dependencies like `ipywidgets` for enhanced debugging experiences in environments like Jupyter notebooks.

```python
from qiskit.utils.optionals import HAS_IPYwidgets

if HAS_IPYwidgets:
    from ipywidgets import IntSlider, interact

    def f(x=1):
        return x

    interact(f, x=IntSlider(min=-10, max=30, step=1, value=10))
else:
    print("ipywidgets not found, skipping interactive widget.")
```

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

### Building a circuit with Twirl, InjectNoise, and Tag

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

This snippet shows how to construct a quantum circuit and apply Twirl, InjectNoise, and Tag annotations to different operations using context managers. It then draws the circuit.

```python
from qiskit.circuit import QuantumCircuit

from samplomatic import InjectNoise, Tag, Twirl, build

circuit = QuantumCircuit(4, 4)

with circuit.box([Twirl(), Tag("cx_ab")]):
    circuit.cx(0, 1)

with circuit.box([Twirl(), InjectNoise("cx_noise"), Tag("cx_cd")]):
    circuit.cx(2, 3)

with circuit.box([Twirl(), Tag("meas_box")]):
    circuit.measure(range(4), range(4))

circuit.draw("mpl")
```

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

### Using the Statevector Simulator

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to use the statevector simulator to obtain the final quantum state of the circuit. This provides detailed information about the quantum state, which is useful for advanced debugging.

```python
from qiskit import QuantumCircuit
from qiskit.providers.basic_provider import BasicProvider

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)

# Get the statevector simulator backend
backend = BasicProvider().get_backend('statevector_simulator')

# Run the circuit and get the statevector
job = backend.run(qc)
result = job.result()
statevector = result.get_statevector(qc)
print(statevector)
```

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

### Create Base Circuit for Twirling Strategy Demonstration

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

Initializes a QuantumCircuit with 5 qubits and 2 classical bits, then applies a series of Hadamard and CNOT gates to create a base circuit for demonstrating twirling strategies.

```python
circuit = QuantumCircuit(5, 2)
circuit.h(range(4))
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
circuit.barrier()
circuit.h(range(4))
```

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

### Create a Sample Quantum Circuit

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

This code defines a sample quantum circuit with Hadamard, CZ, CX, RZ, RX gates, and measurements. It's used to demonstrate the effects of the transpiler.

```python
from qiskit.circuit import Parameter, QuantumCircuit

circuit = QuantumCircuit(4, 7)
circuit.h(1)
circuit.h(2)
circuit.cz(1, 2)
circuit.h(1)
circuit.cx(1, 0)
circuit.cx(2, 3)
circuit.measure(range(1, 4), range(3))
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
for qubit in range(4):
    circuit.rz(Parameter(f"th_{qubit}"), qubit)
    circuit.rx(Parameter(f"phi_{qubit}"), qubit)
    circuit.rz(Parameter(f"lam_{qubit}"), qubit)
circuit.measure(range(4), range(3, 7))

circuit.draw("mpl", scale=0.8)
```

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

### sample

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.Samplex.html

Performs sampling based on the Samplex configuration. It takes input bindings and returns the sampled results.

```APIDOC
## sample

### Description
Sample. The following example builds a simple circuit with two parameters into a samplex to demonstrate calling this method. In particular, note that required inputs to the samplex nodes, which includes both type and array shape information, are listed by `inputs()`, and need to be bound with values.

### Method
sample

### Parameters
#### Path Parameters
- **samplex_input** (Mapping[str, Any] | None) - Optional - A mapping from input names to input values, as described by `inputs()` (see also the Samplex Inputs and Outputs guide), or `None` if no input is required. Names that contain a period can use nested dictionary expansion. Note that `TensorInterface` is a mapping object and is therefore a valid input argument when fully bound.
- **num_randomizations** (int) - Optional - The number of randomizations to sample. Defaults to 1.
- **keep_registers** (bool) - Optional - Whether to keep the virtual registers used during sampling and include them in the output under the metadata key "registers".
- **rng** (int | SeedSequence | Generator | None) - Optional - A random number generator or seed.
- **max_workers** (int | None) - Optional - The maximum number of workers to use for sampling.

### Returns
- **SamplexOutput** - The sampled results.
```

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

### Visualizing Circuit Statevector

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Illustrates how to obtain and visualize the statevector of a quantum circuit using Qiskit's statevector simulator.

```python
from qiskit import QuantumCircuit
from qiskit.providers.basic_provider import BasicProvider
from qiskit.visualization import plot_bloch_multivector

# Construct a quantum circuit
qc = QuantumCircuit(1)
pc.h(0)

# Use the basic simulator provider
provider = BasicProvider()
backend = provider.get_backend('statevector_simulator')

# Run the circuit on the statevector simulator
job = backend.run(qc)
result = job.result()
statevector = result.get_statevector(qc)

# Plot the Bloch sphere for the qubit
plot_bloch_multivector(statevector)
```

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

### Simulating and Correcting with StatevectorSampler

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

This snippet shows how to use StatevectorSampler to get simulation data from multiple randomizations and apply bitflip correction. The corrected data is then used to calculate expectation values.

```python
from qiskit.primitives import StatevectorSampler as Sampler
from qiskit.primitives.containers import BitArray

# get the sampler data from each randomization, and do bitflip correction
sampler_job = Sampler().run([(template, outputs["parameter_values"])], shots=10_000)
alpha_data = sampler_job.result()[0].data["alpha"]
alpha_data ^= BitArray.from_bool_array(outputs["measurement_flips.alpha"], "little")
```

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

### Simulating a Circuit and Inspecting Results

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Run a quantum circuit on a simulator and examine the measurement outcomes. This helps in verifying circuit logic.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.basic_provider import BasicProvider

# Create a quantum circuit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Use the basic simulator
provider = BasicProvider()
backend = provider.get_backend('basic_simulator')

# Transpile the circuit for the backend
transpiled_qc = transpile(qc, backend)

# Run the simulation
job = backend.run(transpiled_qc, shots=1024)
result = job.result()

# Get the counts
counts = result.get_counts(qc)
print(f"\nTotal counts are: {counts}")
```

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

### pre_build

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.builders.pre_build.html

Builds a template state and a pre-samplex for a given boxed-up circuit. This is a helper method for build() and not typically used directly in standard workflows.

```APIDOC
## pre_build

### Description
Builds a template state and a pre-samplex for the given boxed-up circuit. This is a helper method to `build()` and is not intended to be useful in standard workflows.

### Method
`pre_build(_circuit : QuantumCircuit_, _debug : bool = False_)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **circuit** (QuantumCircuit) - The circuit to build.
* **debug** (bool) - Optional. Defaults to False. Whether to populate pre-nodes with information that traces them back to the boxes that generated them. Tracing information is based on `ref` attributes of box annotations.

### Returns
* **tuple[TemplateState, PreSamplex]** - The built template state and the corresponding pre-samplex.
```

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

### Visualizing Circuit Structure

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Shows how to visualize the structure of a quantum circuit using Qiskit's built-in drawer. This is useful for understanding the circuit's layout and gate connections.

```python
from qiskit import QuantumCircuit

# Construct a quantum circuit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Draw the circuit
qc.draw(output='text')
```

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

### Create Circuit with Unmeasured Qubit

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

Defines a QuantumCircuit with an unmeasured qubit (qubit 0) and parameterized gates, followed by measurements on other qubits. This circuit serves as an example for demonstrating the transpiler's handling of unmeasured qubits.

```python
circuit_with_unmeasured_qubit = QuantumCircuit(4, 3)
circuit_with_unmeasured_qubit.cz(0, 1)
circuit_with_unmeasured_qubit.cz(2, 3)
for qubit in range(4):
    circuit_with_unmeasured_qubit.rz(Parameter(f"th_{qubit}"), qubit)
    circuit_with_unmeasured_qubit.rx(Parameter(f"phi_{qubit}"), qubit)
    circuit_with_unmeasured_qubit.rz(Parameter(f"lam_{qubit}"), qubit)
circuit_with_unmeasured_qubit.measure(range(1, 4), range(3))

circuit_with_unmeasured_qubit.draw("mpl", scale=0.8)
```

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

### Specify Pauli Lindblad Map with Qubit Ordering

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Specifies a Pauli Lindblad map using the determined qubit ordering convention. This example shows how to apply noise to a specific qubit based on its position in the convention.

```python
samplex.inputs().bind(
    pauli_lindblad_maps={
        "ref1": (noise1 := PauliLindbladMap.from_sparse_list([("X", [1], 0.12)], num_qubits=2))
    }
)
noise1
```

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

### Build Template and Samplex Pair

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

Calls the `build()` function on a boxed-up circuit to construct a template and samplex pair. The resulting template is drawn to visualize its structure.

```python
template, samplex = build(circuit)

template.draw("mpl", fold=100)

```

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

### Programmatically Get Input Specifications

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

Retrieve detailed specifications for all inputs of a Samplex object using the `inputs().specs` method. This returns a list of `TensorSpecification` or similar objects, detailing name, shape, dtype, description, and optionality.

```python
samplex.inputs().specs

```

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

### Filter and Print Output Specifications by Name

Source: https://qiskit.github.io/samplomatic/guides/samplex_io.html

Use the `outputs().get_specs()` method to filter output specifications by a string pattern. This example prints the name, shape, and dtype for output specifications containing the substring "flips".

```python
for spec in samplex.outputs().get_specs("flips"):
    print(spec.name, spec.shape, spec.dtype)

```

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

### Incorporate Boxing Pass Manager into Qiskit Preset Pass Managers

Source: https://qiskit.github.io/samplomatic/_sources/guides/transpiler.ipynb.txt

Integrates `generate_boxing_pass_manager` into a Qiskit preset pass manager to transpile circuits with ISA and boxes. This example sets the boxing pass manager to run after the scheduling stage.

```python
from qiskit.transpiler import generate_preset_pass_manager

preset_pass_manager = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2]],
    optimization_level=0,
)
boxing_pass_manager = generate_boxing_pass_manager()

# Run the boxing pass manager after the scheduling stage
preset_pass_manager.post_scheduling = boxing_pass_manager

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(0, 2)
circuit.measure_all()

transpiled_circuit = preset_pass_manager.run(circuit)
transpiled_circuit.draw("mpl", scale=0.8)
```

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

### Bind inputs to Samplex interface

Source: https://qiskit.github.io/samplomatic/_sources/guides/samplex_io.ipynb.txt

Demonstrates binding inputs to the Samplex interface through multiple calls to `.bind()`. It also shows how setting optional values does not affect the `fully_bound` status.

```python
inputs = (
    samplex.inputs()
    .bind(
        pauli_lindblad_maps={
            "ref1": PauliLindbladMap.identity(2),
            "ref2": PauliLindbladMap.identity(4),
        }
    )
    .bind(parameter_values=np.linspace(0, 1, 4))
)

# once the final requirement is bound, fully_bound becomes True
print("Fully bound?", inputs.fully_bound)
inputs["basis_changes.conclude"] = [0, 2, 3]
print("Fully bound?", inputs.fully_bound)

# setting optional values does not affect whether the interface is fully bound
inputs["noise_scales.mod_ref1"] = 3
print("Fully bound?", inputs.fully_bound)
```

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

### Using Qiskit's Debugging Features

Source: https://qiskit.github.io/samplomatic/_sources/guides/debug_tracing.ipynb.txt

Demonstrates how to enable and utilize Qiskit's built-in debugging functionalities, such as setting breakpoints or inspecting circuit states during execution. This requires specific backend configurations or simulation options.

```python
from qiskit import QuantumCircuit, transpile
from qiskit.providers.fake_provider import FakeVigo

qc = QuantumCircuit(2, 2)
pc.h(0)
pc.cx(0, 1)
pc.measure([0, 1], [0, 1])

backend = FakeVigo()

tp_qc = transpile(qc, backend)

# To enable debugging, you might need to configure the simulator or backend
# For example, using Aer's qasm_simulator with noise_model or other options
# from qiskit import Aer
# simulator = Aer.get_backend('qasm_simulator')
# job = simulator.run(tp_qc, shots=1024, memory=True, **{'debug_level': 1})
# result = job.result()
# print(result.get_memory())

# Note: Actual debugging features and their activation can vary significantly
# based on the backend and Qiskit version. Consult specific backend documentation.

```

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

### Distribution.sample

Source: https://qiskit.github.io/samplomatic/_sources/api/auto/samplomatic.distributions.Distribution.rst.txt

Generates samples from the distribution. This is a core method for interacting with distribution objects.

```APIDOC
## Distribution.sample

### Description
Generates samples from the distribution. This method is essential for obtaining random variates according to the distribution's defined probability. It is a fundamental operation for any distribution object.

### Method
```
sample(self, size=None)
```

### Parameters
* **size** (int, optional) - The number of samples to generate. If None, a single sample is returned.

### Returns
* list or numpy.ndarray: A list or NumPy array containing the generated samples.
```

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

### Apply Boxing to Heisenberg Circuit via Integrated Pass Manager

Source: https://qiskit.github.io/samplomatic/guides/transpiler.html

Runs the Heisenberg circuit through a preset pass manager that has the boxing pass manager integrated as a post-scheduling step. This results in a boxed ISA circuit where barriers from the original logical circuit guide the stratification.

```python
preset_pm = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2], [2, 3], [3, 4], [4, 0]],
    optimization_level=1,
)
preset_pm.post_scheduling = generate_boxing_pass_manager()

boxed_heisenberg = preset_pm.run(heisenberg)
boxed_heisenberg.draw("mpl", scale=0.5, fold=100)

```

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

### Build Template and Samplex Circuits

Source: https://qiskit.github.io/samplomatic/guides/debug_tracing.html

Builds the template and samplex circuits from the defined QuantumCircuit. The template circuit will contain barriers with labels indicating their origin.

```python
template, samplex = build(circuit)
template.draw("mpl", fold=100)

```

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

### build

Source: https://qiskit.github.io/samplomatic/api/index.html

Builds a circuit template and samplex for the given boxed-up circuit. This function is a primary entry point for creating samplex from circuits.

```APIDOC
## build(circuit[, debug])

### Description
Build a circuit template and samplex for the given boxed-up circuit.

### Parameters
#### Path Parameters
- **circuit** (object) - Required - The input circuit to be processed.
- **debug** (bool) - Optional - Flag to enable debug mode for detailed output.

### Method
N/A (Function call)

### Endpoint
N/A (Function call)

### Request Example
```python
from samplomatic import build

# Assuming 'my_circuit' is a defined Qiskit circuit object
# result = build(my_circuit, debug=True)
```

### Response
#### Success Response
- **samplex** (object) - The generated samplex object.
- **template** (object) - The generated circuit template.

#### Response Example
```json
{
  "samplex": "<samplex_object>",
  "template": "<template_object>"
}
```
```

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

### Sample with Direct Input Mapping

Source: https://qiskit.github.io/samplomatic/api/auto/samplomatic.samplex.Samplex.html

Demonstrates an alternative way to sample from a samplex by providing a direct mapping object (dictionary) for the input values. This also samples 123 randomizations.

```python
# alternatively, we can provide any mapping object directly to specify inputs
samplex.sample(
    {"parameter_values": [0.1, 0.2]},
    num_randomizations=123,
)

```