Skip to content

Clear guidelines on what should and should not be parts of the public API

Motivation

In order to support a stable API, we need to have clear guidelines on what objects (classes, interfaces, functions, methods, etc.) should be part of the public API, and which ones are considered private.

This is important for the following reasons.

  • The definition of breaking changes: interfaces (function, methods, classes, etc.) that are part of the public API can be used by users. If these interfaces change, we need to follow the Deprecation policy (quantify-core!282 (merged)) 7 months old merge request, I think this should be merged.
  • Code maintainability, if the internals are all pinned by being publicly accessible it is no longer possible to refactor or improve the code.
  • Code obfuscation, a user should be concerned with what a function does, and not so much with how it achieves this. This is closely related to the previous, but relevant when we want to replace some internals with something that has higher performance (e.g., compiled C-binaries or something similar).

Definition of public API

The definition of what the public API is is clear, we follow the python convention that "a name prefixed with an underscore (e.g. _spam) should be treated as a non-public part of the API" (https://docs.python.org/3/tutorial/classes.html?highlight=private#private-variables), and conversely everything else should be considered part of the public API.

In addition, we might use the __all__ magic method in modules to define public interfaces.

Proposal for formal guideline

As a formal guideline, I would propose that anything a user might need to use quantify(-scheduler) should be part of the public API. Anything that is required only for the internals of quantify should not be part of the private API.

This of course immediately begs the question, what a user might want to do with quantify, and what we consider the intended use. I think most of us have a pretty good intuition on what is and is not a valid use-case or an intended use-case of quantify. I suggest we iterate a bit on this intuition what should and should not be public with the explicit goal to come up with an actionable guideline that we can integrate into the contribution guidelines and include in merge requests.

Intuition on what this means in practice

For quantify scheduler, I would think this roughly implies the following (on what should be public/private, not on what the current situation is).

What should be public

  • The Schedule API used by users to set up programs.
  • The schedule generating functions
  • the operation libraries (gates, pulses, etc.)
  • the interface definitions for the config files
  • The interfaces to the compilers
  • The QuantumDevice and DeviceElements
  • The visualization and debug functionality.

What should be private

  • The internals of the compilation backends.
  • The internals of the "pulse factories"

Edge cases

  • Utility functions used in multiple compilation backends. (cannot be private on a module basis, but should maybe not be part of the public package API).

I don't know how to deal with this edge case

How should this affect our development guidelines?

This intuition is obviously not clear-cut, and I'm sure we could come up with many edge-cases that violate this. Furthermore, this (intuitive) distinction should follow from what we consider the use-cases of quantify-scheduler.

Consequences of an object being private

A consequence of an object being private is that it can only be used within that module. This should help us in decoupling modules from each other more explicitly (a good thing).
The drawback is of course also that it allows us less freedom in development and reusing code which means we need to think a bit more ahead when working on this.

What to do to resolve this issue

  • Iterate on what valid and invalid use-cases of quantify are with the purpose of distilling a sensible guideline for the public vs private interface discussion.
  • update the contribution guidelines with the outcome of the discussion
  • include public-private consideration in the checkbox for a MR. (up for discussion)

As you can see I'm raising more questions than giving answers. I look forward to your input.