Add QuantumProgram and related classes

[SamFerracin]

Summary

This PR:

• Adds a version of QuantumProgram and related classes copy-pasted from qiskit-ibm-runtime
• Adds all the tests currently present for those classes
• Improves the description samplomatic/quantum_program/__init__.py
• Adds the module to the public documentation

Closes #395

[ihincks]

Thanks @SamFerracin. The main reason for moving this here is to support an ecosystem of tools that treats the concept of a QuantumProgram in a way that is agnostic to the implementation behind it, whether it be IBM hardware, a simulator, or some other provider. Then other packages can depend on this concept without having to depend on qiskit-ibm-runtime.

However, this PR currently brings over some concepts that I would have guessed were specifically related to IBM Quantum Compute: SchedulerTiming, StretchValues, ChunkTimings. This is related to your comment about the drawer.

So then my question is: do you view these things as fundametally part of the concept of a QuantumProgram which all tools should be able to assume exist, or did you bring them over for the convenience of qiskit-ibm-runtime not having to specialize them?

[SamFerracin]

However, this PR currently brings over some concepts that I would have guessed were specifically related to IBM Quantum Compute: SchedulerTiming, StretchValues, ChunkTimings.

That is a fair point. Let me think about the implications of not bringing them over, and I'll update the PR.

I guess the alternative would be to simply bring over QuantumProgramResult(s)--which will be needed for type hinting, for example--with a generic metadata field?

[ihincks]

What I was getting at by specializations was specifically this pattern:

from samplomatic import QuantumProgramResult

class IBMQuantumProgramResult(QuantumProgramResult):
    def scheduler_timings(self) -> SchedulerTimings:
        ....

    ....

Anything that wants to write generically against QuantumProgram/Result can do so, and IBMQuantumProgramResult will work just as well as QuantumProgramResult for them, assuming IBMQuantumProgramResult takes subtype polymorphism seriously and doesn't get tempted by shenanigans. Additionally, any user of IBMQuantumProgramResult gets access to IBM specific goodies. It also gives a mechanism for simulator returns to be different than hardware returns.

[SamFerracin]

On a similar note, I'll remove semantic roles and meas level as well

[ihincks]

Thanks @SamFerracin.

Could we please import the quantum_program module in the the main samplomatic init file, too? For now, though, I would not pull any objects into the main namespace.

[ihincks]

Do you plan on subclassing this in qiskit-ibm-runtime? Right now it adds the sugar for timing information.

[SamFerracin]

Yes, I plan on subclassing and adding the sugar in runtime, see this diff. Which should match what we discussed, but lmk if I misinterpreted

[ihincks]

Docstring claims a dictionary. Although, depending on how the previous question goes, we might consider removing this, and the one in the item class.

Suggested change

	metadata: Any = None,
	metadata: dict[str, Any] | None = None,

[SamFerracin]

Fixed: cacf02f

Although, depending on how the previous question goes, we might consider removing this, and the one in the item class.

I see.. Yeah, I am not against that.. Metadata is a concept that's general enough to live in Samplomatic. At the same time, if it's type-hinted as Any, perhaps it doesn't buy anything and it can just leave in the subclass

[ihincks]

We should probably add some tests for the result class, too.

[SamFerracin]

965cdbc

[SamFerracin]

@ihincks added to the init: 73a83e0