Add Counts object

[mtreinish]

Summary

This commit adds a new class qiskit.result.Counts which is a dict
subclass for dealing with count results from experiment. It takes in a
counts dictionary with hexadecimal string keys and it's data is a binary
string, like the output of get_counts(). The idea is that this class
contains extra attributes about the execution and helper methods for
interacting with counts results. It can be used as a direct replacement
anywhere a counts dictionary was used previously. It is also now the
return type for qiskit.quantum_info.QuantumState.sample_counts().

This commit is part of the v2 providers interface work and will be a key
part of the new providers interface. This class is split out as a
seperate commit/PR from #4485.

Details and comments

[ajavadia]

can you add tests for the two methods int_outcomes and most_frequent?

Also how does Counts object print? Does it need a __str__ or __repr__? Mainly because right now it is straightforward to see the counts and that behavior should persist.

[mtreinish]

Oh, oops I wrote tests but forgot to add it to the commit. Fixed in: f433cbd

[mtreinish]

As for the printing it will work exactly the same as the dict does from Result.get_counts() (assuming you pass in the classical register and memory slots as kwargs). There's no need to add a __str__ or __repr__ since this class is essentially just a dict that does the post-processing up front at object init and has a few extra helpers.

[chriseclectic]

Why are we storing a lot of extra metadata in this container? There is already an ExperimentResult class for that so it seems to me Counts should just be the counts part of the result.

If I want to add additional return data types in the future (which I do!) like ExpectationValue, or Probabilities, there will be a lot of duplication of unneeded metadat.

In this case I think the only the counts needs is perhaps the creg_sizes so you can add whitespace to bitstrings during conversion, and memory_slots if you don't have creg_sizes so you know number of bits when converting from hex-format. Shots can be inferred from sum of dict elements, and time taken, name, and metadata seem unnecessary.

[mtreinish]

The metadata here is used in the v2 providers interface see #4485. In that model the results object will return an OrderedDict of Counts objects instead of a of ExperimentResult objects. So the metadata for an individual run will be stored here.

[chriseclectic]

I guess I have issues with the V2 provider then, since it will not be suitable for simulators if there is no circuit level result object other than counts that can store different output data. I can leave those comments somewhere else.

[chriseclectic]

Accidentally submitted before writing my main comment in the review. My main issue with this is if we are adding a class abstract why are we forcing ourselves to use the hex-string format when initializing. Regardless of what internal representation this class uses to store counts I think it should be able to be initialized from hex string counts, binary string counts, or integer key counts, and also apply conversion to any of these formats from whatever format it was initialized (you have one method for this for converting to int keys).

[chriseclectic]

Another issue is that the counts from QuantumState aren't always bitstrings. They can be any dit string because they allow arbitrary dimension qudit subsystems. For example:

state = qi.Statevector([1, 1, 1, 1, 1, 1, 1, 1, 1], dims=[3,3]) / 3
state.sample_counts(1000)

will return {'00': 121, '01': 109, '02': 114, '10': 113, '11': 106, '12': 114, '20': 117, '21': 104, '22': 102}

[mtreinish]

Accidentally submitted before writing my main comment in the review. My main issue with this is if we are adding a class abstract why are we forcing ourselves to use the hex-string format when initializing. Regardless of what internal representation this class uses to store counts I think it should be able to be initialized from hex string counts, binary string counts, or integer key counts, and also apply conversion to any of these formats from whatever format it was initialized (you have one method for this for converting to int keys).

This is a fair point I was thinking about doing this, but kept it simple. I'll work on adding the arbitrary conversions between the 3 forms. The default data format will still have to be the bitstrings for backwards compat with v2

Another issue is that the counts from QuantumState aren't always bitstrings. They can be any dit string because they allow arbitrary dimension qudit subsystems. For example:

state = qi.Statevector([1, 1, 1, 1, 1, 1, 1, 1, 1], dims=[3,3]) / 3
state.sample_counts(1000)

will return {'00': 121, '01': 109, '02': 114, '10': 113, '11': 106, '12': 114, '20': 117, '21': 104, '22': 102}

I actually think this will work as is today. Right now it calls result.postprocess.format_counts on the input which will only do anything if the string starts with 0x or creg_sizes and/or memory_slots are set. The helper methods will fail because Counts.hex_raw keys will be qudit strings instead of hex strings, but the Counts object will work fine as the dict is being used today. That being said I'll try to handle this in the next revision too.

[nonhermitian]

I actually like the metadata. Much easier to access than from the Results. Also nice since direct access to the results is something we are moving away from.

[chriseclectic]

I suggest removing all the non-count related metadata from the Counts class in this PR until we discuss more under the V2 provider, other than that this looks good. This way we can merge it as a replacement for the current dict returned by get_counts until other things are agreed on.