Skip to content
The RPC framework and message specification for @rigetti Quantum Cloud Services.
Common Lisp Python Other
Branch: master
Clone or download
appleby and stylewarning Add a py.typed file for PEP 561 compliance
This ensures that mypy can "find" the rcpq package when checking type
annotations from pyquil (or any other package that uses rpcq).

https://www.python.org/dev/peps/pep-0561/

https://mypy.readthedocs.io/en/latest/installed_packages.html#making-pep-561-compatible-packages
Latest commit bd0ae49 Sep 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
rpcq Add a py.typed file for PEP 561 compliance Sep 16, 2019
src-tests Add TEST-PREPARE-RPC-CALL-ARGS Jul 31, 2019
src Don't reverse the order of non-keyword args in PREPARE-RPC-CALL-ARGS (#… Jul 30, 2019
.gitignore Initial commit Oct 14, 2018
.gitlab-ci.yml Use the new rigetti/lisp image for testing and Docker build (#83) Jul 17, 2019
CODEOWNERS Add CODEOWNERS file for default reviewers (#26) Jan 4, 2019
Dockerfile Use the new rigetti/lisp image for testing and Docker build (#83) Jul 17, 2019
LICENSE Initial commit Oct 14, 2018
MANIFEST.in Initial commit Oct 14, 2018
Makefile
README.md Use the new rigetti/lisp image for testing and Docker build (#83) Jul 17, 2019
VERSION.txt
docker_update_python_spec.sh Helper script to use docker to update python message spec (#68) May 20, 2019
python-type-design.md Add initial type design doc, Colm to authors list (#51) Apr 22, 2019
requirements.txt Vendor dataclasses and release version 2.5.0 (#56) Apr 30, 2019
rpcq-tests.asd bring the Lisp code up to speed with its Python counterparts Oct 19, 2018
rpcq.asd add core-messages to lisp system (#91) Aug 8, 2019
setup.py Add a py.typed file for PEP 561 compliance Sep 16, 2019
update_python_spec.lisp add rpcq.messages as a parent namespace to rpcq.core_messages (#70) May 29, 2019

README.md

rpcq

pipeline status pypi version conda-forge version docker pulls

The asynchronous RPC client-server framework and message specification for Rigetti Quantum Cloud Services (QCS).

Implements an efficient transport protocol by using ZeroMQ (ZMQ) sockets and MessagePack (msgpack) serialization.

Not intended to be a full-featured replacement for other frameworks like gRPC or Apache Thrift.

Python Installation

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, run pip install rpcq.

NOTE: We strongly encourage users of rpcq to install the software within a (Python) virtual environment (read up on virtualenv, pyenv, or conda for more info).

Lisp Installation

Installation is easier with QuickLisp. After placing the source for RPCQ within your local Lisp projects directory (cf. ql:*local-project-directories*), run (ql:quickload :rpcq) 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 'test'.

Using the Message Spec

The message spec as defined in src/messages.lisp (which in turn produces rpcq/messages.py) 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 src/messages.lisp, open rlwrap sbcl and run:

(ql:quickload :rpcq)
(with-open-file (f "rpcq/messages.py" :direction :output :if-exists :supersede)
  (rpcq:python-message-spec f))

NOTE: Requires pre-installed sbcl, quicklisp, and (optionally) rlwrap.

We can also use the rpcq docker container to update the message spec without to install the requirements.

./docker_update_python_spec.sh

Running the Unit Tests

The rpcq repository is configured with GitLab CI to automatically run the unit tests. The tests run within a container based off of the rigetti/lisp Docker image, which is pinned to a specific tag. If you need a more recent version of the image, update the tag in the .gitlab-ci.yml.

The Python unit tests can be executed locally by running pytest from the top-level directory of the repository (assuming you have installed the test requirements).

The Lisp unit tests can be run locally by doing the following from within rlwrap sbcl:

(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 ]

Automated Packaging with Docker

The CI pipeline for rpcq produces a Docker image, available at rigetti/rpcq. To get the latest stable version of rpcq, run docker pull rigetti/rpcq. The image is built from the rigetti/lisp Docker image, which is pinned to a specific tag. If you need a more recent version of the image, update the tag in the Dockerfile.

To learn more about the rigetti/lisp Docker image, check out the docker-lisp repository.

Release Process

  1. Update VERSION.txt and dependency versions (if applicable) and push the commit to master.
  2. Push a git tag vX.Y.Z that contains the same version number as in VERSION.txt.
  3. Verify that the resulting build (triggered by pushing the tag) completes successfully.
  4. Push the tagged commit to pypi and verify it appears here.
  5. Publish a release using the tag as the name.
  6. Close the milestone associated with this release, and migrate incomplete issues to the next one.

Authors

Developed at Rigetti Computing by Nikolas Tezak, Steven Heidel, Eric Peterson, Colm Ryan, Peter Karalekas, Guen Prawiroatmodjo, and Robert Smith.

You can’t perform that action at this time.