diagnostics.h

Note

As the Diagnostics interface is defined in C, “member functions” are declared as function pointers. When using the interface, these function pointers can be accessed like normal C++ methods.

Provides a C-style interface for diagnostic capabilities of the debugger.

Typedefs

typedef struct ErrorCauseStruct ErrorCause

Represents an error cause.

typedef struct DiagnosticsStruct Diagnostics

An interface representing the diagnostic capabilities of a debugger.

Enums

enum ErrorCauseType

Represents the type of an error cause.

These error causes are returned by the potentialErrorCauses function.

Values:

enumerator Unknown

Indicates that the error cause is unknown.

enumerator MissingInteraction

Indicates that an entanglement error may be caused by a missing interaction.

enumerator ControlAlwaysZero

Indicates that an error may be related to a controlled gate with a control that is always zero.

struct ErrorCauseStruct

Public Members

ErrorCauseType type

The type of the error cause.

size_t instruction

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

struct DiagnosticsStruct

Public Members

Result (*init)(Diagnostics *self)

Initializes the diagnostics interface.

Param self:

The instance to initialize.

Return:

The result of the operation.

size_t (*getNumQubits)(Diagnostics *self)

Get the number of qubits in the system.

Param self:

The diagnostics instance to query.

Return:

The number of qubits.

size_t (*getInstructionCount)(Diagnostics *self)

Get the number of instructions in the code.

Param self:

The diagnostics instance to query.

Return:

The number of instructions.

Result (*getDataDependencies)(Diagnostics *self, size_t instruction, bool includeCallers, bool *instructions)

Extract all data dependencies for a given instruction.

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 data dependency.

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

includeCallers

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.

Param self:

The diagnostics instance to query.

Param instruction:

The instruction to extract the data dependencies for.

Param includeCallers:

True, if the data dependencies should include all possible callers of the containing custom gate.

Param instructions:

An array of booleans that will be set to true for each instruction that is a data dependency.

Return:

The result of the operation.

Result (*getInteractions)(Diagnostics *self, size_t beforeInstruction, size_t qubit, bool *qubitsAreInteracting)

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

This method expects a continuous memory block of booleans with size equal to the number of qubits. Each element represents a qubit and will be set to true if the qubit interacts with the given qubit.

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.

Param self:

The diagnostics instance to query.

Param beforeInstruction:

The instruction to extract the interactions up to (excluding).

Param qubit:

The qubit to extract the interactions for.

Param qubitsAreInteracting:

An array of booleans that will be set to true for each qubit that interacts with the given qubit.

Return:

The result of the operation.

Result (*getZeroControlInstructions)(Diagnostics *self, bool *instructions)

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.

Param self:

The diagnostics instance to query.

Param instructions:

An array of booleans that will be set to true for each instruction that is a controlled gate with only zero controls.

Return:

The result of the operation.

size_t (*potentialErrorCauses)(Diagnostics *self, ErrorCause *output, size_t count)

Extract a list of potential error causes encountered during execution.

Up to count error causes will be returned.

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

Param self:

The diagnostics instance to query.

Param output:

An array of error causes to be filled. It is expected to have space for at least count elements.

Param count:

The maximum number of error causes to return.

Return:

The number of error causes found.

size_t (*suggestAssertionMovements)(Diagnostics *self, size_t *originalPositions, size_t *suggestedPositions, size_t count)

Suggest movements of assertions to better positions.

.

Calling this function with a count of 0 will return the number of assertions that can be suggested.

Param self:

The diagnostics instance to query.

Param originalPositions:

An array of assertion positions to be filled. Contains the original positions of the assertions that should be moved.

Param suggestedPositions:

An array of assertion positions to be filled. Contains the suggested positions of the assertions that should be moved.

Param count:

The maximum number of assertions to suggest movements for.

Return:

The number of suggested movements.

size_t (*suggestNewAssertions)(Diagnostics *self, size_t *suggestedPositions, char **suggestedAssertions, size_t count)

Suggest new assertions to be added to the code.

These assertions are added by first observing assertions that failed during previous iterations. Therefore, the simulation must be run at least once before calling this function.

Calling this function with a

count of 0 will return the number of assertions that can be suggested.

Param self:

The diagnostics instance to query.

Param suggestedPositions:

An array of assertion positions to be filled.

Param suggestedAssertions:

An array of assertion instruction strings to be filled. Each string expects a size of up to 256 characters.

Param count:

The maximum number of assertions to suggest.

Return:

The number of suggested assertions.