Welcome to Q.js

Q is a quantum circuit editor and simulator that runs right in your Web browser. There is nothing to install and nothing to configure. Just by loading this website you have already loaded Q’s entire sweet of quantum tools. In fact, here’s your first quantum circuit—a Bell state. Tap and drag the pieces around to get a feel for the Q editor. It’s okay to make mistakes. Support for dragging multi-register gates (and more!) coming in May 2020. Stay tuned.

Q is free to use, open-source, and includes simple explanations to get you up to speed on the basics of quantum computing. This makes Q ideal for the classroom as well as autodidacts at home. Q just might be the most accessible quantum circuit suite in the world. You can even export your circuit designs and port them over to other quantum suites. Q’s source code—including this documentation—is available for download from GitHub at https://github.com/stewdio/q.js and this documentation website is live at https://stewdio.github.io/q.js

Open your JavaScript console

Do you code? (Want to learn?) If you’re on a desktop or laptop you can use the handy key-command chart below to pop open your browser’s JavaScript console and begin exploring Q from the inside.

  macOS Windows
Firefox K
Option Command K
Control Shift K
Chrome J
Option Command J
Control Shift I
Edge J
Option Command J
Safari C
Option Command C

Quantum JavaScript

You don’t need to know a thing about quantum physics or JavaScript to launch your first qubit in to superposition. Just copy and paste the following line in to your JavaScript console. (Note that those are backticks on either side of the H, not single quotation marks.)

Q`H`.try$() ? 'heads' : 'tails'

Did you try it? You just performed a quantum coin flip. Each time you run the above code there’s a 50% chance of landing on heads (1) and a 50% chance of landing on tails (0). Go ahead and try it out. When you’re ready for more, give “Writing quantum circuits” a quick read.

Code style

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. Some ES6 syntax is preferred, but the bits that disfigure JavaScript to look more like Java are weeded out, bagged, and tossed in the river.

Q’s main goal is to make learning and experimenting with quantum computing easier—not harder. 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. Similarly, Q is composed of plain old JavaScript includes rather than modules. Because of this, all of Q can run directly from your desktop using the file:// protocol with no server required. Just drag and drop any of Q’s HTML files on to your browser window. You can also inspect any piece of Q right from the console as its running.

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'

Documentation interface style

This collection of HTML files serves as Q’s interactive documentation. It’s 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” are represented as dimensional.


As of March 2020 we are focussed on refining the editor interface and adding features to it. The highest priority is including editor support for controlled gates. (Controlled gates are already supported directly in code.) Following these editor updates the priority will shift back to the simulator itself. Optimization is key, including multiple execution threads and hardware acceleration via WebGPU.

Want to get involved? Are you a quantum computation expert? Do you love JavaScript and the free Web? How about breaking down complex subjects in to simple bite-sized chunks of copywriting and minimalist diagrams? Help us by creating (or resolving) issues on Q’s GitHub repository. Let’s make quantum computing accessible!