mqt.debugger

A module for interfacing with the mqt-debugger library.

class CompilationSettings(*args, **kwargs)

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(*args, **kwargs)

Represents a complex number.

property imaginary

The imaginary part of the complex number.

property real

The real part of the complex number.

class Diagnostics(*args, **kwargs)

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

get_data_dependencies(self, instruction: int, 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 – The instruction to extract the data dependencies for.

• include_callers – 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.

get_instruction_count(self) → int

Get the number of instructions in the code.

Returns:

The number of instructions in the code.

get_interactions(self, before_instruction: int, qubit: int) → 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 – The instruction to extract the interactions up to (excluding).

• qubit – The qubit to extract the interactions for.

Returns:

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

get_num_qubits(self) → int

Get the number of qubits in the system.

Returns:

The number of qubits in the system.

get_zero_control_instructions(self) → 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.

init(self) → None

Initializes the diagnostics instance.

potential_error_causes(self) → 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.

suggest_assertion_movements(self) → 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.

suggest_new_assertions(self) → 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.

class ErrorCause(*args, **kwargs)

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 LoadResult(*args, **kwargs)

The result of a code loading operation.

property column

The column number of the error location, or 0 if unknown.

property line

The line number of the error location, or 0 if unknown.

property message

A human-readable error message, or None if none is available.

property status

Indicates whether the load was successful and why it failed.

class LoadResultStatus(*values)

Represents the result of a code loading operation.

INTERNAL_ERROR = 2

OK = 0

PARSE_ERROR = 1

class Result(*values)

Represents the result of an operation.

ERROR = 1

OK = 0

class SimulationState(*args, **kwargs)

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) → 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:

True, if the simulation can step backward.

can_step_forward(self) → 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:

True, if the simulation can step forward.

change_amplitude_value(self, basis_state: str, value: Complex) → None

Updates the amplitude of a given computational basis state.

The basis state is provided as a bitstring whose length matches the current number of qubits. Implementations are expected to renormalize the remaining amplitudes so that the state vector stays normalized and to reject invalid bitstrings or amplitudes that violate normalization.

Parameters:

• basis_state – The bitstring identifying the basis state to update.

• value – The desired complex amplitude.

change_classical_variable_value(self, variable_name: str, new_value: object) → None

Updates the value of a classical variable.

Parameters:

• variable_name – The name of the classical variable to update.

• new_value – The desired value.

clear_breakpoints(self) → None

Clears all breakpoints set in the simulation.

compile(self, settings: CompilationSettings) → str

Compiles the given code into a quantum circuit without assertions.

Parameters:

settings – The settings to use for the compilation.

Returns:

The compiled code.

did_assertion_fail(self) → 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:

True, if an assertion failed during the last step.

get_amplitude_bitstring(self, bitstring: 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 – The index of the state as a bitstring.

Returns:

The complex amplitude of the state.

get_amplitude_index(self, index: int) → 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 – The index of the state in the full state vector.

Returns:

The complex amplitude of the state.

get_classical_variable(self, name: 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 – The name of the variable.

Returns:

The fetched variable.

get_classical_variable_name(self, index: int) → 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 – The index of the variable.

Returns:

The name of the variable.

get_current_instruction(self) → int

Gets the current instruction index.

Returns:

The index of the current instruction.

get_diagnostics(self) → Diagnostics

Gets the diagnostics instance employed by this debugger.

Returns:

The diagnostics instance employed by this debugger.

get_instruction_count(self) → int

Gets the number of instructions in the code.

Returns:

The number of instructions in the code.

get_instruction_position(self, instruction: int) → 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 – The instruction to find.

Returns:

The start and end positions of the instruction.

get_num_classical_variables(self) → 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.

get_num_qubits(self) → int

Gets the number of qubits used by the program.

Returns:

The number of qubits used by the program.

get_quantum_variable_name(self, index: int) → 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 – The index of the variable.

Returns:

The name of the variable.

get_stack_depth(self) → 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.

get_stack_trace(self, max_depth: int) → 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 – The maximum depth of the stack trace.

Returns:

The stack trace of the simulation.

get_state_vector_full(self) → Statevector

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

Returns:

The full state vector of the current simulation state.

get_state_vector_sub(self, qubits: Sequence[int]) → Statevector

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

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

Parameters:

qubits – The qubits to include in the sub-state.

Returns:

The sub-state vector of the current simulation state.

init(self) → None

Initializes the simulation state.

is_finished(self) → bool

Indicates whether the execution has finished.

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

Returns:

True, if the execution has finished.

load_code(self, code: str) → LoadResult

Loads the given code into the simulation state.

Parameters:

code – The code to load.

Returns:

The result of the load operation.

Return type:

LoadResult

pause_simulation(self) → 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) → 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) → int

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

Returns:

The number of assertions that failed during execution.

run_simulation(self) → 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) → None

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

set_breakpoint(self, desired_position: int) → 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 – The position in the code to set the breakpoint.

Returns:

The index of the instruction where the breakpoint was set.

step_backward(self) → None

Steps the simulation backward by one instruction.

step_forward(self) → None

Steps the simulation forward by one instruction.

step_out_backward(self) → None

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

step_out_forward(self) → None

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

step_over_backward(self) → None

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

step_over_forward(self) → None

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

was_breakpoint_hit(self) → 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:

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

class Statevector(*args, **kwargs)

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(*args, **kwargs)

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(*args, **kwargs)

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.