cirq.google.Engine

Runs programs via the Quantum Engine API.

Used in the notebooks

Used in the tutorials

This class has methods for creating programs and jobs that execute on Quantum Engine: create_program run run_sweep run_batch

Another set of methods return information about programs and jobs that have been previously created on the Quantum Engine, as well as metadata about available processors: get_program list_processors get_processor

project_id A project_id string of the Google Cloud Project to use. API interactions will be attributed to this project and any resources created will be owned by the project. See https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects
proto_version The version of cirq protos to use. If None, then ProtoVersion.V2 will be used.
service_args A dictionary of arguments that can be used to configure options on the underlying client.
verbose Suppresses stderr messages when set to False. Default is true.
timeout Timeout for polling for results, in seconds. Default is to never timeout.
context Engine configuration and context to use. For most users this should never be specified.

Methods

create_batch_program

View source

Wraps a list of Circuits into a BatchProgram for the Quantum Engine.

Args
programs The Circuits to execute within a batch.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'prog-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor
description An optional description to set on the program.
labels Optional set of labels to set on the program.

Returns
A EngineProgram for the newly created program.

create_calibration_program

View source

Wraps a list of calibration layers into an Any for Quantum Engine.

Args
layers The calibration routines to execute. All layers will be executed within the same API call in the order specified, though some layers may be interleaved together using hardware-specific batching.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'calibration-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
gate_set The gate set used to serialize the circuits in each layer. The gate set must be supported by the processor.
description An optional description to set on the program.
labels Optional set of labels to set on the program.

Returns
A EngineProgram for the newly created program.

create_program

View source

Wraps a Circuit for use with the Quantum Engine.

Args
program The Circuit to execute.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'prog-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor
description An optional description to set on the program.
labels Optional set of labels to set on the program.

Returns
A EngineProgram for the newly created program.

get_processor

View source

Returns an EngineProcessor for a Quantum Engine processor.

Args
processor_id The processor unique identifier.

Returns
A EngineProcessor for the processor.

get_program

View source

Returns an EngineProgram for an existing Quantum Engine program.

Args
program_id Unique ID of the program within the parent project.

Returns
A EngineProgram for the program.

list_jobs

View source

Returns the list of jobs in the project.

All historical jobs can be retrieved using this method and filtering options are available too, to narrow down the search baesd on:

  • creation time
  • job labels
  • execution states

Args
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

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.

Returns
A list of EngineProcessors to access status, device and calibration information.

list_programs

View source

Returns a list of previously executed quantum programs.

Args
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 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:*'}

run

View source

Runs the supplied Circuit via Quantum Engine.

Args
program The Circuit to execute. If a circuit is provided, a moment by moment schedule will be used.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'prog-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
job_id Job identifier to use. If this is not provided, a random id of the format 'job-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
param_resolver Parameters to run with the program.
repetitions The number of repetitions to simulate.
processor_ids The engine processors that should be candidates to run the program. Only one of these will be scheduled for execution.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor.
program_description An optional description to set on the program.
program_labels Optional set of labels to set on the program.
job_description An optional description to set on the job.
job_labels Optional set of labels to set on the job.

Returns
A single Result for this run.

run_batch

View source

Runs the supplied Circuits via Quantum Engine.Creates

This will combine each Circuit provided in programs into a BatchProgram. Each circuit will pair with the associated parameter sweep provided in the params_list. The number of programs is required to match the number of sweeps.

This method does not block until a result is returned. However, no results will be available until the entire batch is complete.

Args
programs The Circuits to execute as a batch.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'prog-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
job_id Job identifier to use. If this is not provided, a random id of the format 'job-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
params_list Parameter sweeps to use with the circuits. The number of sweeps should match the number of circuits and will be paired in order with the circuits. If this is None, it is assumed that the circuits are not parameterized and do not require sweeps.
repetitions Number of circuit repetitions to run. Each sweep value of each circuit in the batch will run with the same repetitions.
processor_ids The engine processors that should be candidates to run the program. Only one of these will be scheduled for execution.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor.
program_description An optional description to set on the program.
program_labels Optional set of labels to set on the program.
job_description An optional description to set on the job.
job_labels Optional set of labels to set on the job.

Returns
An EngineJob. If this is iterated over it returns a list of TrialResults. All TrialResults for the first circuit are listed first, then the TrialResults for the second, etc. The TrialResults for a circuit are listed in the order imposed by the associated parameter sweep.

run_calibration

View source

Runs the specified calibrations via the Calibration API.

Each calibration will be specified by a CalibrationLayer that contains the type of the calibrations to run, a Circuit to optimize, and any arguments needed by the calibration routine.

Arguments and circuits needed for each layer will vary based on the calibration type. However, the typical calibration routine may require a single moment defining the gates to optimize, for example.

Args
layers The layers of calibration to execute as a batch.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'calibration-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
job_id Job identifier to use. If this is not provided, a random id of the format 'calibration-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
processor_id The engine processor that should run the calibration. If this is specified, processor_ids should not be specified.
processor_ids The engine processors that should be candidates to run the program. Only one of these will be scheduled for execution.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor.
program_description An optional description to set on the program.
program_labels Optional set of labels to set on the program.
job_description An optional description to set on the job.
job_labels Optional set of labels to set on the job. By defauly, this will add a 'calibration' label to the job.

Returns
An EngineJob whose results can be retrieved by calling calibration_results().

run_sweep

View source

Runs the supplied Circuit via Quantum Engine.Creates

In contrast to run, this runs across multiple parameter sweeps, and does not block until a result is returned.

Args
program The Circuit to execute. If a circuit is provided, a moment by moment schedule will be used.
program_id A user-provided identifier for the program. This must be unique within the Google Cloud project being used. If this parameter is not provided, a random id of the format 'prog-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
job_id Job identifier to use. If this is not provided, a random id of the format 'job-################YYMMDD' will be generated, where # is alphanumeric and YYMMDD is the current year, month, and day.
params Parameters to run with the program.
repetitions The number of circuit repetitions to run.
processor_ids The engine processors that should be candidates to run the program. Only one of these will be scheduled for execution.
gate_set The gate set used to serialize the circuit. The gate set must be supported by the selected processor.
program_description An optional description to set on the program.
program_labels Optional set of labels to set on the program.
job_description An optional description to set on the job.
job_labels Optional set of labels to set on the job.

Returns
An EngineJob. If this is iterated over it returns a list of TrialResults, one for each parameter sweep.

sampler

View source

Returns a sampler backed by the engine.

Args
processor_id String identifier, or list of string identifiers, determining which processors may be used when sampling.
gate_set Determines how to serialize circuits when requesting samples.