RFC: results and observables

[jon-wurtz]

Once a kernel is executed using an interpreter, it must generate some data for analysis. There are only so many relevant data types, so we can start to lock in the basics. The big question is figuring out how to do observables-- returned quantum data lives in a basis hosted by qubits, which are possibly decontextualized from their definition within a kernel.

These results would come from execution of some job, aka

results = job.results()
results = context.run(kernel)
...

I propose thinking about extracting wavefunctions and other internal state as a "debug" mode. One can have a register, list of qubits, or wires as a return value, in which case an emulator can simply return the quantum state. But, the same piece of code should also be runnable on hardware, where you cannot return a state. So, I propose a debug dialect (like print statements one uses in python) that a simulator can use to log variables, such as classical or quantum variables.

@bloqade.kernel
def main():
    x = 1
    y = x + 1
    bloqade.debug.log(y,"message")
    reg = bloqade.circuit.qubits(2)
    bloqade.circuit.h(reg[0])
    bloqade.debug.log(reg,"register")

context = bloqade.runtime.debugger()
result = context.run(main) # {"message": 2, "register":reg:Wavefunction}

context = bloqade.runtime.statevector()
result = context.run(main) # wf:Wavefunction, the final wavefunction

There are two kinds of runtime values: ClassicalRuntimeValues, which are runtime values within the kernel, and QuantumRuntimeValues, which are wavefunctions, probability distributions or stochastic samples.

class ResultABC(ABC):
    """
    Base class for results to be fed into analysis.
    """

"""
Kernel Runtime Values are [classical] values that are instantiated
during execution of the kernel, and live in classical memory.
These can be returned when a kernel is run in a debug mode,
similar to how a print() statement is used, or when using a
debugger to step through a program to see the variables in context
"""
class ClassicalRuntimeValue(ResultABC):...   

"""
Kernel results are the things that are returned when running a kernel.
"""
@dataclass(frozen=True)
class KernelResult(ResultABC):
    _data: tuple[Any,...]
    @property
    def data(self)->tuple[Any,...]:
        return self._data
  
@dataclass(frozen=True) # Maybe just use qiskit / cirq etc.
class Qubit(ClassicalRuntimeValue):
    label: Any

@dataclass(frozen=True) # Maybe just use qiskit / cirq etc.
class Register(ClassicalRuntimeValue):
    qubits: list[Qubit]

"""
Quantum Runtime Values are quantum values that are instantiated
during execution of the kernel, and and live on the quantum processor.
These can be returned when a kernel is run in a debug mode,
similar to how a print() statement is used, or when using a
debugger to step through a program to see the variables in context.
"""
class QuantumRuntimeValue(ResultABC):...

@dataclass(frozen=True)
class ProbabilityFunction(QuantumRuntimeValue):
    _data: list[float]
    _basis:  list[Qubit]
    
    

@dataclass(frozen=True)
class BitstringResult(QuantumRuntimeValue):
    _data: list[list[int]]
    _basis:  list[list[Qubit]] | list[Qubit]
    
    
    def probability(self)->ProbabilityFunction:
        data = np.array(self._data)
        if len(data.shape)==2: # Number of qubits is consistent
            data = np.sum(data, axis=0)/data.shape[0]
            return ProbabilityFunction(_data = data, _basis = self._basis)
        else:
            raise ValueError("BitstringResult data is not a valid probability distribution")
            

@dataclass(frozen=True)
class Wavefunction(QuantumRuntimeValue):
    _data: np.ndarray
    _basis: list[Qubit]
    
    def sample(nsamples:int)->BitstringResult:
        """
        Sample from the wavefunction in the Z basis
        """
        raise NotImplementedError("Sampling has not been implemented")
    
    def apply(circuit:cirq.Circuit)->"Wavefunction":
        """
        Apply an abstract circuit to a wavefunction
        """
        raise NotImplementedError("Application of circuits has not been implemented")
    
    def expect(observable:Observable)->float:
        """
        Compute an expectation value with respect to some observable
        """
        
    def probability(self)->ProbabilityFunction:
        return ProbabilityFunction(_data = np.abs(self._data)**2, _basis = self._basis)
    
    def convert(self, target: qiskit.Wavefunction | cirq.Wavefunction | ...):
        """
        Convert the wavefunction to a different representation in another
        open source package.
        """



@dataclass(frozen=True)
class StochasticWavefunction(QuantumRuntimeValue):
    """
    A wavefunction sampled many times from different noise instantiations
    """
    _data: list[Wavefunction]
    
    def densitymatrix(self)->"DensityFunction":...


@dataclass(frozen=True)
class DensityFunction(QuantumRuntimeValue):
    _data:np.ndarray
    _basis:list[Qubit]

We can separate observables and expectation values, because they now are functions which QuantumRuntimeValue as input! This, of course, runs the risk of decoupling qubit labels with the statevector. There's no good way around this-- the statevector is not a true quantity of reality, so its on the user to manage matching qubit labels with the statevector. Nonetheless, the statevector should carry around its basis as an attribute; for 2^N statevector this can be as simple as a list of qubits, implicitly in the Z basis.

"""
Observables are tricky, as they require knowledge of the basis.
In principle this doesn't need any extra objects, by using functions
"""
 
# For example, observing X_2*Y_7 on qubit 3 could look like the following;
# observe that qubit3 and qubit7 have to be defined elsewhere
wf:Wavefunction = ...
qubit3:Qubit = ...
qubit7:Qubit = ...
wf.apply(cirq.X(qubit3)*cirq.Y(qubit7)) * wf # where * is a dot product

# This could have all sorts of happy helper functions, e.g.
def observable(observable:cirq.PauliString, wf:Wavefunction)->float:
    return wf.apply(observable) * wf
 
# Alternatively, observables could be their own object
class Observable:
    _paulis:str
    _qubits:list[Qubit]
    
    def expect(self,wavefunction:Wavefunction | StochasticWavefunction | DensityFunction)->float:
        return observable(self, wavefunction)


# A similar thing can apply to expectation values from data
def expectation_value(distribution:ProbabilityFunction, polynomial:list[tuple[float, list[Qubit]]])->float:
    """
    Compute the expectation value of a binary polynomial with respect to a probability distribution
    """
    raise NotImplementedError("Expectation value has not been implemented")

# Alternatively,
class BinaryPolynomial:
    _coefficients:list[float]
    _qubits:list[list[Qubit]]
    
    def expect(self, distribution:ProbabilityFunction)->float:
        return expectation_value(distribution, self._coefficients)
    
    def __plus__(self,other)->"BinaryPolynomial":...
    def __mul__(self,other)->"BinaryPolynomial":...
    def __sub__(self,other)->"BinaryPolynomial":...
    def __truediv__(self,other)->"BinaryPolynomial":...

This RFC can be seen as a MINIMAL working set for results. There can be much more here, such as helper functions that compute correlation functions, statistical distance, fidelity, and so forth. But they ultimately act on these basic classes. I am not sure if this fits the requirements of error correction-- maybe we can hash that out soon.

A key point to make here is that these data, when linked appropriately with an interpreter, can be part of the building blocks of much larger packages and code. These structures are the use case! I'm being intentionally vague as to how the interpreters generate these data; that's more of an implementation question. But, having a robust way to do emulations and simulation is critical... to be discussed...

[Roger-luo]

I don't think there should be result data structure - the kernel should just return what you write.

Given there's already a runtime can we not start from scratch and propose something based on the current runtime?

[Roger-luo]

IMO, I need to say I don't like this RFC if we are talking about result values, and if you want debug.log modifying the result/return value, you need to walk through my dead body.

To explain more why this is bad, for example, if one writes

@kernel
def main():
    qreg = qasm2.new(3)
    return qreg

this already indicates returning a register, we should not add new syntax like

bloqade.debug.log(reg,"register")

debug.log is always an I/O in ANY language design, we should not change the semantics here and make it means modifying the return value.

---

After taking a closer look, I think what you ACTUALLY want here is a way to pass logs (and whatever being printed into the log) back. I think we should settle #225 before heading into this. In this case, the logs and whatever side effects got captured on server side should be passed back as a piece of metadata instead of directly showing up in the result value. Otherwise it will mess up what the program means.

Instead of having return value being modified which breaks the semantics convention, a possible route is we can pass back the logs in metadata, and having it goes into logging module, then the server side log will be passed back to client nicely and integrate with all Python logging tools.

[Roger-luo]

A key point to make here is that these data, when linked appropriately with an interpreter, can be part of the building blocks of much larger packages and code. These structures are the use case! I'm being intentionally vague as to how the interpreters generate these data; that's more of an implementation question. But, having a robust way to do emulations and simulation is critical... to be discussed...

ok I missed this paragraph. I think current runtime has covered a large range of the use case above, we just need to make sure we can return the same thing from the server.

Basically, anything can be discussed further except modifying return values, that's a hard no for me.

[weinbe58]

This RFC can be seen as a MINIMAL working set for results. There can be much more here, such as helper functions that compute correlation functions, statistical distance, fidelity, and so forth. But they ultimately act on these basic classes. I am not sure if this fits the requirements of error correction-- maybe we can hash that out soon.

When you start to move stuff outside the kernel you now run into the issue where you have an interface that can't be supported by the machine by definition. I would focus future RFC's things like the list you have here: compute correlation functions, statistical distance, fidelity, and so forth.

[jon-wurtz]

@Roger-luo

Given there's already a runtime can we not start from scratch and propose something based on the current runtime?

Respectfully, all this means is that you wrote something without first considering requirements and use cases. We are writing a product for users, to be maximally useful for projects and development, not a tool that is maximally easy for the package developer. These requirements are very close to your proposed solution #226 .

The analysis functions are a use case that depends on the requirements of having unified, consistent, and interpretable results structures. Just dumping some numpy array completely decontextualizes the data in a really bad way. At least having a qubit and register runtime value gives some notion of a basis.

The fundamental problem with extracting (exact) expectation values and wavefunctions is that they are functionally unphysical. We agreed in #218 to have the wavefunction and observables float around outside the kernel, instead of requiring a new set of dialects that include representing shots. We could do another RFC on exactly how we can do simulation and wavefunctions in more complicated scenarios, such as mid-circuit feed-forward, or when you want to collect the wavefunction at multiple places along the execution.

Whether the richer analysis is sugaring kernels with logs, or some other method, having the ability to extract the action of the program with a particular simulator backend is a good use case to enable users to understand the action of their programs. An MVP could be a simulator that simply extracts the wavefunction at the end (how?? a user must do measurements??) and the user must have different kernels for machine submission vs. simulation.

[weinbe58]

all this means is that you wrote something without first considering requirements and use cases

You need to give concrete examples of what requirements are missing, can you provide a use case that isn't covered by the previous RFC?

[jon-wurtz]

Requirement: consistent, reproducible, and extensible representation and generation of data and results produced from the execution of (quantum) kernels. Beyond top-level representations, it becomes implementation details.

Use cases: Integration into larger workflows beyond the scope of bloqade APIs, as well as an ensemble of analysis and helper functions such as cross-entropy, fidelity, averaging, expectation values, and so forth.

To narrow the focus, perhaps we should consider the output of the state-vector simulation. I proposed something here and in #230 but to just dump a numpy vector is inadequate.

[weinbe58]

concrete examples please

e.g.

as well as an ensemble of analysis and helper functions such as cross-entropy, fidelity, averaging, expectation values, and so forth.

expectation values

So we covered this in a previous rfc and everyone seems to agree it works

cross-entropy

cross-entropy between what and what? give an examples. Presumably, you would need to run the kernel on hardware to really get the most out of this but I could imagine you could do simulations with the noise model.

fidelity

fidelity concerning what? what are the states, and where do they come from? What if you run a stabilizer simulation using PyQrack how does this help you? How does this work with STIM or other backends? How do you deal with atoms that have been lost when sampling using the atom loss model?