Quantum Machine Manager API¶

qm.quantum_machines_manager.QuantumMachinesManager ¶

QuantumMachinesManager(
    host: Optional[str] = None,
    port: Optional[int] = None,
    *,
    cluster_name: Optional[str] = None,
    timeout: Optional[float] = None,
    log_level: Union[int, str] = logging.INFO,
    connection_headers: Optional[Dict[str, str]] = None,
    add_debug_data: bool = False,
    credentials: Optional[SSLContext] = None,
    store: Optional[BaseStore] = None,
    file_store_root: Optional[str] = None,
    octave: Optional[QmOctaveConfig] = None,
    octave_calibration_db_path: Optional[
        Union[PathLike, AbstractCalibrationDB]
    ] = None,
    follow_gateway_redirections: bool = True,
    async_follow_redirects: bool = False,
    async_trust_env: bool = True
)

PARAMETER	DESCRIPTION
`host`	Host where to find the QM orchestrator. If `None`, local settings are used. TYPE: `string` DEFAULT: `None`
`port`	Port where to find the QM orchestrator. If None, local settings are used. TYPE: `Optional[int]` DEFAULT: `None`
`cluster_name`	The name of the cluster. Requires redirection between devices. TYPE: `string` DEFAULT: `None`
`timeout`	The timeout, in seconds, for detecting the qmm and most other gateway API calls. Default is 60. TYPE: `float` DEFAULT: `None`
`log_level`	The logging level for the connection instance. Defaults to `INFO`. Please check `logging` for available options. TYPE: `Union[int, string]` DEFAULT: `INFO`
`octave`	The configuration for the Octave devices. Deprecated from QOP 2.4.0. TYPE: `QmOctaveConfig` DEFAULT: `None`
`octave_calibration_db_path`	The path for storing the Octave's calibration database. It can also be a calibration database which is an instance of `AbstractCalibrationDB`. TYPE: `PathLike` DEFAULT: `None`
`follow_gateway_redirections`	If True (default), the client will follow redirections to find a QuantumMachinesManager and Octaves. Otherwise, it will only connect to the given host and port. TYPE: `bool` DEFAULT: `True`
`async_follow_redirects`	If False (default), async httpx will not follow redirections, relevant only in case follow_gateway_redirections is True. TYPE: `bool` DEFAULT: `False`
`async_trust_env`	If True (default), async httpx will read the environment variables for settings as proxy settings, relevant only in case follow_gateway_redirections is True. TYPE: `bool` DEFAULT: `True`

clear_all_job_results ¶

clear_all_job_results() -> None

Deletes all data from all previous jobs

close ¶

close() -> None

Tear down the gRPC channel and release its network resources.

Without close(), the channel is pinned to the process until interpreter shutdown — accumulating one open connection per QMM instance in long-running sessions (e.g. Jupyter kernels).

Idempotent: subsequent calls are no-ops. After close() any RPC method on this instance raises QMConnectionError.

close_all_qms ¶

close_all_qms() -> None

Closes ALL open quantum machines

get_controllers ¶

get_controllers() -> List[ControllerBase]

Returns a list of all the controllers that are available

get_job ¶

get_job(job_id: str) -> JobApi

-- Available in QOP 3.x --

Get a job based on the job_id.

PARAMETER	DESCRIPTION
`job_id`	A list of jobs ids TYPE: `str`

RETURNS	DESCRIPTION
`JobApi`	The job

get_job_result_handles ¶

get_job_result_handles(job_id: str) -> StreamsManager

-- Available in QOP 2.x --

Returns the result handles for a job.

PARAMETER	DESCRIPTION
`job_id`	The job id TYPE: `str`

RETURNS	DESCRIPTION
`StreamsManager`	The handles that this job generated

get_jobs ¶

get_jobs(
    qm_ids: Iterable[str] = tuple(),
    job_ids: Iterable[str] = tuple(),
    user_ids: Iterable[str] = tuple(),
    description: str = "",
    status: Iterable[JobStatus] = tuple(),
) -> List[JobData]

-- Available in QOP 3.x --

Get jobs based on filtering criteria. All fields are optional.

PARAMETER	DESCRIPTION
`qm_ids`	A list of qm ids TYPE: `Iterable[str]` DEFAULT: `tuple()`
`job_ids`	A list of jobs ids TYPE: `Iterable[str]` DEFAULT: `tuple()`
`user_ids`	A list of user ids TYPE: `Iterable[str]` DEFAULT: `tuple()`
`description`	Jobs' description TYPE: `str` DEFAULT: `''`
`status`	A list of job statuses TYPE: `Iterable[JobStatus]` DEFAULT: `tuple()`

RETURNS	DESCRIPTION
`List[JobData]`	A list of jobs

get_qm ¶

get_qm(machine_id: str) -> Union[QuantumMachine, QmApi]

Gets an open quantum machine object with the given machine id

PARAMETER	DESCRIPTION
`machine_id`	The id of the open quantum machine to get TYPE: `str`

RETURNS	DESCRIPTION
`Union[QuantumMachine, QmApi]`	A quantum machine obj that can be used to execute programs

list_open_qms ¶

list_open_qms() -> List[str]

Return a list of open quantum machines. (Returns only the ids, use get_qm(...) to get the machine object)

RETURNS	DESCRIPTION
`List[str]`	The ids list

open_qm ¶

open_qm(
    config: Union[FullQuaConfig, ControllerQuaConfig],
    close_other_machines: Optional[bool] = None,
    validate_with_protobuf: bool = False,
    add_calibration_elements_to_config: bool = True,
    use_calibration_data: bool = True,
    keep_dc_offsets_when_closing: bool = False,
    **kwargs: Any
) -> Union[QuantumMachine, QmApi]

Opens a new quantum machine. A quantum machine can use multiple OPXes, and a single OPX can also be used by multiple quantum machines as long as they do not share the same physical resources (input/output ports) as defined in the config.

-- Available from QOP 3.5 -- The configuration is split into two: controller config and logical config. When opening a QuantumMachine, the physical configuration defines the physical resources (e.g., ports), idle values (e.g., DC offsets), and port configurations. A full configuration (containing both logical and controller configs) can also be supplied, which will be used as the program's default. See the documentation website for more information.

PARAMETER	DESCRIPTION
`config`	The config that will be used by the Quantum Machine TYPE: `Union[FullQuaConfig, ControllerQuaConfig]`
`close_other_machines`	When set to true, any open quantum machine that uses resources required for the opening of the new quantum machine will be closed. This simplifies the workflow but might result in unintended closure of quantun machines. The default `None` behavior is currently the same as `True`. TYPE: `Optional[bool]` DEFAULT: `None`
`validate_with_protobuf`	Validates config with protobuf instead of marshmallow. It is usually faster when working with large configs. Defaults to False. TYPE: `bool` DEFAULT: `False`
`add_calibration_elements_to_config`	Automatically adds config entries to allow Octave calibration. TYPE: `bool` DEFAULT: `True`
`use_calibration_data`	Automatically load updated calibration data from the calibration database into the config. TYPE: `bool` DEFAULT: `True`
`keep_dc_offsets_when_closing`	Available in QOP 2.4.2 - When closing the QM, do not change the DC offsets. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Union[QuantumMachine, QmApi]`	A quantum machine obj that can be used to execute programs

open_qm_from_file ¶

open_qm_from_file(
    filename: str, close_other_machines: bool = True
) -> Union[QuantumMachine, QmApi]

Opens a new quantum machine with config taken from a file on the local file system

PARAMETER	DESCRIPTION
`filename`	The path to the file that contains the config TYPE: `str`
`close_other_machines`	Flag whether to close all other running machines TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`Union[QuantumMachine, QmApi]`	A quantum machine obj that can be used to execute programs

perform_healthcheck ¶

perform_healthcheck(strict: bool = True) -> None

Perform a health check against the QM server.

PARAMETER	DESCRIPTION
`strict`	Will raise an exception if health check failed TYPE: `bool` DEFAULT: `True`

reset_data_processing ¶

reset_data_processing() -> None

Stops current data processing for all running jobs.

Warning

Resetting the data processing is a disruptive operation. It should be used only as a recovery measure when the system becomes unresponsive due to heavy data processing, and is not intended for routine use.

set_capabilities_offline `staticmethod` ¶

set_capabilities_offline(
    capabilities: Optional[
        Union[Collection[Capability], ServerCapabilities]
    ] = None,
) -> None

Some modules of the sdk cannot be run without the capabilities of the QOP server, which is automatically set when connecting to the server via QuantumMachinesManager (in "_initialize_connection"). This function provides an alternative to connecting to a QOP server via QuantumMachinesManager, by setting the capabilities manually and globally.

It is possible to extract the capabilities of an existing QuantumMachinesManager object by checking the capabilities attribute, e.g. qmm = QuantumMachinesManager(); capabilities = qmm.capabilities.

The QopCaps class (from qm import QopCaps) can be used to get and view all capabilities.

Warning: Setting the capabilities when there is an open QuantumMachinesManager will override them and can cause unexpected behavior.

PARAMETER	DESCRIPTION
`capabilities`	A set of capabilities (or a ServerCapabilities object) to create the container with. If None, all capabilities are set. Warning: Using all capabilities might not produce the expected behavior. TYPE: `Optional[Union[Collection[Capability], ServerCapabilities]]` DEFAULT: `None`

simulate ¶

simulate(
    config: FullQuaConfig,
    program: Program,
    simulate: SimulationConfig,
    compiler_options: Optional[
        CompilerOptionArguments
    ] = None,
    *,
    strict: Optional[bool] = None,
    flags: Optional[List[str]] = None
) -> Union[SimulatedJob, SimulatedJobApi]

Simulate the outputs of a deterministic QUA program.

The following example shows a simple execution of the simulator, where the associated config object is omitted for brevity.

Example

from qm.qua import *
from qm import SimulationConfig, QuantumMachinesManager

qmm = QuantumMachinesManager()

with program() as prog:
    play('pulse1', 'qe1')

job = qmm.simulate(config, prog, SimulationConfig(duration=100))

PARAMETER	DESCRIPTION
`config`	The full QUA configuration used to simulate the program, containing both the controller and logical configurations. TYPE: `FullQuaConfig`
`program`	A QUA `program()` object to execute TYPE: `Program`
`simulate`	A `SimulationConfig` configuration object TYPE: `SimulationConfig`
`compiler_options`	additional parameters to pass to execute TYPE: `Optional[CompilerOptionArguments]` DEFAULT: `None`
`strict`	a deprecated option for the compiler TYPE: `Optional[bool]` DEFAULT: `None`
`flags`	deprecated way to provide flags to the compiler TYPE: `Optional[List[str]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Union[SimulatedJob, SimulatedJobApi]`	a `QmJob` object (see Job API).

validate_qua_config ¶

validate_qua_config(
    qua_config: Union[FullQuaConfig, ControllerQuaConfig],
) -> None

Validates a qua config based on the connected server's capabilities. Raises an exception if the config is invalid.

PARAMETER	DESCRIPTION
`qua_config`	A python dict containing the qua config to validate TYPE: `Union[FullQuaConfig, ControllerQuaConfig]`

version ¶

version() -> DevicesVersion

RETURNS	DESCRIPTION
`DevicesVersion`	An object with the qm-qua and QOP versions

version_dict ¶

version_dict() -> Version

RETURNS	DESCRIPTION
`Version`	A dictionary with the qm-qua and QOP versions