topqad_sdk.library package

class topqad_sdk.library.CircuitLibrary[source]

The CircuitLibrary provides tools for managing quantum circuits in TopQAD services.

This class allows users to upload, retrieve, and list quantum circuits. It supports managing both example circuits and user-uploaded circuits for persistent reuse and lookup.

property example_circuits: list[Circuit]

Returns a list of example circuits.

Returns:: A list of example circuits.
Return type:: list[Circuit]

get_example_by_id(circuit_id: str) → Circuit[source]

Retrieves an example circuit by its ID.

Parameters:: circuit_id (str) – The ID of the circuit.
Returns:: The response containing circuit details.
Return type:: Circuit
Raises:: TopQADError – If the retrieval fails.

get_example_by_name(circuit_name: str) → Circuit[source]

Retrieve example circuit by its name.

Parameters:: circuit_name (str) – The name of the circuit.
Returns:: The response containing circuit details.
Return type:: Circuit
Raises:: ValueError – If no circuit with the given name is found.

get_uploaded_by_id(circuit_id: str) → Circuit[source]

Retrieves a uploaded circuit by its ID.

Parameters:: circuit_id (str) – The ID of the circuit.
Returns:: The response containing circuit details.
Return type:: Circuit
Raises:: TopQADError – If the retrieval fails.

get_uploaded_by_name(circuit_name: str) → Circuit[source]

Retrieve uploaded circuit by its name.

Parameters:: circuit_name (str) – The name of the circuit.
Returns:: The response containing circuit details.
Return type:: Circuit
Raises:: ValueError – If no circuit with the given name is found.

list_all_examples() → list[source]

Fetches and updates the list of all available example circuits.

Returns:: A list of example circuits.
Return type:: list
Raises:: TopQADError – If the request to list examples fails.

list_all_uploads() → list[source]

Fetches and updates the list of all uploaded circuits.

Returns:: A list of uploaded circuits.
Return type:: list
Raises:: TopQADError – If the request to list circuits fails.

upload(file_path: str, name: str = None, description: str = None) → UploadCircuitResponse[source]

Uploads a circuit file.

Parameters:

file_path (str) – Path to the .qasm file. The filename must only contain alpha-numeric characters, underscores (_), dashes (-), and periods (.). Other characters in the filename are not allowed. To avoid the invalid slash character (/), place files in the top level of Python’s current working directory.
name (str, optional) – Name of the circuit. Defaults to the file name without extension.
description (str, optional) – Description of the circuit.

Returns:

The response containing the uploaded circuit’s details.

Return type:

UploadCircuitResponse

Raises:

TopQADError – If the upload fails or no ID is returned.

property uploaded_circuits: list[Circuit]

Returns a list of uploaded circuits.

Deprecated since version 0.4.1: The uploaded_circuits property will be removed in v1.0.0.

Returns:: A list of uploaded circuits.
Return type:: list[Circuit]

Warning

This property uses a cached list that may not reflect the most recently-uploaded circuits from other sources, like the TopQAD Portal. Call list_all_uploads() to fetch latest circuits from the server.

class topqad_sdk.library.HardwareParameters(**kwargs)[source]

The HardwareParameters provides tools for managing hardware parameters in the QRE pipeline.

This class allows user customization via keyword arguments, supports loading configuration from a dictionary or JSON file, and can serialize the configuration into a dictionary for the QRE pipeline input.

Examples: The following example demonstrates how to load hardware parameters from different sources.

Load from a JSON string:

from topqad_sdk.library import HardwareParameters
from topqad_sdk.noiseprofiler import qre_noiseprofile

hardware_params = HardwareParameters()

# Create a hardware noise profile from a built-in preset
noise_profile_preset = qre_noiseprofile.noise_profile_from_preset(
    "physical_depolarizing_target"
)

# Load parameters from a JSON string
hardware_params.load_from_json_string(noise_profile_preset)
print(hardware_params.as_dict)

{'protocols': [...]}

Load from a JSON file:

from topqad_sdk.library import HardwareParameters

hardware_params = HardwareParameters()

# Load parameters from a JSON file
hardware_params.load_from_json_file("noise_profile_emulated.json")
print(hardware_params.as_dict)

{'protocols': [...]}

property as_dict: dict[str, Any]

Return the parameters as a dictionary.

Returns:: A dictionary representation of the current hardware parameters.
Return type:: dict[str, Any]

load_from_dict(params: dict)[source]

Override current parameters using a dictionary.

Parameters:: params (dict) – A dictionary containing hardware parameters to override the current settings.
Raises:: TopQADValueError – If the provided dictionary does not match the expected parameter names or types.

load_from_json_file(file_path: str)[source]

Override current parameters using a JSON file.

Parameters:

file_path (str) – Path to the JSON file containing hardware parameters.

Raises:

FileNotFoundError – If the specified file does not exist.
json.JSONDecodeError – If the file content is not valid JSON.
TopQADValueError – If the JSON content does not match the expected parameter names or types.

load_from_json_string(json_str: str)[source]

Override current parameters using a JSON string.

Parameters:

json_str (str) – JSON string containing hardware parameters.

Raises:

json.JSONDecodeError – If the string is not valid JSON.
TopQADValueError – If the JSON content does not match the expected parameter names or types.