cirq.Collector

Collects data from a sampler, in parallel, towards some purpose.

Child classes must override the next_job and on_job_result methods, which respectively determine what to sample and how to process the results. Utility methods on the base class such as collect and collect_async can then be given a sampler to collect from, and will request samples with some specified amount of parallelism.

Methods

collect

View source

collect(
    sampler: 'cirq.Sampler',
    *,
    concurrency: int = 2,
    max_total_samples: Optional[int] = None
) -> None

Collects needed samples from a sampler.

Examples

collector = cirq.PauliStringCollector(...)
sampler.collect(collector, concurrency=3)
print(collector.estimated_energy())

Args
sampler The simulator or service to collect samples from.
concurrency Desired number of sampling jobs to have in flight at any given time.
max_total_samples Optional limit on the maximum number of samples to collect.

Returns
The collector's result after all desired samples have been collected.

collect_async

View source

collect_async(
    sampler, *, concurrency=2, max_total_samples=None
)

Asynchronously collects needed samples from a sampler.

Examples

collector = cirq.PauliStringCollector(...)
await sampler.collect_async(collector, concurrency=3)
print(collector.estimated_energy())

Args
sampler The simulator or service to collect samples from.
concurrency Desired number of sampling jobs to have in flight at any given time.
max_total_samples Optional limit on the maximum number of samples to collect.

Returns
The collector's result after all desired samples have been collected.

next_job

View source

@abc.abstractmethod
next_job() -> Optional[CIRCUIT_SAMPLE_JOB_TREE]

Determines what to sample next.

This method is called by driving code when more samples can be requested.

Returns
A CircuitSampleJob describing the circuit to sample, how many samples to take, and a key value that can be used in the on_job_result method to recognize which job this is.

Can also return a nested iterable of such jobs.

Returning None, an empty list, or any other result which flattens into an empty list of work, indicates that the driving code should await more results (and pass them into on_job_results) before bothering to ask for more jobs again.

on_job_result

View source

@abc.abstractmethod
on_job_result(
    job: cirq.CircuitSampleJob,
    result: cirq.Result
) -> None

Incorporates sampled results.

This method is called by driving code when sample results have become available.

The results should be incorporated into the collector's state.