Serializable parametric pulse

[nkanazawa1989]

Summary

This is overhaul of qiskit.pulse.library.parametric_pulse. This is necessary for QPY support of pulse schedules.

Background

QPY mechanism allows us to serialize Qiskit programs with better backward compatibility. Currently this only supports QuantumCircuit but we should support ScheduleBlock and Schedule for:

1. Serialization of QuantumCircuit.calibrations
2. Serialization of calibration schedules in the QiskitExperiments

These pulse programs are made of pulse instructions, such as Play, ShiftPhase, ShiftFrequency, etc... and they take instruction operands and channels. These objects should be serializable, however, the Pulse instance that is an operand of the Play instruction cannot be serialized in every situation. See the discussion here for details.

The Pulse instruction has two classes, Waveform and ParametricPulse, and the pulse library defines four sub-classes Gaussian, GaussianSquare, Drag, and Constant. IBM Quantum backends define the same classes, and we just need to submit only parameter values and pulse type information through the communication layer. This drastically saves data volume we need to transmit over the internet. However this mechanism is not scalable and has several downsides.

• Experimentalist should commit to both Qiskit and IBM Quantum system compiler if they want to use new pulse definition. If definition is not found, it falls back into Waveform. Because this is just a sequence of complex data points, we are no longer able to infer raw parameter values, such as amp, phase, etc... which is quite important in the context of system monitoring and maintenance. Also this yields significant increase of data volume and hurts performance of could computing. Note that we are already lacking the definition of DDCX pulse in Qiskit.
• In QiskitExperiments, the calibration database is implemented as an RDB consisting of one for parameter values and another one for fully parametrized schedules. This separation drastically saves data volume in the long run because each calibration attempt just registers a single parameter value entry in the database, rather than full pulse schedule with updated parameter. This means, all schedule should be serializable as ParametricPulse, to make the database serializable. Again, if Qiskit doesn't support a particular pulse shape, an experimentalist must commit to Qiskit with new pulse shape. This may unnecessarily expose IP before publication or invention disclosure (if one will).
• There is no valid mechanism for testing round-trip waveform generation. Since there is no guarantee we have the same waveform samples both on front-end and back-end, it might cause discrepancy in the pulse simulation and real backend execution due to bug on one end or code version difference. The end users have no opportunity to investigate.

To overcome, every ParametricPulse subclass should be serializable even though it is not defined in Qiskit.

Challenges

1. All ParametricPulse must define get_waveform method. When this method is called, an instance should generate numpy array of waveform with instance's pulse parameters. Currently, the program to generate waveform is hard-coded there. Note that, in general, serialization of arbitrary python callback is tough challenge.

2. All ParametricPulse must define validate_parameters method. This is called at the constructor when all parameters are bound. This should raise an error if there is a risk of invalid waveform generation. For example, if maximum value of the waveform exceeds 1.0, it raises an PulseError. Note that this is also a set of callables.

https://github.com/Qiskit/qiskit-terra/blob/main/qiskit/pulse/library/parametric_pulses.py

New mechanism

Here we use Sympy symbolic expression instead of callables. These symbolic expressions are usually serializable, thus we should be able to QPY serialize full pulse schedule containing fancy pulses under the research. The upgraded ParametricPulse implementation conforms to that of circuit Gate structure.

class ParametricPulse:
    definition = None
    constraints = None

    @classmethod
    def _define(cls):    # generate sympy Expr for waveform definition
        pass

    @classmethod
    def _constraints(cls):    # generate sympy Expr for waveform validation
        pass

The class definition and constraints are initialized at __init_subclass__ method when the class is initialized with lambdify. Because in typical pulse programs, the same waveform are repeatedly used with different parameters (for different qubits), it is important to cache the lambda functions without having parameters assigned at the class level. Usually the waveform generation with symbolic equation is heavy computing overhead without lambdify. This is due to long waveform samples and complexity of equation. This often hurts visualization of schedules, where we need to convert all ParametricPulses to Waveform. @wshanks investigated this mechanism carefully and optimized. Now the overhead of waveform visualization is almost comparable to one in the main branch.

Co-authored-by: Will Shanks willshanks@us.ibm.com

TODO

• Release note
• Unittests overhaul
• Bug fix of Drag pulse validation when beta=0 (see ITE evaluates all args at the same time sympy/sympy#23295)
• Consideration of symengine (we had long discussion but I dropped with c4b41d5 owing to the inconsistent behavior in Boolean logic)
• Remove notebook

In follow-up

• Replace Qobj with QPY serialization (so that we can define every backend pulses as ParametricPulse, e.g. DDCX)
• Update QPY schedule PR QPY schedule serialization #7300

[CLAassistant]

All committers have signed the CLA.

[mtreinish]

This needs to be a runtime import to avoid an import performance regression when the parametric_pulses module gets imported.

[wshanks]

One thing to note -- ParametricPulse.__init_subclass__ uses lambdify_symbolic_pulse which uses some sympy functions. So even if the sympy usage was shifted to look like it was a run time import, sympy would still get imported when this module is loaded because of the subclasses like Gaussian which are defined here (and imported in qiskit.pulse's __init__.py). At the cost of some extra complexity, this sympy usage could be shifted from class definition to first usage.

[jakelishman]

If you can shift it to first-use, not import, that would be better - sympy is a super heavy import, so we need to make sure it's not in any code paths that are run during import qiskit.

I think it shouldn't be too much additional complexity; you can either put an extra field on the class to store the cached value and make definition a regular property that returns the class-level cache or populates it as necessary, or you can write a custom descriptor that does essentially the same thing, but stores the cached value in a separate object to keep the main type clean.

[wshanks]

I think @nkanazawa1989 was pushing the change to first-use literally as you were typing submitting (just read the comment about your review being old) this 🙂

[mtreinish]

Same thing here this should be a runtime import

[wshanks]

We might want to leave a symengine version here in a comment for reference for once piece-wise support is available. In nkanazawa1989#48, I had mentioned that symengine did not support complex numbers. It turns out it does, but you need to pass real=False to Lambdify.

So sympy.lambdify(symbols, expr) becomes symengine.lambify(symbols, [expr], real=False).

[nkanazawa1989]

Thanks Will for investigation. I didn't realize that option. Probably we can re-add symengine but I need more investigation for boolean expressions.

[jakelishman]

I just opened this PR, and apparently I wrote these review comments about a month ago and they never submitted properly. I'm sorry if they're a bit out-of-date or incomplete - I just wanted to push them through rather than leaving them in GitHub limbo.

[jakelishman]

If you can shift it to first-use, not import, that would be better - sympy is a super heavy import, so we need to make sure it's not in any code paths that are run during import qiskit.

I think it shouldn't be too much additional complexity; you can either put an extra field on the class to store the cached value and make definition a regular property that returns the class-level cache or populates it as necessary, or you can write a custom descriptor that does essentially the same thing, but stores the cached value in a separate object to keep the main type clean.

[jakelishman]

The type of cls.constraints here looks a bit inconsistent - in one branch it's a list of functions, in the other it's the Sympy truth constant. Given that (I think) you usually use this by effectively all(c(params) for c in cls.constraints), the global truthiness state could also just be represented by the empty sequence.

[nkanazawa1989]

Make sense. Done in 2ea6390. I intentionally avoid using all(c(params) for c in cls.constraints) or something like map for better error message. It still checks constraints one by one to tell users which one failed.

[jakelishman]

It's pretty odd to pass this as a parameter - is there a reason not to use type(self).__name__ in the repr?

[nkanazawa1989]

Ah good catch! I was first thinking how we can QPY deserialize custom pulse class based on envelope and constraints symbolic equations. I was trying to mimic circuit Gate in which they use common base class with custom instance-level definition and unique name to represent custom instruction. So I was thinking to use this type as name (but in pulse module it should behave as class name).

Anyways we decided to add these symbolic definitions to class attribute (to avoid lambdify overhead that the circuit module doesn't have) so this idea doesn't work, i.e. we cannot define two different waveforms on top of the SymbolicPulse base class.

[nkanazawa1989]

In this sense probably your idea of descriptor #7821 (comment) makes this framework much cleaner. In the current implementation we need to dynamically generate custom Type in the QPY loader.

[nkanazawa1989]

Descriptor would be the best solution 0738497. We can QPY serialize the state of descriptor since it can store definitions of all pulse types. Then we can directly restore lambda functions before loading actual pulse instructions. Likely this will simplify the framework for loading custom pulses.

[wshanks]

Looks good to me now!

[mtreinish]

Overall this looks great to me. I'm glad that @wshanks did a detailed review as he'll be a heavy user of this and can provide better feedback on the interface. I've left a few inline comments mostly on documentation but nothing major.

The only open question for me really is if we wanted to have dedicated classes for the SymbolicPulse class, especially to test the validation and error cases. You have tests via the library pulse classes which give some coverage, do you think that's sufficient?

[mtreinish]

If you want truly an immutable type that's really tricky to do in python. You can create one like frozendict pretty easily without that library just something that implements __getitem__() and the other read only mapping protocol functions will work. Basically just subclass collections.abc.Mapping. You could also do it via rust via a HashMap or IndexMap rust struct if you wanted something with statically typed keys which performed better. But that only limits it to top level immutability (basically only blocking inserts and value replacements) you'll always still be able to modify a value inplace. For example, using frozendict you could do something like:

import frozendict
test = frozendict.frozendict({'a': []})
test['a'].append(2)
print(test)

Would print: frozendict.frozendict({'a': [2]})

[mtreinish]

Thanks for the updates I think with one small doc update about the platform support this is good from my end too.