Quick Start

This page uses a Bell-state circuit to demonstrate installation, circuit construction, pure-state execution, and circuit measurement. Backend tuning, density matrices, and compilation are covered in their reference pages.

Use execute() for local simulation and execute_density(shots=..., seed=...) for mixed states and noise. Export CUDA-Q source with to_python(framework="cudaq"). Hardware submit() returns a job object, and job.result() queries it once; see the corresponding reference pages.

Installation and imports


pip install unitarylab


from unitarylab import Circuit

For supported Python versions and optional components, see the Manual Overview.

Create and execute a Bell-state circuit


import numpy as np
from unitarylab import Circuit
 
circuit = Circuit(2)
circuit.h(0)
circuit.cx(0, 1)
 
result = circuit.execute()
 
assert result.state.shape == (4,)
assert np.isclose(result.probability("00"), 0.5)
assert np.isclose(result.probability("11"), 0.5)
assert np.isclose(result.probability("01"), 0.0)
assert np.isclose(result.probability("10"), 0.0)

Circuit(2) creates two qubits and an equal-sized default classical register. h(0) and cx(0, 1) create the Bell state

\frac{∣00 ⟩ + ∣11 ⟩}{2} .

Floating-point output can differ slightly due to dtype and backend rounding, so the example uses np.isclose() to check probabilities instead of relying on fixed decimal text.

Query the state and probabilities


print(result.state)
print(result.probabilities)
print(result.marginal_probabilities(qubits=[0]))
print(result.expectation("ZZ", qubits=(0, 1)))

state is the final state vector.
probabilities is a complete computational-basis probability dictionary, including zero-probability outcomes.
Probability bit strings use little-endian ordering, with qubit 0 at the rightmost position.
expectation() returns the expectation value of the requested observable.

These queries do not change the quantum state held by the result object.

Add circuit measurements


measured = Circuit(2)
measured.h(0)
measured.cx(0, 1)
measured.measure([0, 1], [0, 1])
 
shot_result = measured.execute(shots=1000, seed=7)
 
assert set(shot_result.counts).issubset({"00", "11"})
assert sum(shot_result.counts.values()) == 1000
print(shot_result.counts)

measure([0, 1], [0, 1]) maps the two qubits to classical bits 0 and 1. The Bell state produces correlated outcomes 00 or 11, but exact counts vary because of random sampling.

shots is the number of independent executions of the complete circuit containing measurements. counts aggregates all executions; state and classical_results_map refer to the last execution. Sampling is reproducible when seed is a nonnegative integer; seed=None leaves the random seed unspecified.

Sampling without circuit measurements

Without calling Circuit.measure(), samples can be drawn from the final state distribution:


samples = result.sample(shots=10, qubits=[0, 1], seed=7)
assert set(samples).issubset({"00", "11"})

sample() does not collapse the state held by the result object. result.measure() performs a projective measurement and updates the internal state; these methods have different purposes.

Draw the circuit


text_diagram = measured.draw(output="text")
print(text_diagram)
 
measured.draw(filename="bell.png", title="Bell State")

Text output is suitable for terminals. When filename is specified, the default Matplotlib drawer saves the circuit as an image.