cirq_google.engine.Engine

Runs programs via the Quantum Engine API.

Inherits From: AbstractEngine

View aliases

Main aliases

cirq_google.Engine, cirq_google.engine.engine.Engine

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

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

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

Methods

`create_batch_program`

View source

create_batch_program(
    programs: Sequence[cirq.AbstractCircuit],
    program_id: Optional[str] = None,
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    description: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineProgram

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.

Raises
`ValueError`	If no gate set is provided.

`create_calibration_program`

View source

create_calibration_program(
    layers: List['cirq_google.CalibrationLayer'],
    program_id: Optional[str] = None,
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    description: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineProgram

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.

Raises
`ValueError`	If not gate set is given.

`create_program`

View source

create_program(
    program: cirq.AbstractCircuit,
    program_id: Optional[str] = None,
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    description: Optional[str] = None,
    labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineProgram

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.

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]],
    gate_set: Optional[cirq_google.serialization.Serializer] = None
) -> cirq_google.engine.QuantumEngineSampler

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`	A `Serializer` that determines how to serialize circuits when requesting samples.

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

`list_jobs`

View source

list_jobs(
    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 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

list_processors() -> List[cirq_google.engine.EngineProcessor]

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: Optional[Union[datetime.datetime, datetime.date]] = None,
    created_after: Optional[Union[datetime.datetime, datetime.date]] = None,
    has_labels: Optional[Dict[str, str]] = None
) -> List[cirq_google.engine.AbstractProgram]

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',),
    gate_set: cirq_google.serialization.Serializer = None,
    program_description: Optional[str] = None,
    program_labels: Optional[Dict[str, str]] = None,
    job_description: Optional[str] = None,
    job_labels: Optional[Dict[str, str]] = None
) -> 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`	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.

Raises
`ValueError`	If no gate set is provided.

`run_batch`

View source

run_batch(
    programs: Sequence[cirq.AbstractCircuit],
    program_id: Optional[str] = None,
    job_id: Optional[str] = None,
    params_list: List[cirq.Sweepable] = None,
    repetitions: int = 1,
    processor_ids: Sequence[str] = (),
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    program_description: Optional[str] = None,
    program_labels: Optional[Dict[str, str]] = None,
    job_description: Optional[str] = None,
    job_labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineJob

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.

Raises
`ValueError`	If the length of programs mismatches that of params_list, or `processor_ids` is not supplied.

`run_calibration`

View source

run_calibration(
    layers: List['cirq_google.CalibrationLayer'],
    program_id: Optional[str] = None,
    job_id: Optional[str] = None,
    processor_id: str = None,
    processor_ids: Sequence[str] = (),
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    program_description: Optional[str] = None,
    program_labels: Optional[Dict[str, str]] = None,
    job_description: Optional[str] = None,
    job_labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineJob

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

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

`run_sweep`

View source

run_sweep(
    program: cirq.AbstractCircuit,
    program_id: Optional[str] = None,
    job_id: Optional[str] = None,
    params: cirq.Sweepable = None,
    repetitions: int = 1,
    processor_ids: Sequence[str] = ('xmonsim',),
    gate_set: Optional[cirq_google.serialization.Serializer] = None,
    program_description: Optional[str] = None,
    program_labels: Optional[Dict[str, str]] = None,
    job_description: Optional[str] = None,
    job_labels: Optional[Dict[str, str]] = None
) -> cirq_google.engine.EngineJob

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.

Raises
`ValueError`	If no gate set is provided.

`sampler`

View source

sampler(
    processor_id: Union[str, List[str]],
    gate_set: Optional[cirq_google.serialization.Serializer] = None
) -> cirq_google.engine.QuantumEngineSampler

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.
        gate_set: A `Serializer` that determines how to serialize
             circuits when requesting samples.

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

cirq_google.engine.Engine

View aliases

Args

Raises

Methods

create_batch_program

create_calibration_program

create_program

get_processor

get_program

get_sampler

list_jobs

list_processors

list_programs

run

run_batch

run_calibration

run_sweep

sampler

`create_batch_program`

`create_calibration_program`

`create_program`

`get_processor`

`get_program`

`get_sampler`

`list_jobs`

`list_processors`

`list_programs`

`run`

`run_batch`

`run_calibration`

`run_sweep`

`sampler`