Refactor get sampler

[dyates]

Fixes bug 435217087. Refactor get_sampler and adds the functions get_sampler_from_run_name and get_sampler_from_snapshot_id

get_sampler: This function no longer requires or accepts run_name and snapshot_id

sampler = engine.get_sampler(processor_id='proc_id', device_config_name='test_alias')
another_sampler = engine.get_sampler(processor_id='proc_id')

get_sampler_from_run_name:

sampler = engine.get_sampler_from_run_name( 
    processor_id='proc_id', run_name='current', device_config_name='test_alias'
)

processor = engine.get_processor('proc_id')
another_sampler = processor.get_sampler_from_run_name( 
    processor_id='proc_id', run_name='current', device_config_name='test_alias'
)

get_sampler_from_snapshot_id:

sampler = engine.get_sampler_from_snapshot_id( 
    processor_id='proc_id', snapshot_id='test_snapshot', device_config_name='test_alias'
)

processor = engine.get_processor('proc_id')
another_sampler = processor.get_sampler_from_snapshot_id(
    processor_id='proc_id', snapshot_id='test_snapshot_id', device_config_name='test_alias'
)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.37%. Comparing base (413aee6) to head (3c019ac).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7672   +/-   ##
=======================================
  Coverage   99.37%   99.37%           
=======================================
  Files        1082     1082           
  Lines       96708    96750   +42     
=======================================
+ Hits        96101    96144   +43     
+ Misses        607      606    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[wcourtney]

This removes what I would expect to be the most common use case: specify only a device config name, but not the version (run or snapshot).

@eliottrosenberg - do we really want to support a default config name ("config alias") at all? While defaults make sense to get the "latest" version, a default grid seem more risky and I think are worth forcing explicit selection.

[wcourtney]

The methods in Engine are intended to be easy-to-remember convenience helpers and I'm concerned that over-specialization makes these less usable and more painful to maintain. e.g., if we add another feature with 2 ways to construct a sampler and follow this pattern, these 3 functions will turn into 6 new functions with very long names.

The style guide suggests that defaults are useful to avoid "lots of functions for the rare exceptions", and @eliottrosenberg made it sound like these specialized versions are exceptional.

Would it suffice to just check for mutual exclusivity of the arguments and raise an exception if that's violated? Alternatively, if you find it important to bake this check into the interface, you could alternatively do it with the type system, e.g.:

@dataclass
class Snapshot:
  id: str

@dataclass
class Run:
  id: str

type DeviceVersion = Snapshot | Run

class Engine
  ...
  def get_sampler(
     self,
     processor_id: str | list[str],
     device_config_name: str,
     device_version: DeviceVersion | None = None,
     max_concurrent_jobs: int = 100,
  ) -> cirq_google.ProcessorSampler:
  ...

WDYT?

[wcourtney]

Could this be simplified by adding a sampler() method on ProcessorConfig? The equivalent of .get_sampler_from_run_name(...) would then be .get_config_from_run_name(...).sampler(). As a bonus, this form localizes scope of each resource configuration, e.g. expanded:

sampler = (
    engine.get_processor('willow_123')
        .get_config_from_run(run_name='current', config_name='some_cool_grid')
        .sampler()
)

This or something like it should probably the the canonical form of retrieval because a sampler should always refer to a fully-qualified config even if the user used defaults to construct it.

[wcourtney]

Following on from the above comment regarding the requirement of a device config to build a sampler, should we remove get_sampler from the processor and instead rely on explicitly grabbing the default configuration to generate the sampler?