The asynchronous RPC client-server framework and message specification for Rigetti Quantum Cloud Services (QCS).
To install directly from the source, run
pip install -e . from within the top-level
directory of the
rpcq repository. To additionally install the requirements for testing,
make sure to run
pip install -r requirements.txt.
To instead install the latest released verson of
rpcq from the Python package manager PyPi,
pip install rpcq.
Installation is easier with QuickLisp. After placing the source for RPCQ within your local
Lisp projects directory (cf.
and QuickLisp will download the necessary Lisp dependencies.
In addition to the Lisp dependencies, RPCQ depends on ZeroMQ. Be sure to install both the library and its development headers (which are necessary for the Lisp foreign-function interface to get its bearings).
Using the Client-Server Framework
The following two code samples (first in Python, then in Lisp) demonstrate how to create a server, add a test handler, and spin it up.
from rpcq import Server server = Server() @server.rpc_handler def test(): return 'test' server.run('tcp://*:5555')
(defun test () "test") (let ((dt (rpcq:make-dispatch-table))) (rpcq:dispatch-table-add-handler dt 'test) (rpcq:start-server :dispatch-table dt :listen-addresses '("tcp://*:5555")))
In another window, we can (again first in Python, then in Lisp) create a client that points to the same socket, and call the test method.
from rpcq import Client client = Client('tcp://localhost:5555') client.call('test')
(rpcq:with-rpc-client (client "tcp://localhost:5555") (rpcq:rpc-call client "test"))
In all cases (including interoperating a client/server pair written in different languages), this will return the string
Using the Message Spec
The message spec as defined in
src/messages.lisp (which in turn produces
is meant to be used with the Rigetti QCS platform. Therefore,
these messages are used in
pyquil, in order
to allow users to communicate with the Rigetti Quil compiler and quantum processing units (QPUs).
PyQuil provides utilities for users to interact with the QCS API and write programs in
Quil, the quantum instruction language developed at Rigetti.
Thus, most users will not interact with
rpcq.messages directly. However, for those interested
in building their own implementation of the QCS API utilities in pyQuil, becoming acquainted
with the client-server framework, the available messages in the message spec, and how they
are used in the
pyquil.api module would be a good place to start!
Updating the Python Message Bindings
Currently only Python bindings are available for the message spec, but more language bindings
are in the works. To update the Python message bindings after editing
rlwrap sbcl and run:
(ql:quickload :rpcq) (with-open-file (f "rpcq/messages.py" :direction :output :if-exists :supersede) (rpcq:python-message-spec f))
Running the Unit Tests
rpcq repository is configured with SemaphoreCI to automatically run the Python unit tests.
This can be done locally by running
pytest from the top-level directory of the repository
(assuming you have installed the test requirements).
There is additionally a very small suite of Lisp tests for
rpcq. These are not run by
SemaphoreCI, but can be run locally by doing the following from within
(ql:quickload :rpcq) (asdf:test-system :rpcq)
There may be some instances of
STYLE-WARNING, but if the test run successfully,
there should be something near the bottom of the output that looks like:
RPCQ-TESTS (Suite) TEST-DEFMESSAGE [ OK ]