API

class qiboconnection.api.API(configuration)[source]

Bases: ABC

Qilimanjaro Client API class to communicate with the Quantum Service.

Methods

`cancel_job`(job_id)	Cancels a job
`delete_calibration`(calibration_id)	Deletes a job from the database.
`delete_job`(job_id)	Deletes a job from the database.
`delete_runcard`(runcard_id)	Deletes a job from the database.
`execute`([circuit, qprogram, ...])	Send a Qibo circuit(s) to be executed on the remote service API.
`execute_and_return_results`([circuit, ...])	Executes a circuit or experiment the same way as `qiboconnection.API.execute()`.
`get_calibration`([calibration_id, ...])	Get full information of a specific calibration
`get_job`(job_id)	Get metadata, result and the correspondig Qibo circuit or Qililab experiment from a remote job execution.
`get_result`(job_id)	Get a Job result from a remote execution
`get_results`(job_ids)	Get a Job result from a remote execution
`get_runcard`([runcard_id, runcard_name])	Get full information of a specific runcard
`list_calibrations`()	List all calibrations
`list_devices`()	List all available devices
`list_jobs`([favourites])	List all jobs metadata
`list_runcards`()	List all runcards
`login`(username, api_key)	Log into QaaS using your username and api_key
`ping`()	Checks if the connection is alive and response OK when it is.
`save_calibration`(name, description, ...)	Save a calibration into the database af our servers, for it to be easily recovered when needed.
`save_runcard`(name, description, ...)	Save a runcard into the database af our servers, for it to be easily recovered when needed.
`select_device_id`(device_id)	Select a device from a given identifier
`select_device_ids`(device_ids)	Select a device from a given identifier
`set_device_to_maintenance`(device_id)	Sets a device in maintenance mode, blocking external traffic and allowing for manual manipulation.
`set_device_to_online`(device_id)	Sets a device into online mode, allowing external traffic and blocking manual manipulation. .. warning::.
`update_calibration`(calibration)	Update the info of a calibration in the database
`update_runcard`(runcard)	Update the info of a runcard in the database

Attributes

`jobs`	List all jobs launched to the API
`last_calibration`	Returns the last calibration uploaded in the current session, in case there has been one.
`last_job`	Returns the last job launched
`last_runcard`	Returns the last runcard uploaded in the current session, in case there has been one.
`user_id`	Exposes the id of the authenticated user

classmethod login(username, api_key)[source]

Log into QaaS using your username and api_key

Parameters:

username – username of your account
api_key – you access key

Returns:

Authenticated API instance

property jobs[source]

List all jobs launched to the API

Returns:: List of Jobs launched
Return type:: List[Job]

property last_job[source]

Returns the last job launched

Returns:: last Job launched
Return type:: Job

property last_runcard[source]

Returns the last runcard uploaded in the current session, in case there has been one.

Returns:: last uploaded runcard
Return type:: Runcard | None

property last_calibration[source]

Returns the last calibration uploaded in the current session, in case there has been one.

Returns:: last uploaded calibration
Return type:: Calibration | None

property user_id[source]

Exposes the id of the authenticated user

Returns:: user ir
Return type:: int
Raises:: ValueError – User does not have user_id

ping()[source]

Checks if the connection is alive and response OK when it is.

Returns:: OK when connection is alive or raise Connection Error.
Return type:: str

list_devices()[source]

List all available devices

Raises:: RemoteExecutionException – Devices could not be retrieved
Returns:: All available Devices
Return type:: Devices

select_device_id(device_id)[source]

Select a device from a given identifier

Parameters:: device_id (int) – Device identifier

select_device_ids(device_ids)[source]

Select a device from a given identifier

Parameters:: device_ids (int) – List of device identifiers

set_device_to_online(device_id)[source]

Sets a device into online mode, allowing external traffic and blocking manual manipulation. .. warning:

This method is only available for admin members.

Parameters:: device_id (int) – Device identifier

set_device_to_maintenance(device_id)[source]

Sets a device in maintenance mode, blocking external traffic and allowing for manual manipulation.

Warning

This method is only available for admin members.

Parameters:: device_id (int) – Device identifier

execute(circuit=None, qprogram=None, anneal_program_args=None, vqa=None, nshots=10, device_ids=None, device_id=None, name='-', summary='-')[source]

Send a Qibo circuit(s) to be executed on the remote service API. User should define either a circuit or an experiment. If both are provided, the function will fail.

Parameters:

circuit (Circuit or List[Circuit]) – a Qibo circuit to execute
qprogram (str) – a QProgram description, result of Qililab utils serialize(qprogram) function.
anneal_program_args (dict) – an annealing implementation. It is supposed to contain a dict with everything needed for a platform.
vqa (dict) – a Variational Quantum Algorithm, result of applications-sdk’ VQA.to_dict() method.
nshots (int) – number of times the execution is to be done.
device_ids (List[int]) – list of devices where the execution should be performed. If set, any device set
devices. (using API.select_device_id() will not be used. This will not update the selected) –
device_id (int) – id of the device your job will be executed on

Returns:

list of job ids

Return type:

List[int]

Raises:

ValueError – VQA, circuit, qprogram and anneal_program_args were provided, but execute() only takes one of them.
ValueError – Neither of circuit, vqa, qprogram or anneal_program_args were provided.

get_result(job_id)[source]

Get a Job result from a remote execution

Parameters:

job_id (int) – Job identifier

Raises:

RemoteExecutionException – Job could not be retrieved.
ValueError – Job status not supported.s
ValueError – Your job failed.

Returns:

The Job result as an Abstract State or None when it is not executed yet.

Return type:

CircuitResult | npt.NDArray | dict | None

get_results(job_ids)[source]

Get a Job result from a remote execution

Parameters:

job_ids (List[int]) – List of Job identifiers

Raises:

RemoteExecutionException – Job could not be retrieved.
ValueError – Job status not supported

Returns:

The Job result as an Abstract State or None when it is not executed yet.

Return type:

Union[CircuitResult, None]

execute_and_return_results(circuit=None, qprogram=None, nshots=10, device_ids=None, device_id=None, timeout=3600, interval=60)[source]

Executes a circuit or experiment the same way as qiboconnection.API.execute().

Parameters:

circuit (Circuit) – a Qibo circuit to execute
qprogram (str) – a QProgram description, results of Qililab’s QProgram().to_dict() function.
nshots (int) – number of times the execution is to be done.
device_ids (List[int]) – list of devices where the execution should be performed. If set, any device set using API.select_device_id() will not be used. This will not update the selected
timeout (int) – seconds passed which the function should be interrupted with an error.
interval (int) – seconds to wait between checking with the backend if the results are ready. If the task is expected to last for tens of minutes, this should be set to, at least, 60 seconds.

Raises:

RemoteExecutionException – Job could not be retrieved.
ValueError – Job status not supported
TimeoutError – timeout seconds reached

Returns:

The Job result as an Abstract State or None when it is not executed yet.

Return type:

Union[CircuitResult, None]

list_jobs(favourites=False)[source]

List all jobs metadata

Raises:: RemoteExecutionException – Devices could not be retrieved
Returns:: All Jobs
Return type:: Devices

get_job(job_id)[source]

Get metadata, result and the correspondig Qibo circuit or Qililab experiment from a remote job execution.

Parameters:

job_id (int) – Job identifier

Raises:

RemoteExecutionException – Job could not be retrieved.
ValueError – Job status not supported.
ValueError – Your job failed.

Returns:

JobData

save_runcard(name, description, runcard_dict, device_id, user_id, qililab_version)[source]

Save a runcard into the database af our servers, for it to be easily recovered when needed.

Warning

This method is only available for Qilimanjaro members.

Parameters:

name – Name the experiment is going to be saved with.
description – Short descriptive text to more easily identify this specific experiment instance.
runcard_dict – Serialized runcard (using its .to_dict() method)
device_id – Id of the device the experiment was executed in
user_id – Id of the user that is executing the experiment
qililab_version – version of qililab the experiment was executed with

Returns:

new saved runcard

get_runcard(runcard_id=None, runcard_name=None)[source]

Get full information of a specific runcard

Warning

This method is only available for Qilimanjaro members.

Parameters:

runcard_id (int, optional) – id of the runcard to retrieve. Incompatible with providing a name.
runcard_name (str, optional) – name of the runcard to retrieve. Incompatible with providing an id.

Raises:

RemoteExecutionException – Runcard could not be retrieved

Returns:

serialized runcard dictionary

Return type:

Runcard

list_runcards()[source]

List all runcards

Raises:: RemoteExecutionException – Devices could not be retrieved
Returns:: All Runcards
Return type:: Runcards

update_runcard(runcard)[source]

Update the info of a runcard in the database

Warning

This method is only available for Qilimanjaro members.

Raises:: RemoteExecutionException – Runcard could not be retrieved
Returns:: serialized runcard dictionary
Return type:: Runcard

delete_runcard(runcard_id)[source]

Deletes a job from the database.

Warning

This method is only available for Qilimanjaro members.

Raises:: RemoteExecutionException – Devices could not be retrieved

save_calibration(name, description, calibration_serialized, device_id, user_id, qililab_version)[source]

Save a calibration into the database af our servers, for it to be easily recovered when needed.

Warning

This method is only available for Qilimanjaro members.

Parameters:

name – Name the experiment is going to be saved with.
description – Short descriptive text to more easily identify this specific experiment instance.
calibration_dict – Serialized calibration (using its .to_dict() method)
device_id – Id of the device the experiment was executed in
user_id – Id of the user that is executing the experiment
qililab_version – version of qililab the experiment was executed with

Returns:

new saved calibration

get_calibration(calibration_id=None, calibration_name=None)[source]

Get full information of a specific calibration

Warning

This method is only available for Qilimanjaro members.

Parameters:

calibration_id (int, optional) – id of the calibration to retrieve. Incompatible with providing a name.
calibration_name (str, optional) – name of the calibration to retrieve. Incompatible with providing an id.

Raises:

RemoteExecutionException – Calibration could not be retrieved

Returns:

serialized calibration dictionary

Return type:

Calibration

list_calibrations()[source]

List all calibrations

Raises:: RemoteExecutionException – Devices could not be retrieved
Returns:: All Calibrations
Return type:: Calibrations

update_calibration(calibration)[source]

Update the info of a calibration in the database

Warning

This method is only available for Qilimanjaro members.

Raises:: RemoteExecutionException – Calibration could not be retrieved
Returns:: serialized calibration dictionary
Return type:: Calibration

delete_calibration(calibration_id)[source]

Deletes a job from the database.

Warning

This method is only available for Qilimanjaro members.

Raises:: RemoteExecutionException – Devices could not be retrieved

delete_job(job_id)[source]

Deletes a job from the database.

Warning

This method is only available for admin members.

Raises:: RemoteExecutionException – Devices could not be retrieved

cancel_job(job_id)[source]: Cancels a job

Qiboconnection API