{"id":13442764,"url":"https://github.com/quil-lang/quilc","last_synced_at":"2025-03-20T15:30:46.289Z","repository":{"id":38216553,"uuid":"158458059","full_name":"quil-lang/quilc","owner":"quil-lang","description":"The optimizing Quil compiler.","archived":false,"fork":false,"pushed_at":"2024-06-18T02:51:31.000Z","size":3583,"stargazers_count":447,"open_issues_count":214,"forks_count":73,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-06-26T04:54:19.198Z","etag":null,"topics":["common-lisp","compiler","forest","quantum-computing","quil"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quil-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-20T22:14:40.000Z","updated_at":"2024-07-31T05:11:11.387Z","dependencies_parsed_at":"2023-10-14T17:05:39.769Z","dependency_job_id":"6c642d34-8688-40a8-8b47-f1f77748d838","html_url":"https://github.com/quil-lang/quilc","commit_stats":null,"previous_names":["rigetti/quilc"],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quil-lang%2Fquilc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quil-lang%2Fquilc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quil-lang%2Fquilc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quil-lang%2Fquilc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quil-lang","download_url":"https://codeload.github.com/quil-lang/quilc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244639895,"owners_count":20485947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["common-lisp","compiler","forest","quantum-computing","quil"],"created_at":"2024-07-31T03:01:50.318Z","updated_at":"2025-03-20T15:30:45.762Z","avatar_url":"https://github.com/quil-lang.png","language":"Common Lisp","funding_links":[],"categories":["Common Lisp"],"sub_categories":[],"readme":"# QUILC\n\n[![github release](https://img.shields.io/github/release/rigetti/quilc.svg)](https://github.com/rigetti/quilc/releases)\n[![docker pulls](https://img.shields.io/docker/pulls/rigetti/quilc.svg)](https://hub.docker.com/r/rigetti/quilc)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3677536.svg)](https://doi.org/10.5281/zenodo.3677536)\n\n\nQuilc is an advanced optimizing compiler for the quantum instruction\nlanguage Quil, licensed under the [Apache 2.0 license](LICENSE.txt).\n\nQuilc comprises two projects. The first, `cl-quil`, does the heavy\nlifting of parsing, compiling, and optimizing Quil code. The second,\n`quilc`, presents an external interface for using `cl-quil`, either using\nthe binary `quilc` application directly, or alternatively by\ncommunicating with an [RPCQ](https://github.com/rigetti/rpcq/) server.\n\nQuil is the [quantum instruction language](https://quil-lang.github.io/), originally developed at Rigetti Computing. In Quil quantum algorithms are expressed using Quil's\nstandard gates and instructions. One can also use Quil's `DEFGATE` to\ndefine new non-standard gates, and `DEFCIRCUIT` to build a named circuit\nthat can be referenced elsewhere in Quil code (analogous to a function\nin most other programming languages).\n\n## Quil Compiler\n\nThis directory contains the `quilc` application. `quilc` takes as input\narbitrary Quil code, either provided directly to the binary or to the\n`quilc` server, and produces optimized Quil code. The compiled code is\noptimized for the configured instruction set architecture (ISA),\ntargeting the native gates specified by the ISA.\n\n\n### Cloning the repository\n\nTo clone the quilc repository and its bundled submodules, run the following command:\n\n``` shell\ngit clone --recurse-submodules https://github.com/quil-lang/quilc.git\n```\n\n### Building the Quil Compiler\n\nPrerequisites to building `quilc` are:\n\n1. Standard UNIX build tools\n2. [SBCL](http://www.sbcl.org/) (a recent version, but [*not* SBCL 1.5.6](#sbcl-156)): Common Lisp compiler\n3. [Quicklisp](https://www.quicklisp.org/beta/): Common Lisp library manager\n4. [ZeroMQ](http://zeromq.org/intro:get-the-software): Messaging library\n   required by RPCQ. Development headers are required at build time.\n\nFollow [these instructions](https://github.com/quil-lang/qvm/blob/master/doc/lisp-setup.md)\nto get started from scratch.\n\nOne notorious dependency is [MAGICL](https://github.com/quil-lang/magicl). It is available on Quicklisp,\nbut requires you to install some system libraries such as BLAS, LAPACK, and libffi. Follow MAGICL's\ninstructions carefully before proceeding with loading CL-QUIL or `make`ing quilc.\n\nOnce these dependencies are installed, building should be easy. Building the `quilc`\nbinary is automated using the `Makefile`:\n\n``` shell\n$ make quilc\n```\n\nThis will create a binary `quilc` in the current directory\n\n``` shell\n$ ./quilc --version\n```\n\nTo install system-wide issue the command\n\n``` shell\n$ make install\n```\n\n#### Build flags\n\n`quilc` can be built with additional options provided to `make` as described below:\n\n| Flag                     | Description                                                                                                                                                     |\n|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `POST_LOAD_ASDF_SYSTEMS` | Specify additional ASDF systems to load _after_ `quilc` as part of the executable. This can be used to build `quilc` with additional out-of-tree functionality. |\n\n### Using the Quil Compiler\n\nThe Quil Compiler provides two modes of interaction: (1) communicating\ndirectly with the `quilc` binary, providing your Quil code over `stdin`;\nor (2) communicating with the `quilc` server.\n\n#### quilc\n\nThe `quilc` binary reads Quil code provided on `stdin`:\n\n``` shell\n$ echo H 0 | quilc\n$ cat large_file.quil | quilc\n```\n\n#### Server\n\nFor various reasons (e.g. not having to repeatedly load the `quilc`\nbinary into memory, communicating over a network) `quilc` provides a\nan [RPCQ](https://github.com/rigetti/rpcq/) server\ninterface. [RPCQ](https://github.com/rigetti/rpcq/) is an open-source\nRPC framework developed at Rigetti for efficient network communication\nthrough the QCS stack. The server is started in RPCQ-mode using the\n`-R` flag\n\n```\n$ quilc -R\n+-----------------+\n|  W E L C O M E  |\n|   T O   T H E   |\n|  R I G E T T I  |\n|     Q U I L     |\n| C O M P I L E R |\n+-----------------+\nCopyright (c) 2016-2019 Rigetti Computing.\n\n\u003c134\u003e1 2019-01-29T22:03:08Z workstation.local ./quilc 4077 LOG0001 - Launching quilc.\n\u003c134\u003e1 2019-01-29T22:03:08Z workstation.local ./quilc 4077 - - Spawning server at (tcp://*:5555) .\n```\n\nThe server-mode provides to high-level languages such as Python a way\nto communicate with the Quil compiler, thus enabling high-level\nabstractions and tools that are not directly available in Quil. The\n[`pyquil`](https://github.com/rigetti/pyquil) library provides such an interface to `quilc`.\n\n## CL-QUIL\n\n`CL-QUIL` is the Lisp library that implements parsing and compiling\nof Quil code. The code can be found under `./src/`. Other lisp libraries, including\n`quilc`, can depend on it.\n\n### Usage\n\nTo get up and running quickly using the `quilc` Docker image, head directly to the\nsection \"Running the Quil Compiler with Docker\" below. Otherwise, the following steps\nwill walk you through how to build the compiler from source.\n\nFollow the instructions in QVM's\n[doc/lisp-setup.md](https://github.com/quil-lang/qvm/blob/master/doc/lisp-setup.md) to satisfy the\ndependencies required to load the `CL-QUIL` library. Afterwhich, the\nlibrary can be loaded\n\n\n``` shell\n$ sbcl\n\n```\n\n``` common-lisp\n* (ql:quickload :cl-quil)\n;;; \u003csnip\u003ecompilation output\u003c/snip\u003e\n(:CL-QUIL)\n* (cl-quil:parse-quil \"H 0\")\n#\u003cCL-QUIL:PARSED-PROGRAM {100312C643}\u003e\n```\n\nA few good entry points to exploring the library are:\n\n* The functions `cl-quil::parse-quil` in [`src/parser.lisp`](src/parser.lisp), and\n  `cl-quil:parse-quil` in [`src/cl-quil.lisp`](src/cl-quil.lisp) and the various\n  transforms therein.\n* The function `cl-quil:compiler-hook` which constructs a control-flow\n  graph (CFG) and then performs various optimizations on the CFG.\n\n## Automated Build, Test, and Release with Docker\n\nThe CI pipeline for `quilc` produces a Docker image, available at\n[`rigetti/quilc`](https://hub.docker.com/r/rigetti/quilc).\nTo get the latest stable version of `quilc`, run `docker pull rigetti/quilc`.\nTo instead pull a specific version of quilc, run `docker pull rigetti/quilc:VERSION`,\nwhere `VERSION` is something like `1.10.4`.\n\nThe Dockerfile for quilc builds from three parent Docker images:\n\n1. [`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp): Contains SBCL, Quicklisp, and\n   third-party libraries.\n2. [`rigetti/rpcq`](https://hub.docker.com/r/rigetti/rpcq): Contains the message spec and\n   RPC framework used by quilc.\n3. [`rigetti/qvm`](https://hub.docker.com/r/rigetti/qvm): Contains the Quantum Virtual Machine,\n   used in the quilc tests.\n\nThe Dockerfile for quilc intentionally pins the versions of these three images,\nwhich means that the version numbers must be actively incremented as necessary.\nIf the build for quilc is failing, this is probably the place to look, because\nthe unit tests are run inside of a freshly-built quilc Docker image as part of\nthe GitLab CI pipeline.\n\n## Running the Quil Compiler with Docker\n\nAs outlined above, the Quil Compiler supports two modes of operation: stdin and server.\n\nTo run `quilc` in stdin mode, do one either of the following:\n\n1. The containerized compiler will then read whatever newline-separated Quil instructions you\nenter, waiting for an EOF signal (Control+d) to compile it.\n\n```shell\ndocker run --rm -it rigetti/quilc\n```\n\n2. You can alternatively pipe Quil instructions into the `quilc` container if you drop the `-t`.\n\n```shell\necho H 0 | docker run --rm -i rigetti/quilc\n```\n\nTo run `quilc` in server mode, do the following:\n\n```shell\ndocker run --rm -it -p 5555:5555 rigetti/quilc -R\n```\n\nThis will spawn an RPCQ-mode `quilc` server, that you can communicate with over TCP. If\nyou would like to change the port of the server to PORT, you can alter the command as follows:\n\n```shell\ndocker run --rm -it -p PORT:PORT rigetti/quilc -R -p PORT\n```\n\nPort 5555 is exposed using the EXPOSE directive in the `rigetti/quilc` image, so\nyou can additionally use the `-P` option to automatically bind this container port to a randomly\nassigned host port. You can then inspect the mapping using `docker port CONTAINER [PORT]`.\n\n## Release Process\n\n1. Update `VERSION.txt` and push the commit to `master`.\n2. Push a git tag `vX.Y.Z` that contains the same version number as in `VERSION.txt`.\n3. Verify that the resulting build (triggered by pushing the tag) completes successfully.\n4. Publish a [release](https://github.com/quil-lang/quilc/releases) using the tag as the name.\n5. Close the [milestone](https://github.com/quil-lang/quilc/milestones) associated with this release,\n   and migrate incomplete issues to the next one.\n6. Update the quilc version of downstream dependencies (if applicable, see next section).\n\n## Downstream Dependencies\n\nCurrently, there are a couple different components of the Forest SDK that depend on quilc:\n\n1. [qvm](https://github.com/quil-lang/qvm)\n2. [pyquil](https://github.com/rigetti/pyquil)\n3. [forest-benchmarking](https://github.com/rigetti/forest-benchmarking)\n\nIt is the responsibility of the releaser to verify that the latest quilc release does not\nbreak the test suites of these downstream dependencies. All of these repositories pull the\nlatest released version of quilc as part of their CI pipelines.\n\n## Benchmarking\n\n`quilc` offers a benchmarking suite to compare its performance against other compilers and\nbetween its own versions.  To run the benchmark suite, move to the `quilc` root directory,\nmake sure the git submodules are checked out, and run\n\n```\nmake benchmark-qasm\n```\n\n# Get involved!\n\nWe welcome and encourage community contributions! Peruse our [guidelines for contributing](CONTRIBUTING.md)\nto get you up to speed on expectations. Once that's clear, a good place to start is the\n[good first issue](https://github.com/quil-lang/quilc/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) section. If you find any bugs, please create an [issue](https://github.com/quil-lang/quilc/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).\n\nWe look forward to meeting and working with you!\n\n# Incompatible software versions\n\n## SBCL 1.5.6\n\nThere is [an issue](https://github.com/quil-lang/quilc/issues/401) with\nSBCL 1.5.6 that results in unhandled memory faults in\n`SB-VM::FUNCALLABLE-INSTANCE-TRAMP` when attempting to run quilc\ncompiled with that version of SBCL. The issue was resolved with SBCL\ncommit\n[550c4d2](https://sourceforge.net/p/sbcl/sbcl/ci/550c4d23c77cc670fb95d7216e3c6d493bbd76eb/). For\nthis reason, it's not possible to use quilc or cl-quil with SBCL\n1.5.6, but any other recent SBCL version should work fine.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquil-lang%2Fquilc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquil-lang%2Fquilc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquil-lang%2Fquilc/lists"}