cirq_google.engine.engine_client.EngineClient

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.

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

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.

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,

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
)

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.

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.