cirq_google.engine.Engine

Runs programs via the Quantum Engine API.

Inherits From: AbstractEngine

cirq_google.engine.Engine(
    project_id: str,
    proto_version: Optional[cirq_google.engine.ProtoVersion] = None,
    service_args: Optional[Dict] = None,
    verbose: Optional[bool] = None,
    timeout: Optional[int] = None,
    context: Optional[cirq_google.engine.engine.EngineContext] = None
) -> None

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.

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

Methods

create_batch_program

View source

create_batch_program(
    programs, program_id=None, description=None, labels=None
)

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

View source

create_batch_program_async(
    programs, program_id=None, description=None, labels=None
)

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

View source

create_calibration_program(
    layers, program_id=None, description=None, labels=None
)

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.
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 not gate set is given.

create_calibration_program_async

View source

create_calibration_program_async(
    layers, program_id=None, description=None, labels=None
)

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.
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 not gate set is given.

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_processor

View source

get_processor(
    processor_id: str
) -> cirq_google.engine.EngineProcessor

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

get_program(
    program_id: str
) -> cirq_google.engine.EngineProgram

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.

get_sampler

View source

get_sampler(
    processor_id: Union[str, List[str]],
    run_name: str = '',
    device_config_name: str = ''
) -> 'cirq_google.ProcessorSampler'

Returns a sampler backed by the engine.

Args
processor_id String identifier of which processor should be used to sample.
run_name A unique identifier representing an automation run for the processor. An Automation Run 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.

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

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,
    program_id: Optional[str] = None,
    job_id: Optional[str] = None,
    param_resolver: cirq.ParamResolver = cirq.ParamResolver({}),
    repetitions: int = 1,
    processor_ids: Sequence[str] = ('xmonsim',),
    program_description: Optional[str] = None,
    program_labels: Optional[Dict[str, str]] = None,
    job_description: Optional[str] = None,
    job_labels: Optional[Dict[str, str]] = None,
    *,
    processor_id: str = '',
    run_name: 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.
processor_ids Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored.
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. If not set, processor_ids will be used.
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.
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 neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

run_batch

View source

run_batch(
    programs,
    program_id=None,
    job_id=None,
    params_list=None,
    repetitions=1,
    processor_ids=(),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    processor_id='',
    run_name='',
    device_config_name=''
)

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 Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored.
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. If not set, processor_ids will be used.
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.
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. 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.

Raises
ValueError If the length of programs mismatches that of params_list, or processor_ids is not supplied.
ValueError If neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

run_batch_async

View source

run_batch_async(
    programs,
    program_id=None,
    job_id=None,
    params_list=None,
    repetitions=1,
    processor_ids=(),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    processor_id='',
    run_name='',
    device_config_name=''
)

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 Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored.
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. If not set, processor_ids will be used.
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.
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. 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.

Raises
ValueError If the length of programs mismatches that of params_list, or processor_ids is not supplied.
ValueError If neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

run_calibration

View source

run_calibration(
    layers,
    program_id=None,
    job_id=None,
    processor_id=None,
    processor_ids=(),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None
)

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.
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 default, this will add a 'calibration' label to the job.

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

Raises
ValueError If processor_id and processor_ids are both specified, or neither is supplied.

run_calibration_async

View source

run_calibration_async(
    layers,
    program_id=None,
    job_id=None,
    processor_id=None,
    processor_ids=(),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None
)

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.
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 default, this will add a 'calibration' label to the job.

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

Raises
ValueError If processor_id and processor_ids are both specified, or neither is supplied.

run_sweep

View source

run_sweep(
    program,
    program_id=None,
    job_id=None,
    params=None,
    repetitions=1,
    processor_ids=('xmonsim',),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    processor_id='',
    run_name='',
    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.
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 Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored.
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. If not set, processor_ids will be used.
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.
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 neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
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,
    program_id=None,
    job_id=None,
    params=None,
    repetitions=1,
    processor_ids=('xmonsim',),
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    *,
    processor_id='',
    run_name='',
    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.
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 Deprecated list of candidate processor ids to run the program. Only allowed to contain one processor_id. If the argument processor_id is non-empty, processor_ids will be ignored.
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. If not set, processor_ids will be used.
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.
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 neither processor_id or processor_ids are set.
ValueError If only one of run_name and device_config_name are specified.
ValueError If processor_ids has more than one processor id.
ValueError If either run_name and device_config_name are set but processor_id is empty.

sampler

View source

sampler(
    processor_id: Union[str, List[str]]
) -> 'cirq_google.ProcessorSampler'

THIS FUNCTION IS DEPRECATED.

IT WILL BE REMOVED IN cirq v1.0.

Use get_sampler instead.

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.

    Returns:
        A <a href="https://quantumai.google/reference/python/cirq/Sampler"><code>cirq.Sampler</code></a> instance (specifically a `engine_sampler.ProcessorSampler`
        that will send circuits to the Quantum Computing Service
        when sampled.