-
Notifications
You must be signed in to change notification settings - Fork 30
/
contributing.html
273 lines (263 loc) · 14.1 KB
/
contributing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
<!DOCTYPE html>
<html>
<head>
<title>Q ⟩ Contributing</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<meta name="description" content="Quantum computing in your browser.">
<meta name="copyright" content="Stewart Smith 2019–2020">
<meta name="keywords" content="
Q, Q.js, Q-js, Qjs, quantum JavaScript,
quantum, quantum physics, quantum mechanics, superposition,
quantum computer, quantum computer programming, quantum computing, QC,
quantum simulator, quantum computer simulator,
qubit, qbit, gate, Hadamard, Bloch, Bloch Sphere,
Web, Web site, website, Web browser, browser, HTML, HTML5, JavaScript, ES6, CSS,
Chrome, Firefox, Safari, Opera, Brave, Edge, WebKit, Blink, Gecko, Mozilla,
Stewart Smith, Stewart, Stew, Stuart, Steven, Steve, Stewdio, stewartsmith, stew_rtsmith, @stew_rtsmith,
Moar, Moar Technologies Corp, MTC,
Google, IBM, Microsoft, Amazon, NASA, DWave, D-Wave,
Quil, OpenQASM,
ProjectQ, Qiskit,
Quantum Development Kit, Cirq, Strawberry Fields, t|ket>,
QCL, Quantum pseudocode, Q#, Q|SI>, Q language, qGCL, QFC, QML, LIQUi|>, Quipper,
Stanford CS 269 Q: Quantum Computer Programming">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@stew_rtsmith">
<meta name="twitter:creator" content="@stew_rtsmith">
<meta name="twitter:title" content="Q ⟩ Contributing">
<meta name="twitter:description" content="Quantum computing in your browser.">
<meta name="twitter:image" content="https://quantumjavascript.app/assets/Q-website-preview.jpg">
<meta property="og:type" content="website">
<meta property="og:title" content="Q ⟩ Contributing">
<meta property="og:description" content="Quantum computing in your browser.">
<meta property="og:image" content="https://quantumjavascript.app/assets/Q-website-preview.jpg">
<meta property="og:url" content="https://quantumjavascript.app/contributing.html">
<link rel="canonical" href="https://quantumjavascript.app/contributing.html">
<link href="assets/Q-favicon-064.png" rel="icon" type="image/png">
<link href="assets/Q-favicon-144.png" rel="apple-touch-icon">
<link rel="stylesheet" href="Q/Q.css">
<link rel="stylesheet" href="Q/Q-Circuit-Editor.css">
<link rel="stylesheet" href="assets/documentation.css">
<script src="https://www.googletagmanager.com/gtag/js" async></script>
<script src="assets/ga.js"></script>
<script src="Q/Q.js"></script>
<script src="Q/Q-ComplexNumber.js"></script>
<script src="Q/Q-Matrix.js"></script>
<script src="Q/Q-Qubit.js"></script>
<script src="Q/Q-Gate.js"></script>
<script src="Q/Q-History.js"></script>
<script src="Q/Q-Circuit.js"></script>
<script src="Q/Q-Circuit-Editor.js"></script>
<script src="assets/navigation.js"></script>
</head>
<body>
<main>
<h3>Q needs you</h3>
<p>
It’s time for Q to grow.
But it’s also 2020—we’re right in the middle of the
<a href="https://en.wikipedia.org/wiki/Coronavirus_disease_2019" target="_blank">COVID-19</a> 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
<a href="https://en.wikipedia.org/wiki/Copywriting" target="_blank">copywriting</a> and minimalist diagrams?
Are you a graphic designer or copywriter?
Are you excited about quantum computing?
<a href="https://github.com/stewdio/q.js" target="_blank">Join our Q.js project on GitHub</a>,
<a href="https://github.com/stewdio/q.js/issues" target="_blank">create or resolve some issues</a>,
and help us make quantum accessible!
</p>
<p>
Read the following sections to familiarize yourself
with Q’s objectives, inspirations, and plans for the future.
</p>
<h4>Roadmap</h4>
<p>
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
<a href="https://github.com/stewdio/q.js/issues" target="_blank">issues to resolve</a>,
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
<a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers" target="_blank">multiple execution threads</a> and hardware acceleration via
<a href="https://en.wikipedia.org/wiki/WebGPU" target="_blank">WebGPU</a>.
On the back burner
we’ll be adding new import and export utilities
to make hopping between Q and other quantum suites a breeze.
</p>
<h4>Documentation style</h4>
<h5>Concepts included</h5>
<p>
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
<a href="Q-ComplexNumber.html">complex numbers</a>?)
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.
</p>
<p>
To this end documentation for Q classes—such as
<a href="Q-Matrix.html">Q.Matrix</a>,
<a href="Q-Qubit.html">Q.Qubit</a>,
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
<a href="resources.html">Resources page</a>
with links to learn more about quantum computing in general.
</p>
<h5>Interface</h5>
<p>
This collection of <code>HTML</code> 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.
</p>
<h4>JavaScript style</h4>
<blockquote cite="https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html#%_chap_Temp_4">Programs must be written for people to read, and only incidentally for machines to execute.</blockquote>
<cite>
<p>
<a href="https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html#%_chap_Temp_4" target="_blank">Structure and Interpretation of Computer Programs,<br>
Preface to the first edition</a>
</p>
</cite>
<p>
Q’s source code is verbose, heavily commented, and there’s great empathy for fellow learners.
<a href="https://en.wikipedia.org/wiki/Visual_hierarchy" target="_blank">Visual hierarchy</a> is key when facing a brick of monospace code gibberish.
<a href="https://en.wikipedia.org/wiki/White_space_(visual_arts)" target="_blank">White space</a> 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; <a href="https://en.wikipedia.org/wiki/Typography" target="_blank">typographic</a> noise in the signal.)
Q is meant to be flexible and expressive to adapt to your style.
<a href="https://en.wikipedia.org/wiki/Fluent_interface" target="_blank">“Fluent interface” method chaining</a> is prized, but Q often uses static class methods as a foundation for instance methods, so you’re free to use either approach.
</p>
<h5>Low barrier to entry</h5>
<p>
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
<strong>not use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules" target="_blank">JavaScript modules</a></strong>.)
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 <a href="https://en.wikipedia.org/wiki/History_of_the_World_Wide_Web" target="_blank">Sir Tim’s World Wide Web</a>
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.
</p>
<h5>Hackable by design</h5>
<p>
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
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules" target="_blank">JavaScript modules</a>,
is sensitive to the use of
<a href="https://en.wikipedia.org/wiki/Closure_(computer_programming)#State_representation" target="_blank">closures</a>,
and hangs all of its functionality off of the
<a href="Q.html" target="_blank">Q object</a>
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.”
</p>
<h5>Less Java, more JavaScript</h5>
<p>
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
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain" target="_blank">prototypal inheritance</a>
and it’s in fact
<a href="https://www.crockford.com/javascript/inheritance.html" target="_blank">more powerful than classical inheritance</a>.
JavaScript is uniquely beautiful in its flexibility
and to paper over that with
“<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes" target="_blank"><code>class</code></a>”,
or ignore the power of
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures" target="_blank">closures</a>,
or pretend private variables weren’t possible prior to 2015
is like confusing an aptitude for Rock Band
with actual musicianship.
</p>
<p>
While Q’s internal code uses <code>let</code> and <code>const</code> when declaring variables,
the examples here use <code>var</code> instead;
redeclare and overwrite example variables to your heart’s content.
</p>
<h5>Destructive vs non-destructive methods</h5>
<p>
Q pays particular attention to <em>destructive</em> versus <em>non-destructive</em> instance methods.
For example, the archetypal <em>non-destructive</em> method is <code>.<strong>clone</strong>()</code>
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, <code>.<strong>copy</strong>$( sibling )</code> is the archetypal <em>destructive</em> 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
<a href="https://en.wikipedia.org/wiki/Ruby_(programming_language)" target="_blank">Ruby</a>’s
exclamation point suffix and is a reminder that the operation is destructive; will alter the instance.
</p>
<pre><code>
var
cat = new <a href="Q.html">Q</a>.<a href="Q-ComplexNumber.html">ComplexNumber</a>( 1, 2 ),
dog = new <a href="Q.html">Q</a>.<a href="Q-ComplexNumber.html">ComplexNumber</a>( 3, -4 )
cat.<a href="Q-ComplexNumber.html#.toText">toText</a>() <span class="comment">// Returns '1 + 2i'</span>
dog.<a href="Q-ComplexNumber.html#.toText">toText</a>() <span class="comment">// Returns '3 - 4i'</span>
cat.<a href="Q-ComplexNumber.html#.add"><strong>add</strong></a>( dog ) <span class="comment">// Non-destructive.</span>
cat.<a href="Q-ComplexNumber.html#.toText">toText</a>() <span class="comment">// Still returns '1 + 2i'</span>
cat.<a href="Q-ComplexNumber.html#.add$"><strong>add$</strong></a>( dog )<span class="comment">// Destructive. Note the ‘$’ suffix.</span>
cat.<a href="Q-ComplexNumber.html#.toText">toText</a>() <span class="comment">// Now returns '4 - 2i'</span>
</pre></code>
<p>
The notable exception to this is the “Python-inspired”
circuit editing syntax
which uses convenience functions <strong>not</strong>
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:
</p>
<pre><code>
<a href="Q.html">Q</a>( 2, 2 )
.h( 1, 1 )
.x( 2, [ 1, 2 ])
</code></pre>
<h4>CSS style</h4>
<p>
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
<a href="https://en.wikipedia.org/wiki/Black_box" target="_blank">“black box”</a> if you don’t look inside it.)
Our CSS variables are prefixed with “<code>--Q</code>”
and several categories, such as color palette values,
are exposed for your convenience.
</p>
</main>
</body>
</html>