cirq_google.engine.SimulatedLocalProcessor

A processor backed by a sampler and device.

Inherits From: AbstractLocalProcessor, AbstractProcessor

cirq_google.engine.SimulatedLocalProcessor(
    *args,
    sampler: cirq.Sampler = cirq.Simulator(),
    device: cirq.Device = cirq.UNCONSTRAINED_DEVICE,
    validator: Optional[cirq_google.engine.engine_validator.VALIDATOR_TYPE] = None,
    program_validator: Optional[cirq_google.engine.engine_validator.PROGRAM_VALIDATOR_TYPE] = None,
    simulation_type: cirq_google.engine.local_simulation_type.LocalSimulationType = cirq_google.engine.local_simulation_type.LocalSimulationType.SYNCHRONOUS,
    calibrations: Optional[Dict[int, calibration.Calibration]] = None,
    device_specification: Optional[cirq_google.api.v2.device_pb2.DeviceSpecification] = None,
    **kwargs
)

Intended for local simulation testing, this processor will create a ValidationSampler that will validate requests based on the provided device and an additional Callable (that can verify serialization constraints, for instance). Jobs will then be executed using the provided sampler.

This class also supports a list of calibration metrics that are stored in-memory to replicate Quantum Engine calibration metrics.

This class can be used as a local emulator for the Quantum Engine API or for testing or mocking.

sampler A cirq.Sampler that can execute the quantum jobs.
device An optional device, for validation of qubit connectivity.
validator A Callable that can validate additional characteristics beyond the device, such as serialization, repetition limits, etc.
gate_set_validator A callable that can validate a circuit and sweeps based on the given serializer.
simulation_type Whether sampler execution should be synchronous or asynchronous.
calibrations A dictionary of calibration metrics keyed by epoch seconds that can be returned by the processor.
processor_id Unique string id of the processor.
engine The parent AbstractEngine object, if available.
expected_down_time Optional datetime of the next expected downtime. For informational purpose only.
expected_recovery_time Optional datetime when the processor is expected to be available again. For informational purpose only.
schedule List of time slots that the scheduling/reservation should use. All time slots must be non-overlapping.
project_name A project_name for resource naming.
device_specification aDeviceSpecification proto that the processor should return if get_device_specification() is queried.
project_id Project name of the processor.

Methods

create_reservation

View source

create_reservation(
    start_time: datetime.datetime,
    end_time: datetime.datetime,
    whitelisted_users: Optional[List[str]] = None
) -> cirq_google.cloud.quantum.QuantumReservation

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

Raises
ValueError if start_time is after end_time.

engine

View source

engine() -> Optional['AbstractEngine']

Returns the parent Engine object.

Returns
The program's parent Engine.

Raises
ValueError if no engine has been defined for this processor.

expected_down_time

View source

expected_down_time() -> 'Optional[datetime.datetime]'

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

expected_recovery_time

View source

expected_recovery_time() -> 'Optional[datetime.datetime]'

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

get_calibration

View source

get_calibration(
    calibration_timestamp_seconds: int
) -> cirq_google.engine.Calibration

Retrieve metadata about a specific calibration run.

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

Returns
The calibration data.

get_current_calibration

View source

get_current_calibration() -> Optional[cirq_google.engine.Calibration]

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 cirq.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.Device that will validate that operations are supported and use the correct qubits.

get_device_specification

View source

get_device_specification() -> Optional[cirq_google.api.v2.device_pb2.DeviceSpecification]

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

Returns
Device specification proto if present.

get_latest_calibration

View source

get_latest_calibration(
    timestamp: int
) -> Optional[cirq_google.engine.Calibration]

Returns the latest calibration with the provided timestamp or earlier.

get_program

View source

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

Returns an AbstractProgram for an existing Quantum Engine program.

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

Returns
An AbstractProgram for the program.

Raises
KeyError if program is not found

get_reservation

View source

get_reservation(
    reservation_id: str
) -> Optional[cirq_google.cloud.quantum.QuantumReservation]

Retrieve a reservation given its id.

get_sampler

View source

get_sampler(
    run_name: str = '', device_config_name=''
) -> cirq_google.engine.ProcessorSampler

Returns a sampler backed by the processor.

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.

get_schedule

View source

get_schedule(
    from_time: Union[None, datetime.datetime, datetime.timedelta] = datetime.timedelta(),
    to_time: Union[None, datetime.datetime, datetime.timedelta] = datetime.timedelta(weeks=2),
    time_slot_type: Optional[cirq_google.cloud.quantum.QuantumTimeSlot.TimeSlotType] = None
) -> List[cirq_google.cloud.quantum.QuantumTimeSlot]

Retrieves the schedule for a processor.

The schedule may be filtered by time.

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
Time slots that fit the criteria.

health

View source

health()

Returns the current health of processor.

list_calibrations

View source

list_calibrations(
    earliest_timestamp: Optional[Union[datetime.datetime, datetime.date, int]] = None,
    latest_timestamp: Optional[Union[datetime.datetime, datetime.date, int]] = None,
    **kwargs
) -> List[cirq_google.engine.Calibration]

Retrieve metadata about a specific calibration run.

Args
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_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.AbstractLocalProgram]

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 before 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_reservations

View source

list_reservations(
    from_time: Union[None, datetime.datetime, datetime.timedelta] = datetime.timedelta(),
    to_time: Union[None, datetime.datetime, datetime.timedelta] = datetime.timedelta(weeks=2)
) -> List[cirq_google.cloud.quantum.QuantumReservation]

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_program

View source

remove_program(
    program_id: str
)

Remove reference to a child program.

remove_reservation

View source

remove_reservation(
    reservation_id: str
) -> None

Removes a reservation on this processor.

run

View source

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

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.
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.
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 single Result for this run.

run_async

View source

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

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.
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.
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 single Result for this run.

run_sweep

View source

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

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. 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. 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: 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,
    program_id=None,
    job_id=None,
    params=None,
    repetitions=1,
    program_description=None,
    program_labels=None,
    job_description=None,
    job_labels=None,
    run_name='',
    device_config_name=''
)

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. 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. 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: An AbstractJob. If this is iterated over it returns a list of cirq.Result, one for each parameter sweep.

set_engine

View source

set_engine(
    engine
)

Sets the parent processor.

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: Optional[datetime.datetime] = None,
    end_time: Optional[datetime.datetime] = None,
    whitelisted_users: Optional[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.

Args
reservation_id The string identifier of the reservation to change.
start_time New starting time of the reservation. If unspecified, starting time is left unchanged.
end_time New ending time of the reservation. If unspecified, ending time is left unchanged.
whitelisted_users The new list of whitelisted users to allow on the reservation. If unspecified, the users are left unchanged.

Raises
ValueError if reservation_id does not exist.