cirq_google.engine.engine_client.EngineClient

Client for the Quantum Engine API handling protos and gRPC client.

This is the client for the Quantum Engine API that deals with the engine protos and the gRPC client but not cirq protos or objects. All users are likely better served by using the Engine, EngineProgram, EngineJob, EngineProcessor, and Calibration objects instead of using this directly.

service_args A dictionary of arguments that can be used to configure options on the underlying gRPC client.
verbose Suppresses stderr messages when set to False. Default is true.
max_retry_delay_seconds The maximum number of seconds to retry when a retryable error code is returned.

grpc_client Creates an async grpc client for the quantum engine service.

Methods

add_job_labels

View source

Adds new labels to a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
labels New labels to add to the existing job labels.

Returns
The updated quantum job.

add_job_labels_async

View source

Adds new labels to a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
labels New labels to add to the existing job labels.

Returns
The updated quantum job.

add_program_labels

View source

Adds new labels to a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
labels New labels to add to the existing program labels.

Returns
The updated quantum program.

add_program_labels_async

View source

Adds new labels to a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
labels New labels to add to the existing program labels.

Returns
The updated quantum program.

cancel_job

View source

Cancels the given job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

cancel_job_async

View source

Cancels the given job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

cancel_reservation

View source

Cancels a quantum reservation.

This action is only valid if the associated [QuantumProcessor] schedule not been frozen. Otherwise, delete_reservation should be used.

The reservation will be truncated to end at the time when the request is serviced and any remaining time will be made available as an open swim period. This action will only succeed if the reservation has not yet ended and is within the processor's freeze window. If the reservation has already ended or is beyond the processor's freeze window, then the call will return an error.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,

cancel_reservation_async

View source

Cancels a quantum reservation.

This action is only valid if the associated [QuantumProcessor] schedule not been frozen. Otherwise, delete_reservation should be used.

The reservation will be truncated to end at the time when the request is serviced and any remaining time will be made available as an open swim period. This action will only succeed if the reservation has not yet ended and is within the processor's freeze window. If the reservation has already ended or is beyond the processor's freeze window, then the call will return an error.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,

create_job

View source

Creates and runs a job on Quantum Engine.

Either both run_name and device_config_name must be set, or neither of them must be set. If none of them are set, a default internal device configuration will be used.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
run_context Properly serialized run context.
processor_ids Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored. Otherwise the deprecated decorator will fix the arguments and call create_job_async using processor_id instead of processor_ids.
priority Optional priority to run at, 0-1000.
description Optional description to set on the job.
labels Optional set of labels to set on the job.
processor_id Processor id for running the program. If not set, processor_ids will be used.
run_name A unique identifier representing an automation run for the specified processor. An Automation Run contains a collection of device configurations for a processor. If specified, processor_id is required to be set.
device_config_name An identifier used to select the processor configuration utilized to run the job. A configuration identifies the set of available qubits, couplers, and supported gates in the processor. If specified, processor_id is required to be set.

Returns
Tuple of created job id and job.

Raises
ValueError If the priority is not between 0 and 1000.
ValueError If neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

create_job_async

View source

Creates and runs a job on Quantum Engine.

Either both run_name and device_config_name must be set, or neither of them must be set. If none of them are set, a default internal device configuration will be used.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
run_context Properly serialized run context.
processor_ids Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored. Otherwise the deprecated decorator will fix the arguments and call create_job_async using processor_id instead of processor_ids.
priority Optional priority to run at, 0-1000.
description Optional description to set on the job.
labels Optional set of labels to set on the job.
processor_id Processor id for running the program. If not set, processor_ids will be used.
run_name A unique identifier representing an automation run for the specified processor. An Automation Run contains a collection of device configurations for a processor. If specified, processor_id is required to be set.
device_config_name An identifier used to select the processor configuration utilized to run the job. A configuration identifies the set of available qubits, couplers, and supported gates in the processor. If specified, processor_id is required to be set.

Returns
Tuple of created job id and job.

Raises
ValueError If the priority is not between 0 and 1000.
ValueError If neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

create_program

View source

Creates a Quantum Engine program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
code Properly serialized program code.
description An optional description to set on the program.
labels Optional set of labels to set on the program.

Returns
Tuple of created program id and program

create_program_async

View source

Creates a Quantum Engine program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
code Properly serialized program code.
description An optional description to set on the program.
labels Optional set of labels to set on the program.

Returns
Tuple of created program id and program

create_reservation

View source

Creates a quantum reservation and returns the created object.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project, or None if the engine should generate an id
start the starting time of the reservation as a datetime object
end the ending time of the reservation as a datetime object
whitelisted_users a list of emails that can use the reservation.

create_reservation_async

View source

Creates a quantum reservation and returns the created object.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project, or None if the engine should generate an id
start the starting time of the reservation as a datetime object
end the ending time of the reservation as a datetime object
whitelisted_users a list of emails that can use the reservation.

delete_job

View source

Deletes a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

delete_job_async

View source

Deletes a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

delete_program

View source

Deletes a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
delete_jobs If True will delete all the program's jobs, other this will fail if the program contains any jobs.

delete_program_async

View source

Deletes a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
delete_jobs If True will delete all the program's jobs, other this will fail if the program contains any jobs.

delete_reservation

View source

Deletes a quantum reservation.

This action is only valid if the associated [QuantumProcessor] schedule has not been frozen. Otherwise, cancel_reservation should be used.

If the reservation has already ended or is within the processor's freeze window, then the call will return a FAILED_PRECONDITION error.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,

delete_reservation_async

View source

Deletes a quantum reservation.

This action is only valid if the associated [QuantumProcessor] schedule has not been frozen. Otherwise, cancel_reservation should be used.

If the reservation has already ended or is within the processor's freeze window, then the call will return a FAILED_PRECONDITION error.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,

get_calibration

View source

Returns a quantum calibration.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
calibration_timestamp_seconds The timestamp of the calibration in seconds.

Returns
The quantum calibration.

get_calibration_async

View source

Returns a quantum calibration.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
calibration_timestamp_seconds The timestamp of the calibration in seconds.

Returns
The quantum calibration.

get_current_calibration

View source

Returns the current quantum calibration for a processor if it has one.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.

Returns
The quantum calibration or None if there is no current calibration.

Raises
EngineException If the request for calibration fails.

get_current_calibration_async

View source

Returns the current quantum calibration for a processor if it has one.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.

Returns
The quantum calibration or None if there is no current calibration.

Raises
EngineException If the request for calibration fails.

get_job

View source

Returns a previously created job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
return_run_context If true then the run context will be loaded from the job's run_context_location and set on the returned QuantumJob.

get_job_async

View source

Returns a previously created job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
return_run_context If true then the run context will be loaded from the job's run_context_location and set on the returned QuantumJob.

get_job_results

View source

Returns the results of a completed job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

Returns
The quantum result.

get_job_results_async

View source

Returns the results of a completed job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.

Returns
The quantum result.

get_processor

View source

Returns a quantum processor.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.

Returns
The quantum processor.

get_processor_async

View source

Returns a quantum processor.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.

Returns
The quantum processor.

get_program

View source

Returns a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
return_code If True returns the serialized program code.

get_program_async

View source

Returns a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
return_code If True returns the serialized program code.

get_reservation

View source

Gets a quantum reservation from the engine.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project.

Raises
EngineException If the request to get the reservation failed.

get_reservation_async

View source

Gets a quantum reservation from the engine.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project.

Raises
EngineException If the request to get the reservation failed.

list_calibrations

View source

Returns a list of quantum calibrations.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str Filter string current only supports 'timestamp' with values of epoch time in seconds or short string 'yyyy-MM-dd'. For example: 'timestamp > 1577960125 AND timestamp <= 1578241810' 'timestamp > 2020-01-02 AND timestamp <= 2020-01-05'

Returns
A list of calibrations.

list_calibrations_async

View source

Returns a list of quantum calibrations.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str Filter string current only supports 'timestamp' with values of epoch time in seconds or short string 'yyyy-MM-dd'. For example: 'timestamp > 1577960125 AND timestamp <= 1578241810' 'timestamp > 2020-01-02 AND timestamp <= 2020-01-05'

Returns
A list of calibrations.

list_jobs

View source

Returns the list of jobs for a given program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Optional, a unique ID of the program within the parent project. If None, jobs will be listed across all programs within the project.
created_after retrieve jobs that were created after this date or time.
created_before retrieve jobs that were created after this date or time.
has_labels retrieve jobs that have labels on them specified by this dict. If the value is set to *, filters having the label regardless of the label value will be filtered. For example, to query programs that have the shape label and have the color label with value red can be queried using

{'color': 'red', 'shape':'*'}

execution_states retrieve jobs that have an execution state that is contained in execution_states. See quantum.ExecutionStatus.State enum for accepted values.
executed_processor_ids filters jobs by processor ID used for execution. Matches any of provided IDs.
scheduled_processor_ids filters jobs by any of provided scheduled processor IDs.

list_jobs_async

View source

Returns the list of jobs for a given program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Optional, a unique ID of the program within the parent project. If None, jobs will be listed across all programs within the project.
created_after retrieve jobs that were created after this date or time.
created_before retrieve jobs that were created after this date or time.
has_labels retrieve jobs that have labels on them specified by this dict. If the value is set to *, filters having the label regardless of the label value will be filtered. For example, to query programs that have the shape label and have the color label with value red can be queried using

{'color': 'red', 'shape':'*'}

execution_states retrieve jobs that have an execution state that is contained in execution_states. See quantum.ExecutionStatus.State enum for accepted values.
executed_processor_ids filters jobs by processor ID used for execution. Matches any of provided IDs.
scheduled_processor_ids filters jobs by any of provided scheduled processor IDs.

list_processors

View source

Returns a list of Processors that the user has visibility to in the current Engine project. The names of these processors are used to identify devices when scheduling jobs and gathering calibration metrics.

Args
project_id A project_id of the parent Google Cloud Project.

Returns
A list of metadata of each processor.

list_processors_async

View source

Returns a list of Processors that the user has visibility to in the current Engine project. The names of these processors are used to identify devices when scheduling jobs and gathering calibration metrics.

Args
project_id A project_id of the parent Google Cloud Project.

Returns
A list of metadata of each processor.

list_programs

View source

Returns a list of previously executed quantum programs.

Args
project_id the id of the project
created_after retrieve programs that were created after this date or time.
created_before retrieve programs that were created after this date or time.
has_labels retrieve programs that have labels on them specified by this dict. If the value is set to *, filters having the label egardless of the label value will be filtered. For example, to uery programs that have the shape label and have the color label with value red can be queried using

{'color': 'red', 'shape':'*'}

list_programs_async

View source

Returns a list of previously executed quantum programs.

Args
project_id the id of the project
created_after retrieve programs that were created after this date or time.
created_before retrieve programs that were created after this date or time.
has_labels retrieve programs that have labels on them specified by this dict. If the value is set to *, filters having the label egardless of the label value will be filtered. For example, to uery programs that have the shape label and have the color label with value red can be queried using

{'color': 'red', 'shape':'*'}

list_reservations

View source

Returns a list of quantum reservations.

Only reservations owned by this project will be returned.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str A string for filtering quantum reservations. The fields eligible for filtering are start_time and end_time Examples: start_time >= 1584385200: Reservation began on or after the epoch time Mar 16th, 7pm GMT. end_time >= 1483370475: Reservation ends on or after Jan 2nd 2017 15:21:15

Returns
A list of QuantumReservation objects.

list_reservations_async

View source

Returns a list of quantum reservations.

Only reservations owned by this project will be returned.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str A string for filtering quantum reservations. The fields eligible for filtering are start_time and end_time Examples: start_time >= 1584385200: Reservation began on or after the epoch time Mar 16th, 7pm GMT. end_time >= 1483370475: Reservation ends on or after Jan 2nd 2017 15:21:15

Returns
A list of QuantumReservation objects.

list_time_slots

View source

Returns a list of quantum time slots on a processor.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str A string expression for filtering the quantum time slots returned by the list command. The fields eligible for filtering are start_time, end_time.

Returns
A list of QuantumTimeSlot objects.

list_time_slots_async

View source

Returns a list of quantum time slots on a processor.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
filter_str A string expression for filtering the quantum time slots returned by the list command. The fields eligible for filtering are start_time, end_time.

Returns
A list of QuantumTimeSlot objects.

remove_job_labels

View source

Removes labels with given keys from the labels of a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
label_keys Label keys to remove from the existing job labels.

Returns
The updated quantum job.

remove_job_labels_async

View source

Removes labels with given keys from the labels of a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
label_keys Label keys to remove from the existing job labels.

Returns
The updated quantum job.

remove_program_labels

View source

Removes labels with given keys from the labels of a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
label_keys Label keys to remove from the existing program labels.

Returns
The updated quantum program.

remove_program_labels_async

View source

Removes labels with given keys from the labels of a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
label_keys Label keys to remove from the existing program labels.

Returns
The updated quantum program.

run_job_over_stream

View source

Runs a job with the given program and job information over a stream.

Sends the request over the Quantum Engine QuantumRunStream bidirectional stream, and returns a future for the stream response. The future will be completed with a QuantumResult if the job is successful; otherwise, it will be completed with a QuantumJob.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
code Properly serialized program code.
run_context Properly serialized run context.
program_description An optional description to set on the program.
program_labels Optional set of labels to set on the program.
job_id Unique ID of the job within the parent program.
priority Optional priority to run at, 0-1000.
job_description Optional description to set on the job.
job_labels Optional set of labels to set on the job.
processor_id Processor id for running the program. If not set, processor_ids will be used.
run_name A unique identifier representing an automation run for the specified processor. An Automation Run contains a collection of device configurations for a processor. If specified, processor_id is required to be set.
device_config_name An identifier used to select the processor configuration utilized to run the job. A configuration identifies the set of available qubits, couplers, and supported gates in the processor. If specified, processor_id is required to be set.

Returns
A future for the job result, or the job if the job has failed.

Raises
ValueError If the priority is not between 0 and 1000.
ValueError If processor_id is not set.
ValueError If only one of run_name and device_config_name are specified.

set_job_description

View source

Sets the description for a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
description The new job description.

Returns
The updated quantum job.

set_job_description_async

View source

Sets the description for a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
description The new job description.

Returns
The updated quantum job.

set_job_labels

View source

Sets (overwriting) the labels for a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
labels The entire set of new job labels.

Returns
The updated quantum job.

set_job_labels_async

View source

Sets (overwriting) the labels for a previously created quantum job.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
job_id Unique ID of the job within the parent program.
labels The entire set of new job labels.

Returns
The updated quantum job.

set_program_description

View source

Sets the description for a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
description The new program description.

Returns
The updated quantum program.

set_program_description_async

View source

Sets the description for a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
description The new program description.

Returns
The updated quantum program.

set_program_labels

View source

Sets (overwriting) the labels for a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
labels The entire set of new program labels.

Returns
The updated quantum program.

set_program_labels_async

View source

Sets (overwriting) the labels for a previously created quantum program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
labels The entire set of new program labels.

Returns
The updated quantum program.

update_reservation

View source

Updates a quantum reservation.

This will update a quantum reservation's starting time, ending time, and list of whitelisted users. If any field is not filled, it will not be updated.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,
start the new starting time of the reservation as a datetime object
end the new ending time of the reservation as a datetime object
whitelisted_users a list of emails that can use the reservation. The empty list, [], will clear the whitelisted_users while None will leave the value unchanged.

update_reservation_async

View source

Updates a quantum reservation.

This will update a quantum reservation's starting time, ending time, and list of whitelisted users. If any field is not filled, it will not be updated.

Args
project_id A project_id of the parent Google Cloud Project.
processor_id The processor unique identifier.
reservation_id Unique ID of the reservation in the parent project,
start the new starting time of the reservation as a datetime object
end the new ending time of the reservation as a datetime object
whitelisted_users a list of emails that can use the reservation. The empty list, [], will clear the whitelisted_users while None will leave the value unchanged.