cirq_google.engine.EngineProcessor

A processor available via the Quantum Engine API.

Inherits From: AbstractProcessor

cirq_google.engine.EngineProcessor(
    project_id: str,
    processor_id: str,
    context: engine_base.EngineContext,
    _processor: (quantum.QuantumProcessor | None) = None
) -> None

project_id A project_id of the parent Google Cloud Project.
processor_id Unique ID of the processor.
context Engine configuration and context to use.
_processor The optional current processor state.

project_id A project_id of the parent Google Cloud Project.
processor_id Unique ID of the processor.

Methods

create_reservation

View source

create_reservation(
    start_time: datetime.datetime,
    end_time: datetime.datetime,
    allowlisted_users: (list[str] | None) = None
)

Creates a reservation on this processor.

Args
start_time the starting date/time of the reservation.
end_time the ending date/time of the reservation.
allowlisted_users a list of emails that are allowed to send programs during this reservation (in addition to users with permission "quantum.reservations.use" on the project).

engine

View source

engine() -> engine_base.Engine

Returns the parent Engine object.

Returns
The program's parent Engine.

expected_down_time

View source

expected_down_time() -> (datetime.datetime | None)

Returns the start of the next expected down time of the processor, if set.

expected_recovery_time

View source

expected_recovery_time() -> (datetime.datetime | None)

Returns the expected the processor should be available, if set.

get_calibration

View source

get_calibration(
    calibration_timestamp_seconds: int
) -> calibration.Calibration

Retrieve metadata about a specific calibration run.

Params
calibration_timestamp_seconds The timestamp of the calibration in seconds since epoch.

Returns
The calibration data.

get_current_calibration

View source

get_current_calibration() -> (calibration.Calibration | None)

Returns metadata about the current calibration for a processor.

Returns
The calibration data or None if there is no current calibration.

get_device

View source

get_device() -> cirq.Device

Returns a Device created from the processor's device specification.

This method queries the processor to retrieve the device specification, which is then use to create a cirq_google.GridDevice that will validate that operations are supported and use the correct qubits.

get_device_specification

View source

get_device_specification() -> (v2.device_pb2.DeviceSpecification | None)

Returns a device specification proto for use in determining information about the device.

Returns
Device specification proto if present.

get_reservation

View source

get_reservation(
    reservation_id: str
) -> (quantum.QuantumReservation | None)

Retrieve a reservation given its id.

get_sampler

View source

get_sampler(
    run_name: str = '',
    device_config_name: str = '',
    snapshot_id: str = '',
    max_concurrent_jobs: int = 10
) -> cg.engine.ProcessorSampler

Returns a sampler backed by the engine.

Args
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.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor.
max_concurrent_jobs The maximum number of jobs to be sent simultaneously 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 only one of run_name and device_config_name are specified.
ValueError If both run_name and snapshot_id are specified.

get_schedule

View source

get_schedule(
    from_time: (None | datetime.datetime | datetime.timedelta) = datetime.timedelta(),
    to_time: (None | datetime.datetime | datetime.timedelta) = datetime.timedelta(weeks=2),
    time_slot_type: (quantum.QuantumTimeSlot.TimeSlotType | None) = None
) -> list[quantum.QuantumTimeSlot]

Retrieves the schedule for a processor.

The schedule may be filtered by time.

Time slot type will be supported in the future.

Args
from_time Filters the returned schedule to only include entries that end no earlier than the given value. Specified either as an absolute time (datetime.datetime) or as a time relative to now (datetime.timedelta). Defaults to now (a relative time of 0). Set to None to omit this filter.
to_time Filters the returned schedule to only include entries that start no later than the given value. Specified either as an absolute time (datetime.datetime) or as a time relative to now (datetime.timedelta). Defaults to two weeks from now (a relative time of two weeks). Set to None to omit this filter.
time_slot_type Filters the returned schedule to only include entries with a given type (e.g. maintenance, open swim). Defaults to None. Set to None to omit this filter.

Returns
Schedule time slots.

health

View source

health() -> str

Returns the current health of processor.

list_calibrations

View source

list_calibrations(
    earliest_timestamp: (datetime.datetime | datetime.date | int | None) = None,
    latest_timestamp: (datetime.datetime | datetime.date | int | None) = None
) -> list[calibration.Calibration]

Retrieve metadata about a specific calibration run.

Params
earliest_timestamp The earliest timestamp of a calibration to return in UTC.
latest_timestamp The latest timestamp of a calibration to return in UTC.

Returns
The list of calibration data with the most recent first.

list_reservations

View source

list_reservations(
    from_time: (None | datetime.datetime | datetime.timedelta) = datetime.timedelta(),
    to_time: (None | datetime.datetime | datetime.timedelta) = datetime.timedelta(weeks=2)
) -> list[quantum.QuantumTimeSlot]

Retrieves the reservations from a processor.

Only reservations from this processor and project will be returned. The schedule may be filtered by starting and ending time.

Args
from_time Filters the returned reservations to only include entries that end no earlier than the given value. Specified either as an absolute time (datetime.datetime) or as a time relative to now (datetime.timedelta). Defaults to now (a relative time of 0). Set to None to omit this filter.
to_time Filters the returned reservations to only include entries that start no later than the given value. Specified either as an absolute time (datetime.datetime) or as a time relative to now (datetime.timedelta). Defaults to two weeks from now (a relative time of two weeks). Set to None to omit this filter.

Returns
A list of reservations.

remove_reservation

View source

remove_reservation(
    reservation_id: str
)

Removes a reservation on this processor.

run

View source

run(
    program,
    *,
    device_config_name,
    run_name='',
    snapshot_id='',
    program_id=None,
    job_id=None,
    param_resolver=None,
    repetitions=1,
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None
)

Runs the supplied Circuit on this processor.

Args
program The Circuit to execute. If a circuit is provided, a moment by moment schedule will be used.
run_name A unique identifier representing an automation run for the processor. An Automation Run contains a collection of device configurations for the processor. snapshot_id and run_name should not both be set. Choose one.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor. snapshot_id and run_name should not both be set. Choose one.
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.
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.

Returns
A single Result for this run.

run_async

View source

run_async(
    program,
    *,
    device_config_name,
    run_name='',
    snapshot_id='',
    program_id=None,
    job_id=None,
    param_resolver=None,
    repetitions=1,
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None
)

Runs the supplied Circuit on this processor.

Args
program The Circuit to execute. If a circuit is provided, a moment by moment schedule will be used.
run_name A unique identifier representing an automation run for the processor. An Automation Run contains a collection of device configurations for the processor. snapshot_id and run_name should not both be set. Choose one.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor. snapshot_id and run_name should not both be set. Choose one.
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.
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.

Returns
A single Result for this run.

run_sweep

View source

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

Runs the supplied Circuit on this processor.

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. 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. snapshot_id: A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor. Both snapshot_id and run_name should not be set. 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.

Returns
An AbstractJob. If this is iterated over it returns a list of cirq.Result, one for each parameter sweep.

run_sweep_async

View source

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

Runs the supplied Circuit on this processor.

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.
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.
snapshot_id A unique identifier for an immutable snapshot reference. A snapshot contains a collection of device configurations for the processor.
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.

Returns
An AbstractJob. If this is iterated over it returns a list of cirq.Result, one for each parameter sweep.

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

supported_languages

View source

supported_languages() -> list[str]

Returns the list of processor supported program languages.

update_reservation

View source

update_reservation(
    reservation_id: str,
    start_time: (datetime.datetime | None) = None,
    end_time: (datetime.datetime | None) = None,
    allowlisted_users: (list[str] | None) = None
)

Updates a reservation with new information.

Updates a reservation with a new start date, end date, or list of additional users. For each field, it the argument is left as None, it will not be updated.