mqt.debugger

A module for interfacing with the mqt-debugger library.

class CompilationSettings

The settings that should be used to compile an assertion program.

property opt

The optimization level that should be used. Exact meaning depends on the implementation, but typically 0 means no optimization.

property slice_index

The index of the slice that should be compiled.

class Complex

Represents a complex number.

property imaginary

The imaginary part of the complex number.

property real

The real part of the complex number.

class Diagnostics

Provides diagnostics capabilities such as different analysis methods for the debugger.

get_data_dependencies(self: Diagnostics, instruction: SupportsInt | SupportsIndex, include_callers: bool = False) → list[int]

Extract all data dependencies for a given instruction.

If the instruction is inside a custom gate definition, the data dependencies will by default not go outside of the custom gate, unless a new call instruction is found. By setting include_callers to True, all possible callers of the custom gate will also be included and further dependencies outside the custom gate will be taken from there.

The line itself will also be counted as a dependency. Gate and register declarations will not.

This method can be performed without running the program, as it is a static analysis method.

Parameters:

• instruction (int) – The instruction to extract the data dependencies for.

• include_callers (bool, optional) – True, if the data dependencies should include all possible callers of the containing custom gate. Defaults to False.

Returns:

A list of instruction indices that are data dependencies of the given instruction.

Return type:

list[int]

get_instruction_count(self: Diagnostics) → int

Get the number of instructions in the code.

Returns:

The number of instructions in the code.

Return type:

int

get_interactions(self: Diagnostics, arg0: SupportsInt | SupportsIndex, arg1: SupportsInt | SupportsIndex) → list[int]

Extract all qubits that interact with a given qubit up to a specific instruction.

If the target instruction is inside a custom gate definition, the interactions will only be searched inside the custom gate, unless a new call instruction is found.

The qubit itself will also be counted as an interaction.

This method can be performed without running the program, as it is a static analysis method.

Parameters:

• before_instruction (int) – The instruction to extract the interactions up to (excluding).

• qubit (int) – The qubit to extract the interactions for.

Returns:

A list of qubit indices that interact with the given qubit up to the target instruction.

Return type:

list[int]

get_num_qubits(self: Diagnostics) → int

Get the number of qubits in the system.

Returns:

The number of qubits in the system.

Return type:

int

get_zero_control_instructions(self: Diagnostics) → list[int]

Extract all controlled gates that have been marked as only having controls with value zero.

This method expects a continuous memory block of booleans with size equal to the number of instructions. Each element represents an instruction and will be set to true if the instruction is a controlled gate with only zero controls.

This method can only be performed at runtime, as it is a dynamic analysis method.

Returns:

The indices of instructions that are controlled gates with only zero controls.

Return type:

list[int]

init(self: Diagnostics) → None

Initializes the diagnostics instance.

potential_error_causes(self: Diagnostics) → list[ErrorCause]

Extract a list of potential error causes encountered during execution.

This method should be run after the program has been executed and reached an assertion error.

Returns:

A list of potential error causes encountered during execution.

Return type:

list[ErrorCause]

suggest_assertion_movements(self: Diagnostics) → list[tuple[int, int]]

Suggest movements of assertions to better positions.

Each entry of the resulting list consists of the original position of the assertion, followed by its new suggested position.

Returns:

A list of moved assertions.

Return type:

list[tuple[int, int]]

suggest_new_assertions(self: Diagnostics) → list[tuple[int, str]]

Suggest new assertions to be added to the program.

Each entry of the resulting list consists of the suggested position for the new assertion, followed by its string representation.

Returns:

A list of new assertions.

Return type:

list[tuple[int, str]]

class ErrorCause

Represents a potential cause of an assertion error.

property instruction

The instruction where the error may originate from or where the error can be detected.

property type

The type of the potential error cause.

class ErrorCauseType(*values)

The type of a potential error cause.

ControlAlwaysZero = 2

MissingInteraction = 1

Unknown = 0

class SimulationState

Represents the state of a quantum simulation for debugging.

“This is the main class of the mqt-debugger library, allowing developers to step through the code and inspect the state of the simulation.

can_step_backward(self: SimulationState) → bool

Indicates whether the simulation can step backward.

The simulation is unable to step backward if it is at the beginning or if the simulation has not been set up yet.

Returns: bool: True, if the simulation can step backward.

can_step_forward(self: SimulationState) → bool

Indicates whether the simulation can step forward.

The simulation is unable to step forward if it has finished or if the simulation has not been set up yet.

Returns: bool: True, if the simulation can step forward.

clear_breakpoints(self: SimulationState) → None

Clears all breakpoints set in the simulation.

compile(self: SimulationState, arg0: CompilationSettings) → str

Compiles the given code into a quantum circuit without assertions.

Parameters:

settings (CompilationSettings) – The settings to use for the compilation.

Returns:

The compiled code.

Return type:

str

did_assertion_fail(self: SimulationState) → bool

Indicates whether an assertion has failed in the previous step.

If execution is continued after a failed assertion, then this flag will be set to false again.

Returns: bool: True, if an assertion failed during the last step.

get_amplitude_bitstring(self: SimulationState, arg0: str) → Complex

Gets the complex amplitude of a state in the full state vector.

The amplitude is selected by a bitstring representing the state.

Parameters:

bitstring (str) – The index of the state as a bitstring.

Returns:

The complex amplitude of the state.

Return type:

Complex

get_amplitude_index(self: SimulationState, arg0: SupportsInt | SupportsIndex) → Complex

Gets the complex amplitude of a state in the full state vector.

The amplitude is selected by an integer index that corresponds to the binary representation of the state.

Parameters:

index (int) – The index of the state in the full state vector.

Returns:

The complex amplitude of the state.

Return type:

Complex

get_classical_variable(self: SimulationState, arg0: str) → Variable

Gets a classical variable by name.

For registers, the name should be the register name followed by the index in square brackets.

Parameters:

name (str) – The name of the variable.

Returns:

The fetched variable.

Return type:

Variable

get_classical_variable_name(self: SimulationState, arg0: SupportsInt | SupportsIndex) → str

Gets the name of a classical variable by its index.

For registers, each index is counted as a separate variable and can be accessed separately. This method will return the name of the specific index of the register.

Parameters:

index (int) – The index of the variable.

Returns:

The name of the variable.

Return type:

str

get_current_instruction(self: SimulationState) → int

Gets the current instruction index.

Returns: int: The index of the current instruction.

get_diagnostics(self: SimulationState) → Diagnostics

Gets the diagnostics instance employed by this debugger.

Returns:

The diagnostics instance employed by this debugger.

Return type:

Diagnostics

get_instruction_count(self: SimulationState) → int

Gets the number of instructions in the code.

Returns:

The number of instructions in the code.

Return type:

int

get_instruction_position(self: SimulationState, arg0: SupportsInt | SupportsIndex) → tuple[int, int]

Gets the position of the given instruction in the code.

Start and end positions are inclusive and white-spaces are ignored.

Parameters:

instruction (int) – The instruction to find.

Returns:

The start and end positions of the instruction.

Return type:

tuple[int, int]

get_num_classical_variables(self: SimulationState) → int

Gets the number of classical variables in the simulation.

For registers, each index is counted as a separate variable.

Returns:

The number of classical variables in the simulation.

Return type:

int

get_num_qubits(self: SimulationState) → int

Gets the number of qubits used by the program.

Returns:

The number of qubits used by the program.

Return type:

int

get_quantum_variable_name(self: SimulationState, arg0: SupportsInt | SupportsIndex) → str

Gets the name of a quantum variable by its index.

For registers, each index is counted as a separate variable and can be accessed separately. This method will return the name of the specific index of the register.

Parameters:

index (int) – The index of the variable.

Returns:

The name of the variable.

Return type:

str

get_stack_depth(self: SimulationState) → int

Gets the current stack depth of the simulation.

Each custom gate call corresponds to one stack entry.

Returns:

The current stack depth of the simulation.

Return type:

int

get_stack_trace(self: SimulationState, arg0: SupportsInt | SupportsIndex) → list[int]

Gets the current stack trace of the simulation.

The stack trace is represented as a list of instruction indices. Each instruction index represents a single return address for the corresponding stack entry.

Parameters:

max_depth (int) – The maximum depth of the stack trace.

Returns:

The stack trace of the simulation.

Return type:

list[int]

get_state_vector_full(self: SimulationState) → Statevector

Gets the full state vector of the simulation at the current time.

The state vector is expected to be initialized with the correct number of qubits and allocated space for the amplitudes before calling this method.

Returns:

The full state vector of the current simulation state.

Return type:

Statevector

get_state_vector_sub(self: SimulationState, arg0: Sequence[SupportsInt | SupportsIndex]) → Statevector

Gets a sub-state of the state vector of the simulation at the current time.

The state vector is expected to be initialized with the correct number of qubits and allocated space for the amplitudes before calling this method.

This method also supports the re-ordering of qubits, but does not allow qubits to be repeated.

Parameters:

qubits (list[int]) – The qubits to include in the sub-state.

Returns:

The sub-state vector of the current simulation state.

Return type:

Statevector

init(self: SimulationState) → None

Initializes the simulation state.

is_finished(self: SimulationState) → bool

Indicates whether the execution has finished.

The execution is considered finished if it has reached the end of the code.

Returns: bool: True, if the execution has finished.

load_code(self: SimulationState, arg0: str) → None

Loads the given code into the simulation state.

Parameters:

code (str) – The code to load.

pause_simulation(self: SimulationState) → None

Pauses the simulation.

If the simulation is running in a concurrent thread, the execution will stop as soon as possible, but it is not guaranteed to stop immediately.

If the simulation is not running, then the next call to continue the simulation will stop as soon as possible. step over and step out methods, in particular, may still execute the next instruction.

reset_simulation(self: SimulationState) → None

Resets the simulation to the initial state.

This will reset measured variables and state vectors and go back to the start of the code.

run_all(self: SimulationState) → int

Runs the simulation until it finishes, even if assertions fail.

Returns: int: The number of assertions that failed during execution.

run_simulation(self: SimulationState) → None

Runs the simulation until it finishes or an assertion fails.

If an assertion fails, the simulation stops and the did_assertion_fail method will return True.

run_simulation_backward(self: SimulationState) → None

Runs the simulation backward until it finishes or an assertion fails.

set_breakpoint(self: SimulationState, arg0: SupportsInt | SupportsIndex) → int

Sets a breakpoint at the desired position in the code.

The position is given as a 0-indexed character position in the full code string.

Parameters:

desired_position (int) – The position in the code to set the breakpoint.

Returns:

The index of the instruction where the breakpoint was set.

Return type:

int

step_backward(self: SimulationState) → None

Steps the simulation backward by one instruction.

step_forward(self: SimulationState) → None

Steps the simulation forward by one instruction.

step_out_backward(self: SimulationState) → None

Steps the simulation backward until the instruction calling the current custom gate is encountered.

step_out_forward(self: SimulationState) → None

Steps the simulation forward until the current custom gate call returns.

step_over_backward(self: SimulationState) → None

Steps the simulation backward by one instruction, skipping over possible custom gate calls.

step_over_forward(self: SimulationState) → None

Steps the simulation forward by one instruction, skipping over possible custom gate calls.

was_breakpoint_hit(self: SimulationState) → bool

Indicates whether a breakpoint was hit in the previous step.

If execution is continued after a breakpoint, then this flag will be set to false again.

Returns: bool: True, if a breakpoint was hit during the last step.

class Statevector

Represents a state vector.

property amplitudes

The amplitudes of the state vector.

Contains one element for each of the num_states states in the state vector.

property num_qubits

The number of qubits in the state vector.

property num_states

The number of states in the state vector.

This is always equal to 2^`num_qubits`.

class Variable

Represents a classical variable.

property name

The name of the variable.

property type

The type of the variable.

property value

The value of the variable.

class VariableType(*values)

The type of a classical variable.

VarBool = 0

VarFloat = 2

VarInt = 1

class VariableValue

Represents the value of a classical variable.

Only one of these fields has a valid value at a time, based on the variable’s VariableType.

property bool_value

The value of a boolean variable.

property float_value

The value of a floating-point variable.

property int_value

The value of an integer variable.

create_ddsim_simulation_state() → SimulationState

Creates a new SimulationState instance using the DD backend for simulation and the OpenQASM language as input format.

Returns:

The created simulation state.

Return type:

SimulationState

destroy_ddsim_simulation_state(arg0: SimulationState) → None

Delete a given DD-based SimulationState instance and free up resources.

Parameters:

state (SimulationState) – The simulation state to delete.