Measurement Results Refactor

Is your design idea/issue related to a use case or problem? Please describe. Based on the #3808, #3233, #3785 and other discussion around changing the measurement Results, proposing some high-level design ideas below for discussion. Once a consensus is reached, this will be developed into an RFC.

Names below are only descriptive, final names might be better.

Describe your design idea/issue

Proposal based on inheritance (inheritance was decided in Cirq Cynque):

• AbstractResults interface
  • Would have measurement_dict, flat_measurements, dataframe (not data) accessors.
    • Implemented as lazily evaluated properties in the concrete classes
• KeyedResults Interface inherits from AbstractResults
  • Natively tracks the measurement keys
  • Has from_flat_measurements method that also needs key -> index_list mapping (can be computed from the circuit)
• QuditResults Interface inherits from AbstractResults
  • Stores measurements as qudits (including qubits)
  • [maybe] Has from_iq_points method that also needs some form of distribution/separation boundaries in IQ-space.
• class MeasurementDictResults(KeyedResults, QuditResults)
  • [tangential] The current Dict will change considering nested and repeated CircuitOperations. We will add tuple measurement keys
    • Dict might evolve into a more hierarchical tree structure if we want to automatically group at higher CircuitOperation levels
• class FlatMeasurementResults(QuditResults)
  • Discussed in #3808. Note that this doesn’t inherit from KeyedResults.
• class PandasResults(KeyedResults, QuditResults)
  • Almost always costlier except when user wants to interact with Pandas for convenience
  • The structure of the DataFrame might also change based on the above changes in the Measurement Dict.
• class IQPointsResults/RawResults(KeyedResults)
  • If we decide not to pursue IQ Points right now, QuditResults interface can also be removed.
  • These is a fundamentally different and a higher dimensional data. IQ Points can be converted to any of the types above (given the boundaries to use), but not the other way round.

Strategy pattern (built on another suggestion in #3808 and much simpler):

• Define a MeasurementStorageStrategy enum
• Instead of all the inheritance, pass this enum to the current Results class
• Results will use this enum to determine what data structure to use for native measurement storage
• Accessors for other storage types are still available as lazily evaluated properties.
  • Since we’ll need different logic for different strategies, this implementation will be longer than the inheritance above, but no more complex.

[Future work/Classical data] Take in MeasurementKey->ClassicalRegister mapping to populate classical data during the run in addition to populating the native data structure. FlatMeasurementResults might take an Index->ClassicalRegister mapping

[mpharrigan]

cc @maffoo I think we’ve made the critical change of moving Result to an abstract base class. Going to mark this as “after-1.0” since we’ve done the backwards-compatibility-concern part

[maffoo]

+1 from me to close this and file separate issues for additional specialized result types if needed.