topqad_sdk.compiler package

class topqad_sdk.compiler.CompilationResult(response: CompilerPipelineSolutionResponse)[source]

Result of the Compilation service run.

property decomposed_circuit_path

Path to the decomposed circuit.

property num_logical_measurements

Number of logical measurements.

property num_non_clifford_operations

Number of non clifford gates.

property rotations_circuit_path

Path to the circuit decomposed into Pauli rotations.

property scheduled_output_filepath

Path to the assembled schedule file.

property sk_accumulated_error

Error induced by decomposition of gates.

property total_num_operations

Total number of gates.

class topqad_sdk.compiler.Compiler[source]

The Compiler provides an interface for TopQAD’s Compiler service.

This class provides methods to submit quantum circuits for compilation, retrieve results, and handle job cancellations. It supports both synchronous and asynchronous execution modes, making it easy to integrate into quantum workflows.

cancel() → dict[source]

Cancel a running Compiler job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

  • compiler_pipeline_id (str): The compiler pipeline ID of the request to be cancelled.

  • status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.

  • message (str): Information about the cancellation request.

Return type:

dict

Raises:

  • TopQADError – If the cancellation fails due to an internal error.

  • ValueError – If no compiler pipeline ID is found.

Examples

from topqad_sdk.library import CircuitLibrary
from topqad_sdk.compiler import Compiler

# See `CircuitLibrary` documentation for more details.
circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

compiler = Compiler()

compiler.compile(
    circuit=circuit,
    error_budget=0.01,
    async_mode=True,
)
print(compiler.cancel())

Starting compilation ...
Compiler request with compiler pipeline_id ... has been submitted. Please come back later and call get_results
Cancel request for compiler_pipeline_id ... has been submitted.
{'compiler_pipeline_id': '...', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}
compile(circuit: Circuit, error_budget: float, remove_clifford_gates: bool = False, insights_only: bool = False, async_mode: bool = False, overwrite_result: bool = False) → CompilationResult | dict[source]

Run the Compiler Pipeline.

This method supports two execution modes: Synchronous and Asynchronous.

  • Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.

  • Async Mode: The method submits the job and returns immediately with the compiler_pipeline_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

  1. Stop tracking the job (exit, job continues on server).

  2. Send a cancellation request to the server and exit.

  3. Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Parameters:

  • circuit (Circuit) – The quantum circuit to be processed.

  • error_budget (float) – Allowed synthesis error to be used.

  • remove_clifford_gates (bool) – Flag to determine whether or not to bypass the optimization stage.

  • insights_only (bool) – Flag to determine if the output of the scheduler is produced.

  • async_mode (bool) – Flag to determine whether to use async mode or not.

  • overwrite_result (bool) – Flag to overwrite existing results if they exists. Defaults to False.

Returns:

Result of the compilation run execution. Returns dict of compiler_pipeline_id and status if async_mode set to True.

Return type:

CompilationResult|dict

Raises:

  • KeyboardInterrupt – If the job is interrupted by the user.

  • ValueError – If existing results are present and overwrite_result is False.

  • TopQADTimeoutError – If polling for the Compiler job times out.

  • RuntimeError – If the Compiler job fails or polling times out.

Examples

Synchronous Mode
from topqad_sdk.library import CircuitLibrary
from topqad_sdk.compiler import Compiler

# See `CircuitLibrary` documentation for more details.
circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

compiler = Compiler()

result = compiler.compile(
    circuit=circuit,
    error_budget=0.01,
)
print(result)

Starting compilation ...
<CompilationResult>
  Decomposed circuit path: ...
  Accumulated error: ...
  Non-Clifford operations: ...
  Total operations: ...
  Rotations circuit path: ...
  Logical measurements: ...
  Scheduled output filepath: ...
Asynchronous Mode
from topqad_sdk.library import CircuitLibrary
from topqad_sdk.compiler import Compiler

# See `CircuitLibrary` documentation for more details.
circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

compiler = Compiler()

response = compiler.compile(
    circuit=circuit,
    error_budget=0.01,
    async_mode=True,
)
compiler_pipeline_id = response["compiler_pipeline_id"] # Store the job ID for later use

compiler.load(compiler_pipeline_id=compiler_pipeline_id) # Load the job later
print(compiler.get_results()) # Retrieve and display results when ready

Starting compilation ...
Compiler request with compiler pipeline_id ... has been submitted. Please come back later and call get_results
Existing results found for compiler pipeline ID ... Returning...
<CompilationResult>
  Decomposed circuit path: ...
  Accumulated error: ...
  Non-Clifford operations: ...
  Total operations: ...
  Rotations circuit path: ...
  Logical measurements: ...
  Scheduled output filepath: ...
get_results()[source]

Retrieve the Compiler results from the request if it has finished.

Returns:

Result of the compilation run execution.

Return type:

CompilationResult

load(compiler_pipeline_id)[source]

Retrieves and loads compiler pipeline information from server using given compiler_pipeline_id.

This method fetches the status and results of a previously submitted Compiler job. If the job is complete, the results are also loaded into the current instance. Any existing cached data (e.g., results, status, compiler pipeline ID) in the instance will be overwritten.

Use this method when you have a compiler_pipeline_id from a previously submitted job and want to retrieve its current status or results.

Parameters:

compiler_pipeline_id (str) – The ID of the Compiler pipeline.

Returns:

Status and compiler pipeline ID of request.

Return type:

dict

Examples

from topqad_sdk.compiler import Compiler
compiler = Compiler()

compiler_pipeline_id = "12345" # Replace with your actual compiler pipeline ID
print(compiler.load(compiler_pipeline_id))

{'compiler_pipeline_id': '12345', 'status': 'done'}