cirq_google.engine.EngineProgram

A program created via the Quantum Engine API.

Inherits From: AbstractProgram

cirq_google.engine.EngineProgram(
    project_id: str,
    program_id: str,
    context: engine_base.EngineContext,
    _program: (quantum.QuantumProgram | None) = None
) -> None

This program wraps a Circuit with additional metadata used to schedule against the devices managed by Quantum Engine.

project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.
context Engine configuration and context to use.
_program The optional current program state.

project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent project.

Methods

add_labels

View source

add_labels(
    labels
)

Adds new labels to a previously created quantum program.

Params
labels New labels to add to the existing program labels.

Returns
This EngineProgram.

add_labels_async

View source

add_labels_async(
    labels
)

Adds new labels to a previously created quantum program.

Params
labels New labels to add to the existing program labels.

Returns
This EngineProgram.

batch_size

View source

batch_size()

Returns the number of programs in a batch program.

Raises
ValueError if the program created was not a batch program.

batch_size_async

View source

batch_size_async()

Returns the number of programs in a batch program.

Raises
ValueError if the program created was not a batch program.

create_time

View source

create_time() -> datetime.datetime

Returns when the program was created.

delete

View source

delete(
    delete_jobs=False
)

Deletes a previously created quantum program.

Params
delete_jobs If True will delete all the program's jobs, other this will fail if the program contains any jobs.

delete_async

View source

delete_async(
    delete_jobs=False
)

Deletes a previously created quantum program.

Params
delete_jobs If True will delete all the program's jobs, other this will fail if the program contains any jobs.

delete_job

View source

delete_job(
    job_id
)

Deletes the job and result, if any.

delete_job_async

View source

delete_job_async(
    job_id
)

Deletes the job and result, if any.

description

View source

description() -> str

Returns the description of the program.

engine

View source

engine() -> engine_base.Engine

Returns the parent Engine object.

Returns
The program's parent Engine.

get_circuit

View source

get_circuit(
    circuit_num=None
)

Returns the cirq Circuit for the Quantum Engine program. This is only supported if the program was created with the V2 protos.

Args
circuit_num if this is a multi-circuit program, the index of the circuit to return. This argument is zero-indexed. Negative values indexing from the end of the list.

Returns
The program's cirq Circuit.

get_circuit_async

View source

get_circuit_async(
    circuit_num=None
)

Returns the cirq Circuit for the Quantum Engine program. This is only supported if the program was created with the V2 protos.

Args
circuit_num if this is a multi-circuit program, the index of the circuit to return. This argument is zero-indexed. Negative values indexing from the end of the list.

Returns
The program's cirq Circuit.

get_circuits

View source

get_circuits()

Returns all the cirq Circuits for the Quantum Engine program.

get_circuits_async

View source

get_circuits_async()

Returns all the cirq Circuits for the Quantum Engine program.

get_job

View source

get_job(
    job_id: str
) -> engine_job.EngineJob

Returns an EngineJob for an existing Quantum Engine job.

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

Returns
A EngineJob for the job.

is_batch

View source

is_batch()

Returns True if the program is a batch program.

is_batch_async

View source

is_batch_async()

Returns True if the program is a batch program.

labels

View source

labels() -> dict[str, str]

Returns the labels of the program.

list_jobs

View source

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

Returns the list of jobs for this program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent 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.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 for this program.

Args
project_id A project_id of the parent Google Cloud Project.
program_id Unique ID of the program within the parent 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.ExecutionStatus.State enum for accepted values.

remove_labels

View source

remove_labels(
    keys
)

Removes labels with given keys from the labels of a previously created quantum program.

Params
label_keys Label keys to remove from the existing program labels.

Returns
This EngineProgram.

remove_labels_async

View source

remove_labels_async(
    keys
)

Removes labels with given keys from the labels of a previously created quantum program.

Params
label_keys Label keys to remove from the existing program labels.

Returns
This EngineProgram.

run

View source

run(
    *,
    processor_id,
    run_name='',
    snapshot_id='',
    device_config_name,
    job_id=None,
    param_resolver=cirq.ParamResolver({}),
    repetitions=1,
    description=None,
    labels=None
)

Runs the supplied Circuit via Quantum Engine.

Args
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.
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.
job_id Optional job id 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.
description An optional description to set on the job.
labels Optional set of labels to set on the job.

Returns
An EngineJob. If this is iterated over it yields one EngineResult.

Raises
ValueError If a processor id hasn't been specified to run the job
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_async

View source

run_async(
    *,
    processor_id,
    run_name='',
    snapshot_id='',
    device_config_name,
    job_id=None,
    param_resolver=cirq.ParamResolver({}),
    repetitions=1,
    description=None,
    labels=None
)

Runs the supplied Circuit via Quantum Engine.

Args
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.
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.
job_id Optional job id 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.
description An optional description to set on the job.
labels Optional set of labels to set on the job.

Returns
An EngineJob. If this is iterated over it yields one EngineResult.

Raises
ValueError If a processor id hasn't been specified to run the job
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(
    processor_id,
    *,
    device_config_name,
    run_name='',
    snapshot_id='',
    job_id=None,
    params=None,
    repetitions=1,
    description=None,
    labels=None
)

Runs the program on the QuantumEngine.

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

Args
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.
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.
job_id Optional job id 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.
description An optional description to set on the 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 a processor id hasn't been specified to run the job
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(
    processor_id,
    *,
    device_config_name,
    run_name='',
    snapshot_id='',
    job_id=None,
    params=None,
    repetitions=1,
    description=None,
    labels=None
)

Runs the program on the QuantumEngine.

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

Args
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.
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.
job_id Optional job id 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.
description An optional description to set on the 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 a processor id hasn't been specified to run the job
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.

set_description

View source

set_description(
    description
)

Sets the description of the program.

Params
description The new description for the program.

Returns
This EngineProgram.

set_description_async

View source

set_description_async(
    description
)

Sets the description of the program.

Params
description The new description for the program.

Returns
This EngineProgram.

set_labels

View source

set_labels(
    labels
)

Sets (overwriting) the labels for a previously created quantum program.

Params
labels The entire set of new program labels.

Returns
This EngineProgram.

set_labels_async

View source

set_labels_async(
    labels
)

Sets (overwriting) the labels for a previously created quantum program.

Params
labels The entire set of new program labels.

Returns
This EngineProgram.

update_time

View source

update_time() -> datetime.datetime

Returns when the program was last updated.