The quilc Reference Manual

This is the quilc Reference Manual, version 1.26.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon May 15 06:17:45 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 quilc

A CLI front-end for the Quil compiler

Author

Eric Peterson <>

License

Apache License 2.0 (See LICENSE.txt)

Version

1.26.0

Dependencies
  • cl-ppcre (system).
  • split-sequence (system).
  • command-line-arguments (system).
  • yason (system).
  • magicl (system)., at least version "0.7.0"
  • cl-quil (system).
  • cl-quil-benchmarking (system).
  • uiop (system).
  • bordeaux-threads (system).
  • cl-syslog (system).
  • rpcq (system).
  • drakma (system).
  • trivial-features (system).
  • alexandria (system).
  • swank (system).
Source

quilc.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 quilc/quilc.asd

Source

quilc.asd.

Parent Component

quilc (system).

ASDF Systems

quilc.


3.1.2 quilc/package.lisp

Source

quilc.asd.

Parent Component

quilc (system).

Packages

quilc.


3.1.3 quilc/globals.lisp

Dependency

package.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.4 quilc/versions.lisp

Dependency

globals.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.5 quilc/impl/sbcl.lisp

Dependency

versions.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.6 quilc/chip-cache.lisp

Dependency

impl/sbcl.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.7 quilc/rpc-server.lisp

Dependency

chip-cache.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.8 quilc/printers.lisp

Dependency

rpc-server.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.9 quilc/options.lisp

Dependency

printers.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

3.1.10 quilc/entry-point.lisp

Dependency

options.lisp (file).

Source

quilc.asd.

Parent Component

quilc (system).

Internals

4 Packages

Packages are listed by definition order.


4.1 quilc

Source

package.lisp.

Use List
  • cl-quil.
  • common-lisp.
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.2 Internals


5.2.1 Constants

Constant: +git-hash+

The git hash of the quilc repo.

Package

quilc.

Source

versions.lisp.

Constant: +quilc-version+

The version of the quilc application.

Package

quilc.

Source

versions.lisp.


5.2.2 Special variables

Special Variable: *chip-cache*

Cached chip specifications. Pair of values (hash-table . lock). Large chips have a significant construction overhead, and caching chips between requests reduces or eliminates that overhead. The hash value for a given key is a pair (last-access . chip-spec). Note: use the lock when accessing.

Package

quilc.

Source

chip-cache.lisp.

Special Variable: *chip-cache-max-size*

The maximum number of entries in the cache.

Package

quilc.

Source

chip-cache.lisp.

Special Variable: *deprecated-option-spec*

Supported and deprecated options.

Package

quilc.

Source

options.lisp.

Special Variable: *human-readable-stream*
Package

quilc.

Source

globals.lisp.

Special Variable: *ignored-option-spec*

Inactive and deprecated options.

Package

quilc.

Source

options.lisp.

Special Variable: *log-level*
Package

quilc.

Source

globals.lisp.

Special Variable: *logger*
Package

quilc.

Source

globals.lisp.

Special Variable: *nick-banner*
Package

quilc.

Source

entry-point.lisp.

Special Variable: *option-spec*

Supported and non-deprecated options.

Package

quilc.

Source

options.lisp.

Special Variable: *program-name*
Package

quilc.

Source

globals.lisp.

Special Variable: *protoquil*
Package

quilc.

Source

globals.lisp.

Special Variable: *quil-stream*
Package

quilc.

Source

globals.lisp.

Special Variable: *retired-option-spec*

Invalid options.

Package

quilc.

Source

options.lisp.

Special Variable: *state-aware*
Package

quilc.

Source

globals.lisp.

Special Variable: *without-pretty-printing*
Package

quilc.

Source

globals.lisp.


5.2.3 Macros

Macro: special-bindings-let* (let-defs &body body)

Bind LET-DEFS as in LET, and add those LET-DEFS to bordeaux-threads:*default-special-bindings* in the same LET.

Package

quilc.

Source

entry-point.lisp.


5.2.4 Ordinary functions

Function: %entry-point (argv)
Package

quilc.

Source

entry-point.lisp.

Function: asynchronously-indicate-update-availability (current-version &key proxy)

Write to the logger the state of the software version (whether it’s the latest, if there’s an update, if an update couldn’t be queried).

Package

quilc.

Source

versions.lisp.

Function: backend-compile-program (program chip-spec backend output)

Compile the processed program PROGRAM for BACKEND, writing to OUTPUT.

Package

quilc.

Source

entry-point.lisp.

Function: benchmarks ()
Package

quilc.

Source

entry-point.lisp.

Function: check-libraries ()

Check that the foreign libraries are adequate. Exits with status 0 if so, 1 if not.

Package

quilc.

Source

entry-point.lisp.

Function: chip-cache-or-create (qpu-hash)

Look up the chip described by QPU-HASH in the chip spec cache if it exists, otherwise create and cache it.

This function has the added side-effect that it will purge old chips according to *CHIP-CACHE-MAX-SIZE*

Package

quilc.

Source

chip-cache.lisp.

Function: chip-cache-purge ()

Purge the least recently used entries in *CHIP-CACHE* according to *CHIP-CACHE-MAX-SIZE*.

After calling this function, *CHIP-CACHE* has at most *CHIP-CACHE-MAX-SIZE* entries.

Package

quilc.

Source

chip-cache.lisp.

Function: command-line-debugger (condition previous-hook)
Package

quilc.

Source

entry-point.lisp.

Function: compute-statistics (processed-program chip-specification statistics &key gate-whitelist gate-blacklist)

Compute statistics about protoquil program PROCESSED-PROGRAM.

This function will have undefined behavior when PROCESSED-PROGRAM is not protoquil.

Package

quilc.

Source

entry-point.lisp.

Function: conjugate-pauli-by-clifford-handler (request)

Conjugates a Pauli operator by a Clifford operator, as specified by REQUEST.

Package

quilc.

Source

rpc-server.lisp.

Function: disable-debugger ()
Package

quilc.

Source

impl/sbcl.lisp.

Function: enable-debugger ()
Package

quilc.

Source

impl/sbcl.lisp.

Function: ensure-optional-real (x)
Package

quilc.

Source

rpc-server.lisp.

Function: entry-point (argv)
Package

quilc.

Source

entry-point.lisp.

Function: generate-rb-sequence-handler (request)

Generates a randomized benchmarking sequence according to REQUEST.

Package

quilc.

Source

rpc-server.lisp.

Function: get-internal-real-time-seconds ()
Package

quilc.

Source

chip-cache.lisp.

Function: get-version-info-handler ()
Package

quilc.

Source

rpc-server.lisp.

Function: git-hash (system)

Get the short git hash of the system SYSTEM.

Package

quilc.

Source

versions.lisp.

Function: log-level-string-to-symbol (log-level)
Package

quilc.

Source

entry-point.lisp.

Function: lookup-isa-descriptor-for-name (isa)
Package

quilc.

Source

entry-point.lisp.

Function: native-quil-to-binary-handler (request)

Dummy invocation: this QUILC binary returns something QVM-executable, which is just the program again.

Package

quilc.

Source

rpc-server.lisp.

Function: parse-backend-options (options)

Parse backend options to keyword init-args for making backend.

Package

quilc.

Source

entry-point.lisp.

Function: print-matrix-comparision (m1 m2 &optional stream)
Package

quilc.

Source

printers.lisp.

Function: print-matrix-with-comment-hashes (matrix &optional stream)
Package

quilc.

Source

entry-point.lisp.

Function: print-program (processed-program &optional stream)
Package

quilc.

Source

printers.lisp.

Function: print-statistics (statistics &optional stream)
Package

quilc.

Source

printers.lisp.

Function: process-options (&rest all-args &key prefer-gate-ladders compute-gate-depth compute-gate-volume compute-runtime compute-fidelity compute-matrix-reps compute-2q-gate-depth compute-unused-qubits show-topological-overhead json-serialize gate-blacklist gate-whitelist without-pretty-printing print-logical-schedule verbose isa compile backend backend-option list-backends output enable-state-prep-reductions protoquil print-statistics print-circuit-definitions version check-libraries benchmark server-mode-rpc host port chip-cache time-limit help log-level quiet check-sdk-version proxy safe-include-directory swank-port)
Package

quilc.

Source

entry-point.lisp.

Function: process-program (program chip-specification &key protoquil state-aware verbose gate-whitelist gate-blacklist)

Compile PROGRAM for the chip CHIP-SPECIFICATION. Optionally calculate statistics described by the keyword arguments. All require :PROTOQUIL T.

Note: PROGRAM is mutated by the compilation process. To avoid this, use COPY-INSTANCE.

Returns a values tuple (PROCESSED-PROGRAM, STATISTICS), where PROCESSED-PROGRAM is the compiled program, and STATISTICS is a HASH-TABLE whose keys are the slots of the RPCQ::|NativeQuilMetadata| class.

Package

quilc.

Source

entry-point.lisp.

Function: query-latest-sdk-version (&key proxy)

Get the latest SDK quilc version, or NIL if unavailable.

Package

quilc.

Source

versions.lisp.

Function: quil-to-native-quil-handler (request &key protoquil state-aware)

Traditional QUILC invocation: compiles a Quil program to native Quil, as specified by an ISA.

Package

quilc.

Source

rpc-server.lisp.

Function: reload-foreign-libraries ()
Package

quilc.

Source

entry-point.lisp.

Function: rewrite-arithmetic-handler (request)

Rewrites the request program without arithmetic in gate parameters.

Package

quilc.

Source

rpc-server.lisp.

Function: runtime-estimation (parsed-protoquil-program)

Estimated QPU runtime of PARSED-PROTOQUIL-PROGRAM. Likely to be an over-estimate for small depth programs, where runtime is dominated by network latency and compilation, etc. Take these results with a grain of salt.

Package

quilc.

Source

rpc-server.lisp.

Function: sdk-update-available-p (current-version &key proxy)

Test whether the current SDK version is the latest SDK version. Second value returned indicates the latest version.

Package

quilc.

Source

versions.lisp.

Function: setup-debugger ()
Package

quilc.

Source

entry-point.lisp.

Function: show-backends ()
Package

quilc.

Source

entry-point.lisp.

Function: show-banner ()
Package

quilc.

Source

entry-point.lisp.

Function: show-help ()
Package

quilc.

Source

entry-point.lisp.

Function: show-version ()
Package

quilc.

Source

entry-point.lisp.

Function: slurp-lines (&optional stream)
Package

quilc.

Source

entry-point.lisp.

Function: start-rpc-server (&key protocol host port logger time-limit)
Package

quilc.

Source

rpc-server.lisp.

Function: statistics-to-metadata (statistics)
Package

quilc.

Source

rpc-server.lisp.

Function: strip-final-halt-respecting-rewirings (processed-program)

Remove the final HALT instruction, if any, from PROCESSED-PROGRAM, retaining any attached rewiring comments.

Package

quilc.

Source

entry-point.lisp.

Function: system-version (system-designator)
Package

quilc.

Source

versions.lisp.

Function: warn-deprecated-options (args)

Print a warning message if the server is started with deprecated options (see *DEPRECATED-OPTION-SPEC*).

Package

quilc.

Source

entry-point.lisp.

Function: warn-ignored-options (args)

Print a warning message if the server is started with deprecated options (see *DEPRECATED-OPTION-SPEC*).

Package

quilc.

Source

entry-point.lisp.


5.2.5 Generic functions

Generic Reader: cached-chip-addresser-state (object)
Package

quilc.

Methods
Reader Method: cached-chip-addresser-state ((cached-chip cached-chip))

automatically generated reader method

Source

chip-cache.lisp.

Target Slot

addresser-state.

Generic Writer: (setf cached-chip-addresser-state) (object)
Package

quilc.

Methods
Writer Method: (setf cached-chip-addresser-state) ((cached-chip cached-chip))

automatically generated writer method

Source

chip-cache.lisp.

Target Slot

addresser-state.

Generic Reader: cached-chip-chip (object)
Package

quilc.

Methods
Reader Method: cached-chip-chip ((cached-chip cached-chip))

automatically generated reader method

Source

chip-cache.lisp.

Target Slot

chip.

Generic Writer: (setf cached-chip-chip) (object)
Package

quilc.

Methods
Writer Method: (setf cached-chip-chip) ((cached-chip cached-chip))

automatically generated writer method

Source

chip-cache.lisp.

Target Slot

chip.

Generic Reader: cached-chip-last-accessed (object)
Package

quilc.

Methods
Reader Method: cached-chip-last-accessed ((cached-chip cached-chip))

automatically generated reader method

Source

chip-cache.lisp.

Target Slot

last-accessed.

Generic Writer: (setf cached-chip-last-accessed) (object)
Package

quilc.

Methods
Writer Method: (setf cached-chip-last-accessed) ((cached-chip cached-chip))

automatically generated writer method

Source

chip-cache.lisp.

Target Slot

last-accessed.


5.2.6 Classes

Class: cached-chip

Represents chip and addresser state cached between server requests.

Package

quilc.

Source

chip-cache.lisp.

Direct methods
Direct slots
Slot: last-accessed
Type

real

Initargs

:last-accessed

Readers

cached-chip-last-accessed.

Writers

(setf cached-chip-last-accessed).

Slot: chip
Type

quilc::chip-specification

Initargs

:chip

Readers

cached-chip-chip.

Writers

(setf cached-chip-chip).

Slot: addresser-state
Type

cl-quil::addresser-state

Initargs

:addresser-state

Readers

cached-chip-addresser-state.

Writers

(setf cached-chip-addresser-state).


5.2.7 Types

Type: interactive-interrupt ()
Package

quilc.

Source

impl/sbcl.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   B   C   D   E   F   G   L   M   N   P   Q   R   S   W  
Index Entry  Section

%
%entry-point: Private ordinary functions

(
(setf cached-chip-addresser-state): Private generic functions
(setf cached-chip-addresser-state): Private generic functions
(setf cached-chip-chip): Private generic functions
(setf cached-chip-chip): Private generic functions
(setf cached-chip-last-accessed): Private generic functions
(setf cached-chip-last-accessed): Private generic functions

A
asynchronously-indicate-update-availability: Private ordinary functions

B
backend-compile-program: Private ordinary functions
benchmarks: Private ordinary functions

C
cached-chip-addresser-state: Private generic functions
cached-chip-addresser-state: Private generic functions
cached-chip-chip: Private generic functions
cached-chip-chip: Private generic functions
cached-chip-last-accessed: Private generic functions
cached-chip-last-accessed: Private generic functions
check-libraries: Private ordinary functions
chip-cache-or-create: Private ordinary functions
chip-cache-purge: Private ordinary functions
command-line-debugger: Private ordinary functions
compute-statistics: Private ordinary functions
conjugate-pauli-by-clifford-handler: Private ordinary functions

D
disable-debugger: Private ordinary functions

E
enable-debugger: Private ordinary functions
ensure-optional-real: Private ordinary functions
entry-point: Private ordinary functions

F
Function, %entry-point: Private ordinary functions
Function, asynchronously-indicate-update-availability: Private ordinary functions
Function, backend-compile-program: Private ordinary functions
Function, benchmarks: Private ordinary functions
Function, check-libraries: Private ordinary functions
Function, chip-cache-or-create: Private ordinary functions
Function, chip-cache-purge: Private ordinary functions
Function, command-line-debugger: Private ordinary functions
Function, compute-statistics: Private ordinary functions
Function, conjugate-pauli-by-clifford-handler: Private ordinary functions
Function, disable-debugger: Private ordinary functions
Function, enable-debugger: Private ordinary functions
Function, ensure-optional-real: Private ordinary functions
Function, entry-point: Private ordinary functions
Function, generate-rb-sequence-handler: Private ordinary functions
Function, get-internal-real-time-seconds: Private ordinary functions
Function, get-version-info-handler: Private ordinary functions
Function, git-hash: Private ordinary functions
Function, log-level-string-to-symbol: Private ordinary functions
Function, lookup-isa-descriptor-for-name: Private ordinary functions
Function, native-quil-to-binary-handler: Private ordinary functions
Function, parse-backend-options: Private ordinary functions
Function, print-matrix-comparision: Private ordinary functions
Function, print-matrix-with-comment-hashes: Private ordinary functions
Function, print-program: Private ordinary functions
Function, print-statistics: Private ordinary functions
Function, process-options: Private ordinary functions
Function, process-program: Private ordinary functions
Function, query-latest-sdk-version: Private ordinary functions
Function, quil-to-native-quil-handler: Private ordinary functions
Function, reload-foreign-libraries: Private ordinary functions
Function, rewrite-arithmetic-handler: Private ordinary functions
Function, runtime-estimation: Private ordinary functions
Function, sdk-update-available-p: Private ordinary functions
Function, setup-debugger: Private ordinary functions
Function, show-backends: Private ordinary functions
Function, show-banner: Private ordinary functions
Function, show-help: Private ordinary functions
Function, show-version: Private ordinary functions
Function, slurp-lines: Private ordinary functions
Function, start-rpc-server: Private ordinary functions
Function, statistics-to-metadata: Private ordinary functions
Function, strip-final-halt-respecting-rewirings: Private ordinary functions
Function, system-version: Private ordinary functions
Function, warn-deprecated-options: Private ordinary functions
Function, warn-ignored-options: Private ordinary functions

G
generate-rb-sequence-handler: Private ordinary functions
Generic Function, (setf cached-chip-addresser-state): Private generic functions
Generic Function, (setf cached-chip-chip): Private generic functions
Generic Function, (setf cached-chip-last-accessed): Private generic functions
Generic Function, cached-chip-addresser-state: Private generic functions
Generic Function, cached-chip-chip: Private generic functions
Generic Function, cached-chip-last-accessed: Private generic functions
get-internal-real-time-seconds: Private ordinary functions
get-version-info-handler: Private ordinary functions
git-hash: Private ordinary functions

L
log-level-string-to-symbol: Private ordinary functions
lookup-isa-descriptor-for-name: Private ordinary functions

M
Macro, special-bindings-let*: Private macros
Method, (setf cached-chip-addresser-state): Private generic functions
Method, (setf cached-chip-chip): Private generic functions
Method, (setf cached-chip-last-accessed): Private generic functions
Method, cached-chip-addresser-state: Private generic functions
Method, cached-chip-chip: Private generic functions
Method, cached-chip-last-accessed: Private generic functions

N
native-quil-to-binary-handler: Private ordinary functions

P
parse-backend-options: Private ordinary functions
print-matrix-comparision: Private ordinary functions
print-matrix-with-comment-hashes: Private ordinary functions
print-program: Private ordinary functions
print-statistics: Private ordinary functions
process-options: Private ordinary functions
process-program: Private ordinary functions

Q
query-latest-sdk-version: Private ordinary functions
quil-to-native-quil-handler: Private ordinary functions

R
reload-foreign-libraries: Private ordinary functions
rewrite-arithmetic-handler: Private ordinary functions
runtime-estimation: Private ordinary functions

S
sdk-update-available-p: Private ordinary functions
setup-debugger: Private ordinary functions
show-backends: Private ordinary functions
show-banner: Private ordinary functions
show-help: Private ordinary functions
show-version: Private ordinary functions
slurp-lines: Private ordinary functions
special-bindings-let*: Private macros
start-rpc-server: Private ordinary functions
statistics-to-metadata: Private ordinary functions
strip-final-halt-respecting-rewirings: Private ordinary functions
system-version: Private ordinary functions

W
warn-deprecated-options: Private ordinary functions
warn-ignored-options: Private ordinary functions


A.3 Variables

Jump to:   *   +  
A   C   L   S  
Index Entry  Section

*
*chip-cache*: Private special variables
*chip-cache-max-size*: Private special variables
*deprecated-option-spec*: Private special variables
*human-readable-stream*: Private special variables
*ignored-option-spec*: Private special variables
*log-level*: Private special variables
*logger*: Private special variables
*nick-banner*: Private special variables
*option-spec*: Private special variables
*program-name*: Private special variables
*protoquil*: Private special variables
*quil-stream*: Private special variables
*retired-option-spec*: Private special variables
*state-aware*: Private special variables
*without-pretty-printing*: Private special variables

+
+git-hash+: Private constants
+quilc-version+: Private constants

A
addresser-state: Private classes

C
chip: Private classes
Constant, +git-hash+: Private constants
Constant, +quilc-version+: Private constants

L
last-accessed: Private classes

S
Slot, addresser-state: Private classes
Slot, chip: Private classes
Slot, last-accessed: Private classes
Special Variable, *chip-cache*: Private special variables
Special Variable, *chip-cache-max-size*: Private special variables
Special Variable, *deprecated-option-spec*: Private special variables
Special Variable, *human-readable-stream*: Private special variables
Special Variable, *ignored-option-spec*: Private special variables
Special Variable, *log-level*: Private special variables
Special Variable, *logger*: Private special variables
Special Variable, *nick-banner*: Private special variables
Special Variable, *option-spec*: Private special variables
Special Variable, *program-name*: Private special variables
Special Variable, *protoquil*: Private special variables
Special Variable, *quil-stream*: Private special variables
Special Variable, *retired-option-spec*: Private special variables
Special Variable, *state-aware*: Private special variables
Special Variable, *without-pretty-printing*: Private special variables


A.4 Data types