See Stable
See Nightly
Client for the Quantum Engine API that deals with the engine protos and
cirq_google.engine.engine_client.EngineClient(
service_args: Optional[Dict] = None,
verbose: Optional[bool] = None,
max_retry_delay_seconds: int = 3600
) -> None
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.
Args
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.
Methods
add_job_labels
View source
add_job_labels(
project_id: str, program_id: str, job_id: str, labels: Dict[str, str]
) -> qtypes.QuantumJob
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
add_program_labels(
project_id: str, program_id: str, labels: Dict[str, str]
) -> qtypes.QuantumProgram
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
cancel_job(
project_id: str, program_id: str, job_id: str
) -> None
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
cancel_reservation(
project_id: str, processor_id: str, reservation_id: str
)
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
create_job(
project_id: str,
program_id: str,
job_id: Optional[str],
processor_ids: Sequence[str],
run_context: qtypes.any_pb2.Any,
priority: Optional[int] = None,
description: Optional[str] = None,
labels: Optional[Dict[str, str]] = None
) -> Tuple[str, qtypes.QuantumJob]
Creates and runs a job on Quantum Engine.
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
List of processor id for running the program.
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.
Returns
Tuple of created job id and job.
Raises
ValueError
If the priority is not betwen 0 and 1000.
create_program
View source
create_program(
project_id: str,
program_id: Optional[str],
code: qtypes.any_pb2.Any,
description: Optional[str] = None,
labels: Optional[Dict[str, str]] = None
) -> Tuple[str, qtypes.QuantumProgram]
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
create_reservation(
project_id: str,
processor_id: str,
start: datetime.datetime,
end: datetime.datetime,
whitelisted_users: Optional[List[str]] = None
)
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
delete_job(
project_id: str, program_id: str, job_id: str
) -> None
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
delete_program(
project_id: str, program_id: str, delete_jobs: bool = False
) -> None
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
delete_reservation(
project_id: str, processor_id: str, reservation_id: str
)
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
get_calibration(
project_id: str, processor_id: str, calibration_timestamp_seconds: int
) -> qtypes.QuantumCalibration
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
get_current_calibration(
project_id: str, processor_id: str
) -> Optional[qtypes.QuantumCalibration]
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
get_job(
project_id: str, program_id: str, job_id: str, return_run_context: bool
) -> qtypes.QuantumJob
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
get_job_results(
project_id: str, program_id: str, job_id: str
) -> qtypes.QuantumResult
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
get_processor(
project_id: str, processor_id: str
) -> qtypes.QuantumProcessor
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
get_program(
project_id: str, program_id: str, return_code: bool
) -> qtypes.QuantumProgram
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
get_reservation(
project_id: str, processor_id: str, reservation_id: str
)
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
list_calibrations(
project_id: str, processor_id: str, filter_str: str = ''
) -> List[qtypes.QuantumCalibration]
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
list_jobs(
project_id: str,
program_id: Optional[str] = None,
created_before: Optional[Union[datetime.datetime, datetime.date]] = None,
created_after: Optional[Union[datetime.datetime, datetime.date]] = None,
has_labels: Optional[Dict[str, str]] = None,
execution_states: Optional[Set[quantum.enums.ExecutionStatus.State]] = None,
executed_processor_ids: Optional[List[str]] = None,
scheduled_processor_ids: Optional[List[str]] = None
)
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.enums.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
list_processors(
project_id: str
) -> List[qtypes.QuantumProcessor]
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
list_programs(
project_id: str,
created_before: Optional[Union[datetime.datetime, datetime.date]] = None,
created_after: Optional[Union[datetime.datetime, datetime.date]] = None,
has_labels: Optional[Dict[str, str]] = None
)
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
list_reservations(
project_id: str, processor_id: str, filter_str: str = ''
) -> List[qtypes.QuantumReservation]
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
list_time_slots(
project_id: str, processor_id: str, filter_str: str = ''
) -> List[qtypes.QuantumTimeSlot]
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
remove_job_labels(
project_id: str, program_id: str, job_id: str, label_keys: List[str]
) -> qtypes.QuantumJob
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
remove_program_labels(
project_id: str, program_id: str, label_keys: List[str]
) -> qtypes.QuantumProgram
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.
set_job_description
View source
set_job_description(
project_id: str, program_id: str, job_id: str, description: str
) -> qtypes.QuantumJob
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
set_job_labels(
project_id: str, program_id: str, job_id: str, labels: Dict[str, str]
) -> qtypes.QuantumJob
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
set_program_description(
project_id: str, program_id: str, description: str
) -> qtypes.QuantumProgram
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
set_program_labels(
project_id: str, program_id: str, labels: Dict[str, str]
) -> qtypes.QuantumProgram
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
update_reservation(
project_id: str,
processor_id: str,
reservation_id: str,
start: Optional[datetime.datetime] = None,
end: Optional[datetime.datetime] = None,
whitelisted_users: Optional[List[str]] = None
)
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.