Q needs you

It’s time for Q to grow. But it’s also 2020—we’re right in the middle of the COVID-19 global pandemic. Are you in need of a project to take your mind off current events? Do you love JavaScript, CSS, and the free Web? How about breaking down complex subjects into simple bite-sized chunks of copywriting and minimalist diagrams? Are you a graphic designer or copywriter? Are you excited about quantum computing? Join our Q.js project on GitHub, create or resolve some issues, and help us make quantum accessible!

Read the following sections to familiarize yourself with Q’s objectives, inspirations, and plans for the future.


Thursday, 30 April 2020, is our one-year anniversary. From conception 12 months ago to now we’ve built a functioning code API and a drag-and-drop circuit editor. While there are still many exciting features to add, and a list of issues to resolve, this anniversary is a milestone worth celebrating. As initial work on the circuit editor interface winds down our focus will shift back to optimization of the simulator itself. During Summer 2020 our primary focus will be wrangling multiple execution threads and hardware acceleration via WebGPU. On the back burner we’ll be adding new import and export utilities to make hopping between Q and other quantum suites a breeze.

Documentation style

Concepts included

For most people anything “quantum” is brand new. Even the simpler mathematics are things that most folks probably haven’t seen since high school. (When’s the last time the average person actually had to think about complex numbers?) If we’re going to make quantum accessible we need to include simple / legible / digestible concept primers for these topics right in the documentation, and also provide links to learning resources.

To this end documentation for Q classes—such as Q.Matrix, Q.Qubit, and so on—include brief explanations of the mathematics that the class represents before diving into the code and usage specifics. We also provide a separate Resources page with links to learn more about quantum computing in general.


This collection of HTML files serve as Q’s interactive documentation. Its design objectives are tidiness, shareability, and consistency. When possible the general UI features, such as the main navigation or body modules, are visually flat. Buttons intended to be “pushed” or circuit operations intended to be “dragged and dropped” may be represented as dimensional.

JavaScript style

Programs must be written for people to read, and only incidentally for machines to execute.

Structure and Interpretation of Computer Programs,
Preface to the first edition

Q’s source code is verbose, heavily commented, and there’s great empathy for fellow learners. Visual hierarchy is key when facing a brick of monospace code gibberish. White space helps; white space around variables, between conceptually different blocks of code. (You’ve got to let code breathe.) Semicolons as line-enders are avoided unless absolutely necessary. (They’re just visual clutter otherwise; typographic noise in the signal.) Q is meant to be flexible and expressive to adapt to your style. “Fluent interface” method chaining is prized, but Q often uses static class methods as a foundation for instance methods, so you’re free to use either approach.

Low barrier to entry

Not everyone’s a grizzled software engineer—nor should they be. If you’re reading this on any desktop or laptop, you already have all the tools you need to start playing with Q. And “getting started” shouldn’t require installing new applications, signing up for new accounts, or spinning up a server thread from the command line just to load a website and play. (That’s one reason Q does not use JavaScript modules.) Just drag and drop any HTML file from Q’s code repository onto your browser window and you’re up and running. This is the beauty of Sir Tim’s World Wide Web and every single person who has ever contributed to the art of the browser. In general you can always add more layers to something—install what you will, tweak how you like. But removing layers is damn near impossible. Q aims to ship with few layers.

Hackable by design

Q places heavy emphasis on the ability to inspect anything right from your own browser console in realtime. This is one of the reasons Q shuns JavaScript modules, is sensitive to the use of closures, and hangs all of its functionality off of the Q object which sits in the global scope For us “hackability” is important—particularly for teaching and learning. By “hackable” we mean heavily inspectable and customizable by the curious—novice and expert alike. We do not not mean “hackable” as in “containing security flaws.”

Less Java, more JavaScript

Some ES6 syntax is preferred, but the bits that disfigure JavaScript to look more like Java, C++, C#, etc. are weeded out, bagged, and tossed in the river. There is nothing wrong with prototypal inheritance and it’s in fact more powerful than classical inheritance. JavaScript is uniquely beautiful in its flexibility and to paper over that with “class”, or ignore the power of closures, or pretend private variables weren’t possible prior to 2015 is like confusing an aptitude for Rock Band with actual musicianship.

While Q’s internal code uses let and const when declaring variables, the examples here use var instead; redeclare and overwrite example variables to your heart’s content.

Destructive vs non-destructive methods

Q pays particular attention to destructive versus non-destructive instance methods. For example, the archetypal non-destructive method is .clone() which returns a new sibling instance of the object it was called from and by its nature makes no alterations to that original object. In contrast, .copy$( sibling ) is the archetypal destructive method which causes an instance to alter itself by overwriting its own properties’ values with values from a sibling instance, then returns itself. The dollar sign suffix is similar to Ruby’s exclamation point suffix and is a reminder that the operation is destructive; will alter the instance.

cat = new Q.ComplexNumber( 1,  2 ),
dog = new Q.ComplexNumber( 3, -4 )

cat.toText()   //  Returns '1 + 2i'
dog.toText()   //  Returns '3 - 4i'

cat.add( dog ) //  Non-destructive.
cat.toText()   //  Still returns '1 + 2i'

cat.add$( dog )//  Destructive. Note the ‘$’ suffix.
cat.toText()   //  Now returns '4 - 2i'

The notable exception to this is the “Python-inspired” circuit editing syntax which uses convenience functions not suffixed with a dollar sign. This allows creating a circuit in Q to more closely resemble editing a Python script for Amazon Braket, IBM Qiskit, and so on:

Q( 2, 2 )
	.h( 1, 1 )
	.x( 2, [ 1, 2 ])

CSS style

Similar to our JavaScript style, our CSS eschews modules and shadow DOM containers in favor of carefully named global variables. We feel it should be easy for you, the developer, to be able to remix and reconfigure Q with ease. Reuse the Q classes, customize them, or leave them be. (Any box is a “black box” if you don’t look inside it.) Our CSS variables are prefixed with “--Q” and several categories, such as color palette values, are exposed for your convenience.