cirq_google.engine.engine_client.EngineClient

See Stable See Nightly

View source on GitHub

Client for the Quantum Engine API that deals with the engine protos and

View aliases

Main aliases

cirq_google.engine.engine.engine_client.EngineClient

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.