cirq_google.engine.Engine

Runs programs via the Quantum Engine API.

Inherits From: AbstractEngine

cirq_google.engine.Engine(
    project_id: str,
    proto_version: (ProtoVersion | None) = None,
    service_args: (dict | None) = None,
    verbose: (bool | None) = None,
    timeout: (int | None) = None,
    context: (EngineContext | None) = None,
    compress_run_context: bool = False
) -> None

This class has methods for creating programs and jobs that execute on Quantum Engine:

  • create_program
  • run
  • run_sweep

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
  • list_jobs
  • get_job

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.
compress_run_context If true, the run context (i.e. sweep information will be compressed using gzip in transit. This will save on data transfer size but will add a small overhead client-side.

ValueError If context is provided and one of proto_version, service_args, or verbose.

Methods

create_program

View source

create_program(
    program, program_id=None, description=None, labels=None
)

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.
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.

Raises
ValueError If no gate set is provided.

create_program_async

View source

create_program_async(
    program, program_id=None, description=None, labels=None
)

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.
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.

Raises
ValueError If no gate set is provided.

get_job

View source

get_job(
    job_id
)

Returns an EngineJob for an existing Quantum Engine job.

Args
job_id Unique ID of the job within the parent project.

Returns
The EngineJob if the job_id mapped to a real job.

Raises
ValueError If the job_id does not map to a real job.

get_job_async

View source

get_job_async(
    job_id
)

Returns an EngineJob for an existing Quantum Engine job.

Args
job_id Unique ID of the job within the parent project.

Returns
The EngineJob if the job_id mapped to a real job.

Raises
ValueError If the job_id does not map to a real job.

get_processor

View source

get_processor(
    processor_id: str
) -> engine_processor.EngineProcessor

Returns an EngineProcessor for a Quantum Engine processor.

Args
processor_id The processor unique identifier.

Returns
A EngineProcessor for the processor.

get_processor_config

View source

get_processor_config(
    processor_id,
    device_config_revision=Run(id='current'),
    config_name='default'
)

Returns a ProcessorConfig from this project and the given processor id.

If no run_name and config_name are specified, the internally configured default config is returned.

Args
processor_id The processor unique identifier.
device_config_revision Specifies either the snapshot_id or the run_name.
config_name The identifier for the config.

Returns
The ProcessorConfig from this project and processor.

get_processor_config_async

View source

get_processor_config_async(
    processor_id,
    device_config_revision=Run(id='current'),
    config_name='default'
)

Returns a ProcessorConfig from this project and the given processor id.

If no run_name and config_name are specified, the internally configured default config is returned.

Args
processor_id The processor unique identifier.
device_config_revision Specifies either the snapshot_id or the run_name.
config_name The identifier for the config.

Returns
The ProcessorConfig from this project and processor.

get_program

View source

get_program(
    program_id: str
) -> engine_program.EngineProgram

Returns an EngineProgram for an existing Quantum Engine program.

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

Returns
The EngineProgram for the program.

get_sampler

View source

get_sampler(
    processor_id: (str | list[str]),
    device_config_name: (str | None) = None,
    device_config_revision: (processor_config.DeviceConfigRevision | None) = None,
    max_concurrent_jobs: int = 100
) -> cirq_google.ProcessorSampler

Returns a sampler backed by the engine.

Args
processor_id String identifier of which processor should be used to sample.
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.
device_config_revision Specifies either the snapshot_id or the run_name.
max_concurrent_jobs The maximum number of jobs to be sent concurrently to the Engine. This client-side throttle can be used to proactively reduce load to the backends and avoid quota violations when pipelining circuit executions.

Returns
A cirq.Sampler instance (specifically a engine_sampler.ProcessorSampler that will send circuits to the Quantum Computing Service when sampled.

Raises
ValueError if a list of processors is provided. This is no longer supported.

list_jobs

View source

list_jobs(
    created_before=None,
    created_after=None,
    has_labels=None,
    execution_states=None
)

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 based 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.ExecutionStatus.State enum for accepted values.

list_jobs_async

View source

list_jobs_async(
    created_before=None,
    created_after=None,
    has_labels=None,
    execution_states=None
)

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 based 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.ExecutionStatus.State enum for accepted values.

list_processor_configs

View source

list_processor_configs(
    processor_id,
    device_config_revision=Run(id='current')
)

Returns list of ProcessorConfigs from an automation run.

Args
processor_id The processor unique identifier.
device_config_revision Specifies either the snapshot_id or the run_name.

Returns
List of ProcessorConfigs.

list_processor_configs_async

View source

list_processor_configs_async(
    processor_id,
    device_config_revision=Run(id='current')
)

Returns list of ProcessorConfigs from an automation run.

Args
processor_id The processor unique identifier.
device_config_revision Specifies either the snapshot_id or the run_name.

Returns
List of ProcessorConfigs.

list_processors

View source

list_processors()

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_processors_async

View source

list_processors_async()

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

list_programs(
    created_before=None, created_after=None, has_labels=None
)

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

list_programs_async

View source

list_programs_async(
    created_before=None, created_after=None, has_labels=None
)

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

run(
    program: cirq.AbstractCircuit,
    processor_id: str,
    program_id: (str | None) = None,
    job_id: (str | None) = None,
    param_resolver: cirq.ParamResolver = cirq.ParamResolver({}),
    repetitions: int = 1,
    program_description: (str | None) = None,
    program_labels: (dict[str, str] | None) = None,
    job_description: (str | None) = None,
    job_labels: (dict[str, str] | None) = None,
    *,
    run_name: str = '',
    snapshot_id: str = '',
    device_config_name: str = ''
) -> cirq.Result

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.
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.
processor_id Processor id for running the program.
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.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor.
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 single Result for this run.

Raises
ValueError If no gate set is provided.
ValueError If only one of run_name and device_config_name are specified.
ValueError If either run_name and device_config_name are set but processor_id is empty.

run_sweep

View source

run_sweep(
    program,
    processor_id,
    program_id=None,
    job_id=None,
    params=None,
    repetitions=1,
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    run_name='',
    snapshot_id='',
    device_config_name=''
)

Runs the supplied Circuit via Quantum Engine.

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. A list or mapping of programs can also be provided. These will be executed as KeyedCircuits.
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.
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.
processor_id Processor id for running the program.
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.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor.
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
An EngineJob. If this is iterated over it returns a list of TrialResults, one for each parameter sweep.

Raises
ValueError If no gate set is provided.
ValueError If only one of run_name and device_config_name are specified.
ValueError If either run_name and device_config_name are set but processor_id is empty.

run_sweep_async

View source

run_sweep_async(
    program,
    processor_id,
    program_id=None,
    job_id=None,
    params=None,
    repetitions=1,
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    run_name='',
    snapshot_id='',
    device_config_name=''
)

Runs the supplied Circuit via Quantum Engine.

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. A list or mapping of programs can also be provided. These will be executed as KeyedCircuits.
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.
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.
processor_id Processor id for running the program.
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.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor.
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
An EngineJob. If this is iterated over it returns a list of TrialResults, one for each parameter sweep.

Raises
ValueError If no gate set is provided.
ValueError If only one of run_name and device_config_name are specified.
ValueError If either run_name and device_config_name are set but processor_id is empty.