Rewrite Qiskit C API extension-module guide#4890
Conversation
The previous "Extend Qiskit from C" guide was very out of date, but more importantly, suggested several code patterns that are highly non-standard and require significant care and understanding to use safely. As of Qiskit 2.4, the C API is now safely packaged up in a way that allows writing Python extension modules _correctly_ and safely. This new form of the guide walks through the construction of a complete extension module, using the minimal amount of non-standard tooling.
|
One or more of the following people are relevant to this code:
|
beckykd
left a comment
beckykd
left a comment
There was a problem hiding this comment.
I'm done with the first half, but I keep getting pulled into other things. I'll pick this up again this afternoon.
| `pyproject.toml` file. However, our module will need access to the Qiskit C API header files during | ||
| its build process. Starting from v2.4, these are included in the Python distributions of the | ||
| Qiskit SDK, and you can locate the directory containing them using `qiskit.capi.get_include()`. | ||
| This leads us to a `setup.py` file that looks like: |
There was a problem hiding this comment.
| This leads us to a `setup.py` file that looks like: | |
| This returns a `setup.py` file that looks like: |
There was a problem hiding this comment.
I didn't apply this one just because "This returns a setup.py file" sounds off to me - the file is still something we are writing as part of the guide, not something that is the output of code. Would
| This leads us to a `setup.py` file that looks like: | |
| This results in a `setup.py` file that looks like: |
be ok?
| version of Python that includes its C API headers (this is standard). | ||
|
|
||
| There are various options to write a C extension for Python. For simplicity, this guide starts with an approach that uses Python's built-in [`ctypes`](https://docs.python.org/3/library/ctypes.html) module. In the next section, the [the Manual C extension](#manual-c-extension) section provides an example of building the C extension using Python's C API to reduce runtime overhead. | ||
| You should be familiar with, or prepared to look up, the individual functions and objects available |
There was a problem hiding this comment.
This part doesn't use the C API objects yet, right? If that only comes further below, where you're also explicitly referring to the C API docs I would suggest scratching that sentence (which also reads a little discouraging to me, but maybe that's just me 😛)
There was a problem hiding this comment.
Well, this is the requirements section for the experience we expect somebody reading the guide to have. We do use C API objects below, and don't explain them line by line.
| You must have the standard C compiler toolchain available for your platform. You must also have a | ||
| version of Python that includes its C API headers (this is standard). |
There was a problem hiding this comment.
Do you want to link to the "install the C API guide" which has a section on C requirements: https://quantum.cloud.ibm.com/docs/en/guides/install-c-api#requirements ?
There was a problem hiding this comment.
No because you don't need to install anything - it's all included in the Python package.
There was a problem hiding this comment.
The C compiler toolchain is included in the Python package? 🤔
I was referring to your sentence that said "You must have the standard C compiler toolchain available for your platform." 😄
There was a problem hiding this comment.
Ok sure, I can expand this a little if you like. I don't want to link to the "Install the C API" page though because that has much more complex requirements.
(Also we need to update that page too in a separate PR - it's also out of date.)
There was a problem hiding this comment.
No need to add more work here, only if it was 0 effort to link I would've added it, but you don't need to add more docs
| obs = cextension.build_observable() | ||
| print("SparseObservable instance?", isinstance(obs, qiskit.quantum_info.SparseObservable)) | ||
| print(obs) | ||
| The result of this is: |
There was a problem hiding this comment.
Maybe briefly to explain this matches what we're actually expecting:
| The result of this is: | |
| In the resulting circuit we can see that the spectator qubits are indeed measured: |
There was a problem hiding this comment.
I was kind of deliberately omitting any real description of the pass itself for this guide - the only thing I really wanted to draw attention to was that the code does in fact run. I don't want to imply that you have to understand the spectator measure stuff to understand the guide.
|
This is a very nice guide and much more stable than what was in place before 😂 I'm wondering if the C logic in the pass distracts a bit from the build process and if a simpler function would be better. But then again it might be easier for users to start from this and tone it down to what they want instead of starting too simple. |
Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Co-authored-by: abbycross <across@us.ibm.com> Co-authored-by: Jake Lishman <jake@binhbar.com>
|
@beckykd: I've updated this mostly with your editing, though I wasn't sure about a couple of them, which I've left open in the conversations above. Can you let me know if they're right / just apply them yourself if you're happy? |
5 participants
The previous "Extend Qiskit from C" guide was very out of date, but more importantly, suggested several code patterns that are highly non-standard and require significant care and understanding to use safely.
As of Qiskit 2.4, the C API is now safely packaged up in a way that allows writing Python extension modules correctly and safely. This new form of the guide walks through the construction of a complete extension module, using the minimal amount of non-standard tooling.