Reference: QPU Class¶

QPU ¶

QPU(pre_filters=None, filters=None, post_filters=None, num_qubits=None)

Bases: BaseQPU

The QPU class serves as the interface between your quantum programs and a quantum processing unit (QPU), whether simulated or physical. It is central to the operation of the Workbench and manages resources, parameters, and filters for quantum computation.

This class facilitates the allocation and management of qubits, configuration of simulation or execution parameters, and integration with various filters to process quantum operations.

Attributes:

Name	Type	Description
`debug_check_ops`	`bool`	Flag for enabling debugging checks on operations (default is False).

Example

Creating a QPU object and configuring its parameters:

from psiqdk.workbench import QPU

# Initialize a QPU instance
qc = QPU(num_qubits=4)

# Set random seed for the simulator
qc.set_param('random_seed', 42)

# Perform quantum operations
qc.had()

Notes

A QPU object must be instantiated at the beginning of a Workbench program.
To improve efficiency during loops, prefer calling QPU.write(0) to reuse existing qubits rather than resetting or creating a new QPU object.
The QPU instance supports parameter configuration via the QPU.set_param method.

For more details, see QPU Object tutorial.

Parameters:

Name	Type	Description	Default
`pre_filters`	`list`	Filters to be applied before the main operation chain. Default is None.	`None`
`filters`	`list`	Main filters to process quantum operations. Default includes ['>>state-vector-sim>>', '>>buffer>>'].	`None`
`post_filters`	`list`	Filters to be applied after the main operation chain. Default is None.	`None`
`num_qubits`	`int or None`	Number of qubits allocated to the QPU instance.	`None`

num_qubits `property` ¶

num_qubits

qubit_highwater `property` ¶

qubit_highwater

utilized_qubit_highwater `property` ¶

utilized_qubit_highwater

witness `property` ¶

witness

all_qubits_mask `property` ¶

all_qubits_mask

Get a bitmask representing all qubits in the QPU.

This property generates a bitmask where each bit corresponds to a qubit in the QPU, with all bits set to 1. The bitmask covers all qubits from 0 to num_qubits - 1.

Returns:

Type	Description
`int`	A bitmask with all qubits set to 1 (i.e., `(1 << num_qubits) - 1`).

enable_qubit_allocation_debugging ¶

enable_qubit_allocation_debugging(enable: bool = True)

Enable/disable detection of qubit allocation/release anomalies.

If enabled, raises an error if the qubits are released without being measured or returned to the |0⟩ state first.

Parameters:

Name	Type	Description	Default
`enable`	`bool`	True to enable, False to disable.	`True`

enable_time_log ¶

enable_time_log(enabled: bool = True)

Enable/disable filter pipe time logging (required for QPU.draw_timing_diagram()).

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	True to enable, False to disable.	`True`

reset ¶

reset(num_qubits, num_block_qubits=0, max_ram_size_gb=0, max_num_threads=0, randomized=False, use_opencl=False, _async=True, verbose=False)

Set the number of qubits and initialize the QPU.

This method resets the QPU, setting the number of qubits and initializing the state. It also configures parameters for simulation such as memory usage, threading, and randomization.

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	The number of qubits to request. For simulations, the required RAM size is approximately \(16 \cdot 2^n\) bytes, where \(n\) is the number of qubits. Rules of thumb: 10 qubits = 16 kB 20 qubits = 16 MB 30 qubits = 16 GB 40 qubits = 16 TB	required
`num_block_qubits`	`int`	The number of block qubits to allocate. Default is 0.	`0`
`max_ram_size_gb`	`int`	The maximum allowable RAM size for the simulation in gigabytes. This acts as a safety limit. If the number of qubits requested exceeds the allowed RAM, the request will fail. Default is 0 (no limit).	`0`
`max_num_threads`	`int`	The maximum number of threads to use for simulation. Default is 0 (automatically determined based on system capabilities).	`0`
`randomized`	`bool`	If True, randomize the initial state of the QPU. Note that for large QPUs (more than 32 qubits), this may take a significant amount of time. Default is False.	`False`
`use_opencl`	`bool`	If True, enable OpenCL for acceleration. Default is False.	`False`
`_async`	`bool`	Whether to initialize the QPU asynchronously. Default is True.	`True`
`verbose`	`bool`	If True, enable verbose logging during initialization. Default is False.	`False`

Raises:

Type	Description
`RuntimeError`	If `num_qubits` is not provided or set to zero.

Note

For QPU simulations, ensure your system has sufficient RAM to handle the requested number of qubits.

Example

Resetting a QPU with 10 qubits:

from psiqdk.workbench import QPU

qc = QPU()
qc.reset(10)

metrics ¶

metrics(metric_names=None, *, symbolic_metrics: bool | None = None, cost_functions: list[Callable[[WitnessCounter, dict, dict], dict]] | None = None, aggregate_functions: list[Callable[[dict], dict]] | None = None, expanded_costs: bool = False, filters: list[str | OpFilter] | None = None, verbose: bool | None = None) -> dict[str, int | float]

Returns a dictionary containing the numerical costs for the QPU program.

Parameters:

Name	Type	Description	Default
`metric_names`	`deprecated`	Formally used to specify which metrics to return. DEPRECATED AND TO BE REMOVED IN WB 5.0.0.	`None`
`symbolic_metrics`	`deprecated`	Whether to use an expanded format for returned costs. DEPRECATED AND TO BE REMOVED IN WB 5.0.0 - USE `expanded_costs` INSTEAD FOR BACKWARDS-COMPATIBLE BEHAVIOR.	`None`
`cost_functions`	`list[Callable[[WitnessCounter, dict, dict], dict]] \| None`	Functions that act on a `WitnessCounter` object and derive costs from the witnessed QPU ops.	`None`
`aggregate_functions`	`list[Callable[[dict], dict]] \| None`	Functions that act on a dictionary of costs and produce second order costs (e.g. "aggregated_measurements", which is the sum of `qc.read` and `qc.ppm` ops).	`None`
`expanded_costs`	`bool`	Whether to return a simplified set of costs ( `"t_count", "toffoli_count", "rotation_count", "clifford_count"`, "rotation_count", "measurement_count", "total_num_ops"`and`"active_volume"`) or to return the full set of costs calculated. Defaults to`False`, corresponding to the simplified costs.	`False`
`filters`	`list[str \| OpFilter] \| None`	Filters to use to decompose non-countable ops (such as 5-controlled Toffolis for example). Defaults to `None`.	`None`
`verbose`	`bool \| None`	Whether to print out debugging info when calling the function. Defaults to `False`.	`None`

metrics_stack ¶

metrics_stack(*, cost_functions: list[Callable[[WitnessCounter, dict, dict], dict]] | None = None, aggregate_functions: list[Callable[[dict], dict]] | None = None, expanded_costs: bool = False, filters: list[str | OpFilter] | None = None, verbose: bool | None = None) -> dict[str, int | float]

Returns a dictionary containing the numerical costs for the QPU program.

Parameters:

Name	Type	Description	Default
`cost_functions`	`list[Callable[[WitnessCounter, dict, dict], dict]] \| None`	Functions that act on a `WitnessCounter` object and derive costs from the witnessed QPU ops.	`None`
`aggregate_functions`	`list[Callable[[dict], dict]] \| None`	Functions that act on a dictionary of costs and produce second order costs (e.g. "aggregated_measurements", which is the sum of `qc.read` and `qc.ppm` ops).	`None`
`expanded_costs`	`bool`	Whether to return a simplified set of costs ( `"t_count", "toffoli_count", "rotation_count", "clifford_count"`, "rotation_count", "measurement_count", "total_num_ops"`and`"active_volume"`) or to return the full set of costs calculated. Defaults to`False`, corresponding to the simplified costs.	`False`
`filters`	`list[str \| OpFilter] \| None`	Filters to use to decompose non-countable ops (such as 5-controlled Toffolis for example). Defaults to `None`.	`None`
`verbose`	`bool \| None`	Whether to print out debugging info when calling the function. Defaults to `False`.	`None`

flush ¶

flush(until_flag_resolved=None)

Stall until all QPU instructions have finished executing. Any filters with buffer windows must empty them.

Stalling is slow, and typically only used for test and debugging.

Parameters:

Name	Type	Description	Default
`until_flag_resolved`	`int`	If not None, just flush until the QPU evaluates the given flag.	`None`

connect ¶

connect(address, port, timeout=60.0 * 30.0)

Connect to a remote filter pipeline, if a >>connect>> filter is in the pipeline.

Parameters:

Name	Type	Description	Default
`address`	`int`	The address of the remote (use 0.0.0.0 or localhost for local).	required
`port`	`int`	The port to connect to (the one the remote is listening on).	required
`timeout`	`float`	Time in seconds to wait for responses (connections, status, measurements, etc) before giving up.	`60.0 * 30.0`

disconnect ¶

disconnect()

Disconnect from a remote filter pipeline.

get_status ¶

get_status(filters=None)

Get some info from the stream components.

Parameters:

Name	Type	Description	Default
`filters`	`list of str, or None`	If not empty, only return results from specified handlers.	`None`

get_filter_by_name ¶

get_filter_by_name(name, first_only=True)

Get the named filter from the chain.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the filter to find.	required
`first_only`	`bool`	Whether to fetch the first handler in the chain if True, or a list of all matching handlers if False.	`True`

Returns:

Type	Description
`OpFilter or list of OpFilter or None`	The handler instance or list of instances if found, otherwise None.

get_filters_of_type ¶

get_filters_of_type(filter_type)

Get all filters of a specific type from the chain.

Parameters:

Name	Type	Description	Default
`filter_type`	`type`	The type of filters to find.	required

get_param ¶

get_param(param_name)

Get a parameter from the QPU.

Built-in params:

'random_seed' (int): Seed for random operations.

set_param ¶

set_param(param_name, param_value)

Set a parameter on the QPU.

Built-in params:

'random_seed' (int): Seed for random operations.

random_seed ¶

random_seed(seed: int)

Set the random seed of the QPU.

Same as set_param('random_seed', seed). Used for simulation only.

Parameters:

Name	Type	Description	Default
`seed`	`int`	The seed to use for the random number generator.	required

label ¶

label(label: str = '')

Apply a label to any subsequent ops.

Parameters:

Name	Type	Description	Default
`label`	`str`	The label to apply, or '' or None to un-apply (clear) the label.	`''`

box ¶

box(box_label='', target_mask=~0, condition_mask=0, cond_xor_mask=0, if_flag=0, taddr=0, caddr=0, cs_key=0)

High-level function box, like a label, but with target and condition qubits. Two identical box calls will cause a box to be drawn between them.

Parameters:

Name	Type	Description	Default
`box_label`	`str`	The label to apply.	`''`
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`condition_mask`	`qubit mask`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Inputs are the same as target_mask. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

error ¶

error(label='', target_mask=~0, if_flag=0, taddr=0, caddr=0)

If this instruction is executed by a backend filter, raise an error.

Parameters:

Name	Type	Description	Default
`label`	`str`	The error message.	`''`
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

box_open ¶

box_open(box_label='', target_mask=~0, condition_mask=0, cond_xor_mask=0, if_flag=0, taddr=0, caddr=0, cs_key=0)

High-level function box, like a label, but with target and condition qubits. Two identical box calls will cause a box to be drawn between them.

Parameters:

Name	Type	Description	Default
`box_label`	`str`	The label to apply.	`''`
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`condition_mask`	`qubit mask`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

box_close ¶

box_close(box_label='', target_mask=~0, condition_mask=0, cond_xor_mask=0, if_flag=0, taddr=0, caddr=0, cs_key=0)

High-level function box, like a label, but with target and condition qubits. Two identical box calls will cause a box to be drawn between them.

Parameters:

Name	Type	Description	Default
`box_label`	`str`	The label to apply.	`''`
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`condition_mask`	`qubit mask`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

pull_state ¶

pull_state(with_qreg_labels: bool = False, with_qreg_types: bool = True, flush: bool = True)

Pull the entire state vector into a numpy array and return it.

This does not change the state. This is used for simulation only.

Parameters:

Name	Type	Description	Default
`with_qreg_labels`	`bool`	If True, returns a two-element dictionary, with `'qregs'` element storing the tuple of labels of all allocated Qubits registers and `'amps'` element storing the dictionary of basis state labels and their amplitudes.	`False`
`with_qreg_types`	`bool`	If True, takes into account the type of Qubits registers (integer vs fixed-point and signed vs unsigned) to generate basis state labels. If False, treats all Qubits registers as unsigned integers.	`True`
`flush`	`bool`	Flush all instructions before pulling the state vector.	`True`

pull_state_specific ¶

pull_state_specific(target_qubits, normalize=True, message_list=[], flush=True)

Pull the state data into Python for a specific set of qubits.

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`flush`	`bool`	Flush all instructions before pulling the state vector	`True`

peek_read_probability ¶

peek_read_probability(value: int, target_mask: int = ~0, flush: bool = True, stop_at: float = 0.0)

Peek at the read probability of a specific value on the qubits specified by the target mask.

This function retrieves the probability of reading a specific value (bitstring) from the qubits specified by the target_mask. It does this via a non-projective inspection of the statevector and does not change the statevector. It checks if the value is within the bounds of the mask and optionally flushes the operation pipeline before retrieving the probability.

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`value`	`int`	The value (bitstring) whose read probability is to be queried.	required
`target_mask`	`int`	A bitmask indicating the target qubits to measure. Defaults to all qubits.	`~0`
`flush`	`bool`	If True, flush the pipeline before reading the probability. Defaults to True.	`True`
`stop_at`	`float`	If the probability is greater than `stop_at`, return as quickly as possible with stop_at or greater (used for zero-checking)	`0.0`

Returns:

Type	Description
`float`	The probability of reading the specified value on the target qubits, or None if no stream head is available.

Raises:

Type	Description
`ValueError`	If the `value` contains bits outside the `target_mask`.

postselect ¶

postselect(value: int, target_mask: int = ~0, flush: bool = True)

Perform a non-random postselected read of the desired value, collapsing the state appropriately. If there is no non-zero amplitude term matching the specified value, raise an exception.

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`value`	`int`	Desired "read" value of each qubit.	required
`target_mask`	`int`	If specified, which bits to "read".	`~0`
`flush`	`bool`	If True, flush all instructions before doing this. (Almost always desired.)	`True`

peek_n_biggest_terms ¶

peek_n_biggest_terms(num_terms: int, flush: bool = True)

Pull the terms and indices with the largest probabilities as a sorted list.

This does not change the state. This is used for simulation only.

Parameters:

Name	Type	Description	Default
`num_terms`	`int`	The number of terms to retrieve.	required
`flush`	`bool`	Flush all instructions before pulling the state vector.	`True`

peek_value ¶

peek_value(index: int, flush: bool = True)

Get the complex amplitude of the indicated term.

This does not change the state. This is used for simulation only.

Parameters:

Name	Type	Description	Default
`index`	`int`	The term to retrieve.	required
`flush`	`bool`	Flush all instructions before pulling the state vector.	`True`

push_state ¶

push_state(src_buffer, normalize=True, flush=True, target_qubits=0)

Push a partial or entire state vector from a numpy array.

If target_qubits is zero, the array must have the same number of terms as the state (2 ** num_qubits). If target_qubits is nonzero, the array must have the same number of terms as (2 ** number_of_qubits_being_pushed).

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`src_buffer`	`ndarray[float \| complex]`	The amplitudes of all terms to push.	required
`normalize`	`bool`	Whether to normalize the state after pushing. Defaults to True.	`True`
`flush`	`bool`	Whether to flush the filter pipeline. Defaults to True.	`True`
`target_qubits`	`int or Qubits`	Specific sub-state to push into. If zero, push the whole state.	`0`

check_state ¶

check_state(src_buffer, epsilon=1e-06, require_same_global_phase=False, max_to_print=100, flush=True)

Check to see if each term in the current state matches the passed-in state, within epsilon.

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`src_buffer`	`numpy array of float or complex`	The state to check against.	required
`epsilon`	`float`	The maximum difference to allow.	`1e-06`
`require_same_global_phase`	`bool`	If False, allow states to differ by a global phase.	`False`
`max_to_print`	`int`	Maximum number of differing terms to print before giving up.	`100`
`flush`	`bool`	If True, finish all QPU instructions before checking the state.	`True`

normalize ¶

normalize()

Normalize the current QPU state.

This is used for simulation only.

mask_to_qubits ¶

mask_to_qubits(mask, mask_xor=0)

Convert a mask into a Qubits object on the current QPU, with not-conditions if provided.

jump_fwd ¶

jump_fwd(target_id=None, condition_mask=0, cond_xor_mask=0, if_flag=0, taddr=0, caddr=0)

Issue a forward jump instruction in the QPU program. Useful for loops.

This function creates a forward jump to a specified or automatically determined target based on conditions and optional XOR masks.

Parameters:

Name	Type	Description	Default
`target_id`	`int`	The ID of the target jump. If None, the next available jump target ID is used.	`None`
`condition_mask`	`int`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

Returns:

Type	Description
`int`	The target jump ID.

jump_fwd_target ¶

jump_fwd_target(target_id=None, if_flag=0, taddr=0, caddr=0)

Mark the destination of a previously issued forward jump. Useful for loops.

This function marks the location in the QPU program to which a forward jump will jump.

Parameters:

Name	Type	Description	Default
`target_id`	`int`	The ID of the target jump. If None, the next available jump target ID is used.	`None`
`if_flag`	`int`	If nonzero, the jump target is marked only if this flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

Returns:

Type	Description
`int`	The target jump ID.

jump_back ¶

jump_back(target_id=None, condition_mask=0, cond_xor_mask=0, if_flag=0, max_num_loops=0, taddr=0, caddr=0)

Issue a backward jump instruction in the QPU program. Useful for loops.

This function creates a backward jump to a specified or automatically determined target based on conditions and optional XOR masks. It also enforces a loop count for safety.

Parameters:

Name	Type	Description	Default
`target_id`	`int`	The ID of the target jump. If None, the next available jump target ID is used.	`None`
`condition_mask`	`int`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`max_num_loops`	`int`	The maximum number of loops before the jump is invalidated.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

Raises:

Type	Description
`ValueError`	If `max_num_loops` is zero, which prevents infinite loops.

Returns:

Type	Description
`int`	The target jump ID.

jump_back_target ¶

jump_back_target(target_id=None, if_flag=0, max_num_loops=0, taddr=0, caddr=0)

Mark the destination of a previously issued backward jump. Useful for loops.

This function marks the location in the QPU program to which a backward jump will return. It also includes an optional maximum jump length.

Parameters:

Name	Type	Description	Default
`target_id`	`int`	The ID of the target jump. If None, the next available jump target ID is used.	`None`
`if_flag`	`int`	If nonzero, the jump target is marked only if this flag has been evaluated to 1.	`0`
`max_num_loops`	`int`	The maximum number of loops before the jump is invalidated.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

Returns:

Type	Description
`int`	The target jump ID.

read_async ¶

read_async(target_mask=~0, result=None, if_flag=0, set_flag=None, taddr=0, caddr=0, qint=None, target_xor=0, fallback_read=None)

Perform an asynchronous measurement (read) of the specified qubits.

This function reads the state of the qubits specified by the target mask asynchronously. The result is returned later, allowing other operations to proceed in the meantime.

Parameters:

Name	Type	Description	Default
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`result`	`any`	Deprecated; not used and will be removed in WB 5.0.0.	`None`
`if_flag`	`int`	Conditional execution flag. The read operation is performed only if this flag is set to 1.	`0`
`set_flag`	`int`	If specified, the flag index to store the measurement result.	`None`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`
`qint`	`optional`	Quantum integer to store the result of the read.	`None`
`target_xor`	`int`	Bitmask to XOR with the target qubits before reading.	`0`

Returns:

Type	Description
`AsyncReadResult`	An object that represents the result of the asynchronous read operation.

read ¶

read(target_mask=~0, result=None, if_flag=0, set_flag=None, taddr=0, caddr=0, as_index_list=False, target_xor=0, fallback_read=None)

Perform a synchronous measurement (read) of the specified qubits.

This function reads the state of the qubits specified by the target mask and returns the result immediately.

Parameters:

Name	Type	Description	Default
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`result`	`any`	Deprecated; not used and will be removed in WB 5.0.0.	`None`
`if_flag`	`int`	Conditional execution flag. The read operation is performed only if this flag is set to 1.	`0`
`set_flag`	`int`	If specified, the flag index to store the measurement result.	`None`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`
`as_index_list`	`bool`	If True, returns the measurement result as a list of indices where qubits are 1.	`False`
`target_xor`	`int`	Bitmask to XOR with the target qubits before reading.	`0`

Returns:

Type	Description
`int or list`	The measurement result as an integer or a list of qubit indices if `as_index_list` is True.

write ¶

write(value, target_mask=~0, if_flag=0, set_flag=0, taddr=0, caddr=0, typed_val=0)

Perform a write operation on the specified qubits. Uses the READ operation followed by the NOT operation.

This function writes the specified value to the target qubits.

Parameters:

Name	Type	Description	Default
`value`	`int`	The value to write to the qubits.	required
`target_mask`	`int or list or Qubits`	The qubits to write to. Defaults to all qubits.	`~0`
`if_flag`	`int`	Conditional execution flag. The write operation is performed only if this flag is set to 1.	`0`
`set_flag`	`int`	If specified, the flag index to store the result of the measurement.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`
`typed_val`	`float`	The typed value provided by the user.	`0`

pps ¶

pps(x_mask, z_mask, flush=True)

This function is equivalent to peek_ppm_probability().

Parameters:

Name	Type	Description	Default
`x_mask`	`int`	A bitmask indicating the qubits to measure in the X-basis.	required
`z_mask`	`int`	A bitmask indicating the qubits to measure in the Z-basis.	required
`flush`	`bool`	If True, flush the pipeline before reading the probabilities. Defaults to True.	`True`

Returns:

Type	Description
`float`	The probability result of the specified Pauli product measurements.

peek_ppm_probability ¶

peek_ppm_probability(x_mask, z_mask, flush=True)

Peek at the Pauli product measurement (PPM) outcome probability for specified qubits.

This function is equivalent to pps() and retrieves the probability of a Pauli product measurement on the qubits specified by the X and Z masks returning 0.

Parameters:

Name	Type	Description	Default
`x_mask`	`int`	A bitmask indicating the qubits to measure in the X-basis.	required
`z_mask`	`int`	A bitmask indicating the qubits to measure in the Z-basis.	required
`flush`	`bool`	If True, flush the pipeline before reading the probabilities. Defaults to True.	`True`

Returns:

Type	Description
`float`	The probability of the specified Pauli product measurement returning 0.

swap ¶

swap(target_mask, condition_mask=0, cond_xor_mask=0, if_flag=0, taddr=0, caddr=0)

Issue a qpu.swap() instruction (same as swap()). This instruction applies a controlled SWAP operation, exchanging the states of the two target qubits if and only if the control qubit(s) are in the |1⟩ state.

Parameters:

Name	Type	Description	Default
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	required
`condition_mask`	`qubit mask`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`
`if_flag`	`int`	If nonzero, apply this op only if the flag has been evaluated to 1.	`0`
`taddr`	`int`	Used to send extra target qubit information to the backend. Only used internally.	`0`
`caddr`	`int`	Used to send extra condition qubit information to the backend. Only used internally.	`0`

Raises:

Type	Description
`ValueError`	If fewer or more than two target qubits are specified.

reverse_bits ¶

reverse_bits(target_mask=~0, condition_mask=0, cond_xor_mask=0)

Reverse the bits of the quantum register for the given target mask.

This method reverses the order of bits in the quantum register, based on the provided target mask. It selectively swaps qubits in pairs, which can be useful for certain quantum algorithms that rely on bit-reversed indexing.

Parameters:

Name	Type	Description	Default
`target_mask`	`qubit mask`	The target qubit(s). Defaults to all qubits ~0.	`~0`
`condition_mask`	`qubit mask`	The control qubit(s). Defaults to 0 which is none.	`0`
`cond_xor_mask`	`int`	Bitmask to apply XOR with condition mask. E.g. if you want to condition on the bitfield (condition_mask \| cond_xor_mask), use this. Defaults to 0 which is none.	`0`

The function identifies bits from the target_mask that should be reversed, and swaps pairs of them in the quantum register.

print_stream_setup ¶

print_stream_setup()

Print the filters attached to the current QPU.

set_random ¶

set_random(flush=True)

Set the quantum state to a random value. if you use this in a test, you should set qc.random_seed(<some value>) beforehand to give deterministic results for pipelines.

This is used for simulation only.

Parameters:

Name	Type	Description	Default
`flush`	`bool`	If True, flush the pipe before setting the state.	`True`

finish ¶

finish()

Complete all pending operations on the QPU.

This function signals the QPU to finalize and complete any outstanding operations, ensuring that all tasks are finished.

clear_instructions ¶

clear_instructions(filter=None)

Clear instructions stored in a stream, so that it becomes empty.

Parameters:

Name	Type	Description	Default
`filter`	`OpFilter or None`	If provided, only flush from this filter down.	`None`

draw_timing_diagram ¶

draw_timing_diagram(filename=None)

Generate and draw a timing diagram for the current stream of QPU operations.

This function generates a visual timing diagram representing the execution of operations on the QPU. The diagram can be saved to a file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The path to the file where the timing diagram should be saved. If None, the diagram is displayed without saving.	`None`

put_instructions ¶

put_instructions(instructions, filters=None, remap_allocations=False)

Send instructions to the QPU, applying optional filters and remapping allocations.

This function processes and sends instructions to the QPU. It can convert instructions from trace or JSON formats, remap qubit allocations, and apply filters before sending them to the filter pipeline.

Parameters:

Name	Type	Description	Default
`instructions`	`list, dict, or str`	The instructions to send, which can be in list form, a trace dictionary, or JSON format.	required
`filters`	`list`	A list of filters to apply to the instructions before execution.	`None`
`remap_allocations`	`bool`	If True, remap the qubit allocations before sending the instructions.	`False`

Raises:

Type	Description
`AssertionError`	If the string provided for instructions is not in JSON format and cannot be converted.

draw ¶

draw(filename=None, instructions=None, filter=None, filters=None, show_qubricks=False, show_allocs=True, show_write_vals=True, format: str = 'svg')

Export enough info to create the diagram.

Parameters:

Name	Type	Description	Default
`filename`	`str or None`	Save to an SVG file with a given name.	`None`
`instructions`	`list[QPUop] or None`	The program to draw.	`None`
`filter`	`StreamHandler or None`	If instructions is None, get them from this filter.	`None`
`filters`	`list[OpFilter]`	Apply these compilation filters before drawing.	`None`
`show_qubricks`	`bool`	If True, include Qubrick boxes in the diagram.	`False`
`show_allocs`	`bool`	If True, include qubit allocation/release tags in the diagram.	`True`
`show_write_vals`	`bool`	If True, include qubit write-values in the diagram.	`True`
`format`	`str`	The desired output format (currently only 'svg' is supported).	`'svg'`

print_probabilities ¶

print_probabilities(qregs=None, line=-1, min_value_to_print=1e-10, max_num_values=1000, show_unallocated_qubits=True, show_entangled=True, with_qreg_types=True, flush=True) -> None

Prints a human-readable representation of the probabilities of the basis states of the quantum state vector.

Parameters:

Name	Type	Description	Default
`qregs`	`list of Qubits or None`	Optional list of qubit registers to display. If None, shows all allocated qubits.	`None`
`line`	`int`	Line number to print (for debugging). Default is -1.	`-1`
`min_value_to_print`	`float`	Minimum absolute amplitude value to display. Default is 1e-10.	`1e-10`
`max_num_values`	`int`	Maximum number of state vector entries to print. Default is 1000.	`1000`
`show_unallocated_qubits`	`bool`	Whether to show unallocated qubits. Default is True.	`True`
`show_entangled`	`bool`	Whether to show qubits that are not included in qregs, but are entangled with qregs, in the probabilities. Default is True.	`True`
`with_qreg_types`	`bool`	Whether to show the state vector as the actual values of the register types, or only as an integer value representation, default is True.	`True`
`flush`	`bool`	Whether to flush the operation pipeline before printing. Default is True.	`True`

print_state_vector ¶

print_state_vector(qregs=None, line=-1, min_value_to_print=1e-10, max_num_values=1000, show_unallocated_qubits=True, show_entangled=True, with_qreg_types=True, flush=True) -> None

Prints a human-readable representation of the quantum state vector.

Parameters:

Name	Type	Description	Default
`qregs`	`list of Qubits or None`	Optional list of qubit registers to display. If None, shows all allocated qubits.	`None`
`line`	`int`	Line number to print (for debugging). Default is -1.	`-1`
`min_value_to_print`	`float`	Minimum absolute amplitude value to display. Default is 1e-10.	`1e-10`
`max_num_values`	`int`	Maximum number of state vector entries to print. Default is 1000.	`1000`
`show_unallocated_qubits`	`bool`	Whether to show unallocated qubits. Default is True.	`True`
`show_entangled`	`bool`	Whether to show qubits that are not included in qregs, but are entangled with qregs, in the state vector. Default is True.	`True`
`with_qreg_types`	`bool`	Whether to show the state vector as the actual values of the register types, or only as an integer value representation, default is True.	`True`
`flush`	`bool`	Whether to flush the operation pipeline before printing. Default is True.	`True`

detect_entanglement ¶

detect_entanglement(qregs=None)

Detects whether the specified qubits are entangled.

Parameters:

Name	Type	Description	Default
`qregs`	`list of Qubits or None`	Optional list of qubit registers to check for entanglement.	`None`

Returns:

Type	Description
`dict`	Mapping of qubit register names to lists of entangled qubit register names. Each key is a qubit register name, and its value is a list of other qubit register names that are entangled with it.

Reference: QPU Class¶

QPU ¶

num_qubits property ¶

qubit_highwater property ¶

utilized_qubit_highwater property ¶

witness property ¶

all_qubits_mask property ¶

enable_qubit_allocation_debugging ¶

enable_time_log ¶

reset ¶

metrics ¶

metrics_stack ¶

flush ¶

connect ¶

disconnect ¶

get_status ¶

get_filter_by_name ¶

get_filters_of_type ¶

get_param ¶

set_param ¶

random_seed ¶

label ¶

box ¶

error ¶

box_open ¶

box_close ¶

pull_state ¶

pull_state_specific ¶

peek_read_probability ¶

postselect ¶

peek_n_biggest_terms ¶

peek_value ¶

push_state ¶

check_state ¶

normalize ¶

mask_to_qubits ¶

jump_fwd ¶

jump_fwd_target ¶

jump_back ¶

jump_back_target ¶

read_async ¶

read ¶

write ¶

pps ¶

peek_ppm_probability ¶

swap ¶

reverse_bits ¶

print_stream_setup ¶

set_random ¶

finish ¶

clear_instructions ¶

draw_timing_diagram ¶

put_instructions ¶

draw ¶

print_probabilities ¶

print_state_vector ¶

detect_entanglement ¶

num_qubits `property` ¶

qubit_highwater `property` ¶

utilized_qubit_highwater `property` ¶

witness `property` ¶

all_qubits_mask `property` ¶