🚸 Improve Handling of Custom Properties and Parameters

[ystade]

QDMI aims to be a uniform interface to various devices with different available properties and parameters to be set. While it tries to incorporate often-used properties and parameters after consolidation from the different devices, especially in the beginning, most likely also in the long run, there will be properties and parameters specific to some devices that are not covered by QDMI. To this end, QDMI provides enumeration values ..._CUSTOM_... at the end of almost all enumerations. However, there are two problems with the current approach:

• The number of custom properties and parameters is limited by the number of respective enumeration values provided by QDMI, five at the moment.
• Those custom properties and parameters do not convey any semantic information. When used in the device, driver, or client code, this makes the code less clear and comprehensible.

Regarding the latter point, note, that QDMI by design cannot provide this semantic information because custom properties and parameters only make sense in combination with a specific device.

So, it remains an open question: how can we facilitate custom properties and parameters while keeping the code clear and comprehensible?

[ystade]

One possible direction to go, that is very close to the current state of the interface, would be to allow each device to define its own constants for properties and parameters specific to itself. To this end, the device implementation would also ship a public header that can be included in the driver's and client's code containing those additional constants together with appropriate docstrings for documentation. There are a couple of points that must be taken care of with this approach:

1. As enumeration values are just treated as integers in C, the extension of an enumeration should be possible somehow. Nevertheless, this could lead to errors during the type checking that must be worked around.
2. Constants defined by the device must never overlap those defined in QDMI itself, otherwise, their meaning is not well-defined anymore. This can become a problem, especially, when QDMI adds new constants from one version to the next. One way to circumvent this issue would be to reserve a fixed range of values for said custom properties and parameters, i.e., everything above 65.536 (= 2^16).

If one wants to avoid that devices must distribute a corresponding header, the same functionality can be achieved in a slightly different way. The device still defines custom constants in a specified value range but exposes the availability and semantics of those additional constants via functions:

1. One function returns a list of available additional properties or parameters defined by the device. This list just contains plain integers corresponding to the additional enumeration values.
2. To give the returned integers some meaning, there is another function that allows to query some kind of help-string for integers describing its semantics. This would be very similar to error codes for HTTP requests or return codes of C functions.
3. Either the function of (2) or a separate function also returns the type of the value that is represented by the corresponding property or parameter.

This approach has the advantage that it avoids any string parsing during normal operation and hence is assumed to be more performant compared to using strings instead of enumeration values to identify properties and parameters.

[burgholzer]

Thanks for opening this issue/discussion. Good to see our internal discussions being written out somewhere.
Let me just add a couple of thoughts.

---

Regarding your proposed approach above, one has to be really careful about how devices are distributed. Right now, a single shared library object is enough. Drivers only need to load that using dlopen. With your first proposal above, devices would also need to ship a header, and that header would have to be incorporated somehow into driver implementations. I suppose this would be impossible during runtime.

That leads me to believe that the shared library of a device must be sufficient for providing all information. Your second proposal seems to be reasonable. I'd just add that besides help text and type information, an optional default value might also be interesting to get via the interface.

---

I can think of at least two alternative solutions:

1. Introducing new parameters that have a string type and essentially represent serialized JSON config. There could be an option to query the default JSON payload, which would provide an overview of the available options and their default values. I'd argue that this is rather flexible, but might not be the prettiest solution.

2. Introducing key-value storage parameters (such as QInfo) that more directly represent the mapping from strings to data (int, double, string in case of QInfo). This would probably make a more structured approach and roughly matches how MPI is handling this.

---

We are not the first to face questions like these. Could someone (@ystade, @mnfarooqi) look through the literature/existing software and collect the best practices from there?
I am thinking about MPI, OpenACC, OpenMP, OpenCL.

[mnfarooqi]

I understand the problem with the ..._CUSTOM_... enum values if a device requires additional ones. However, I am not quite sure how it will be used. For example, even if the QDMI specifications provide a way for a driver/client to query all device-specific enum values, as well as their descriptions, how would a driver/client use this information without knowing how to deal with a device-specific enum at runtime?

Could you elaborate further by providing an example use case?

[burgholzer]

I understand the problem with the ..._CUSTOM_... enum values if a device requires additional ones. However, I am not quite sure how it will be used. For example, even if the QDMI specifications provide a way for a driver/client to query all device-specific enum values, as well as their descriptions, how would a driver/client use this information without knowing how to deal with a device-specific enum at runtime?

Could you elaborate further by providing an example use case?

One of the prime use cases for any kind of additional, device-specific parameters is specifying special options for jobs. An example that comes to mind is IQM's client library and their RunRequest data structure.

https://github.com/iqm-finland/sdk/blob/eeeeb9b383e411feaacb6b3b3159e4bd82cd0f88/iqm_client/src/iqm/iqm_client/models.py#L887

This includes fairly specific settings that control the execution of a circuit on IQM devices.
While some of these (e.g., dynamical decoupling) could make sense to stabilize in the form of new job parameters, some are so overly specific that some other kind of handling is needed.

I believe there could be other places where truly custom parameters would be useful, but job/execution management is the biggest and most precise one.

As for the runtime aspect: yeah. That seems to be fairly tough. One almost surely needs to know beforehand, which custom options a device provides so that these options can be used as part of the driver/client. At that point, there is no real value in exposing type or description information at runtime.

I have to hop to some other tasks now, but hopefully the above provides some arguments for moving this discussion along.

[mnfarooqi]

Having looked into it a bit more, I think that QInfo would be an appropriate solution for handling custom properties.

• Qinfo uses key-value pairs. If we used strings instead of enums as keys, there would be no need for a header file from the device vendors.
• We would only need one enum in the job parameters to pass a QInfo object, which would hold all the custom parameters. This would prevent any breaking changes, regardless of how many custom properties a device has.
• Moreover, this would neatly handle the job properties query interface for custom properties.

We could change the QInfo interface to match the QDMI interface and incorporate it into the QDMI repository. Device vendors can bring their own implementation of QInfo, but we can also add an example implementation from the QInfo repository.

[burgholzer]

Having looked into it a bit more, I think that QInfo would be an appropriate solution for handling custom properties.

• Qinfo uses key-value pairs. If we used strings instead of enums as keys, there would be no need for a header file from the device vendors.

I think that is a convincing argument.

• We would only need one enum in the job parameters to pass a QInfo object, which would hold all the custom parameters. This would prevent any breaking changes, regardless of how many custom properties a device has.

Haven't thought about it that way, but yeah an additional job parameter that is a QInfo object should work quite well.
Or does it need to be a pointer to a QInfo object?
Does QInfo need to be opaque similar to the other structs defined in QDMI?
I would suppose that would be beneficial (and is actually how QInfo is currently designed) for compatibility reasons.

• Moreover, this would neatly handle the job properties query interface for custom properties.

Yeah. There would simply be an additional property that would return a QInfo handle.

We could change the QInfo interface to match the QDMI interface and incorporate it into the QDMI repository. Device vendors can bring their own implementation of QInfo, but we can also add an example implementation from the QInfo repository.

I would be in favor of moving the QInfo interface here to have fewer repositories to maintain.

I also believe we should provide a default implementation as I think it is fairly unlikely that device vendors will want to implement this on their own.
Device implementations would most likely have to link against that example implementation if they want to test their devices.
For distributing devices, they would not need to link against the QInfo library because the driver supposedly links against the default implementation.

@ystade opinions on this?

[ystade]

This all makes sense to me. One more point just to have it spoken out loud: We do not want to replace all enum values with the QInfo object, i.e., that the function only takes a QInfo object instead of an enum value and a value?

[burgholzer]

This all makes sense to me. One more point just to have it spoken out loud: We do not want to replace all enum values with the QInfo object, i.e., that the function only takes a QInfo object instead of an enum value and a value?

That would be an option in principle.
Although I would argue that the current style of the QDMI interface at least enforces a little bit more structure than just using key-value stores (=QInfo). So I would prefer to stick with that for as long as we can go.

I'd really view this addition of QInfo only as a way of adding device specific options. And, at first, I would purposely limit it to the job interface, where we have a concrete use case in mind.

[mnfarooqi]

• We would only need one enum in the job parameters to pass a QInfo object, which would hold all the custom parameters. This would prevent any breaking changes, regardless of how many custom properties a device has.

Haven't thought about it that way, but yeah an additional job parameter that is a QInfo object should work quite well. Or does it need to be a pointer to a QInfo object? Does QInfo need to be opaque similar to the other structs defined in QDMI? I would suppose that would be beneficial (and is actually how QInfo is currently designed) for compatibility reasons.

QInfo as an opaque pointer would be better, as there are no other structs defined in the QDMI. We can copy the existing QInfo interface and remove all the getters and setters that are specific to data types.

[mnfarooqi]

This all makes sense to me. One more point just to have it spoken out loud: We do not want to replace all enum values with the QInfo object, i.e., that the function only takes a QInfo object instead of an enum value and a value?

That would be an option in principle. Although I would argue that the current style of the QDMI interface at least enforces a little bit more structure than just using key-value stores (=QInfo). So I would prefer to stick with that for as long as we can go.

I'd really view this addition of QInfo only as a way of adding device specific options. And, at first, I would purposely limit it to the job interface, where we have a concrete use case in mind.

We only use QInfo for custom parameters, and not as a replacement for the existing or any future standard enums. Even though it cannot force device vendors to use standard enums instead of QInfo. We could name the QInfo so that it highlights it is for custom parameters, but without restricting how it can be used in the future.