fork/numbat

git clone https://git.julia.blue/fork/numbat

David PeterMinor updates038ab76

master
12.1 KiB216 linesraw
1<!DOCTYPE html>
2<html lang="en">
3<head>
4    <meta charset="UTF-8">
5    <meta name="viewport" content="width=device-width, initial-scale=1.0">
6    <meta name="author" content="David Peter">
7    <title>Introducing Numbat</title>
8    <meta property="og:type" content="website">
9    <meta property="og:image" content="https://numbat.dev/numbat.png">
10    <meta property="og:title" content="Introducing Numbat: The type system">
11    <meta property="og:url" content="https://numbat.dev/articles/intro.html">
12    <meta property="og:description" content="Introduces the programming language Numbat and its type system">
13    <link rel="stylesheet" href="main.css">
14    <script src="pkg/ace.min.js"></script>
15</head>
16<body>
17
18<article class="blog-post">
19    <h1 style="margin-bottom: 0.5em">Introducing Numbat</h1>
20
21    <p style="margin-top: 0"><i>Part I: The type system</i></p>
22
23    <p>Numbat is a programming language that aims to provide a convenient way
24    to perform computations with physical units.
25    One of the main goals of the language is to help users write <em>correct</em> programs.
26
27    It has a static type system where <em>physical dimensions</em> act as types.
28    The expression <code><span class="numbat-value">3</span> <span class="numbat-unit">months</span></code>, for example, has a <em>type</em> of <code class="numbat-type-identifier">Time</code>.
29    Similarly, the expression <code><span class="numbat-value">2</span> <span class="numbat-unit">years</span></code> also has a type of <code class="numbat-type-identifier">Time</code>.
30    The compound expression <code><span class="numbat-value">3</span> <span class="numbat-unit">months</span> + <span class="numbat-value">2</span> <span class="numbat-unit">years</span></code> is therefore well-typed:
31    </p>
32
33    <div id="editor1" class="code-editor">3 months + 2 years    # you can edit these examples!</div>
34    <pre id="output1" class="numbat-output"></pre>
35
36    <p>
37    On the other hand, <code><span class="numbat-value">3</span> <span class="numbat-unit">months</span> + <span class="numbat-value">2</span> <span class="numbat-unit">lightyears</span></code> is <em>ill</em>-typed, because the right-hand side is of type <code class="numbat-type-identifier">Length</code>.
38    You can change &lsquo;years&rsquo; to &lsquo;lightyears&rsquo; in the editor above to see the resulting compiler error.
39    </p>
40
41    <p>
42    Before we describe the type system in more detail, let's look at two simple examples. The first program
43    computes the oscillation period of a (mathematical) pendulum using the gravitational acceleration
44    <code>g0</code>.
45    Note that you can change the unit of the pendulum length to, say, <code span="numbat-unit">inch</code> without
46    having to change the type annotations. This is in contrast to a lot of unit libraries in other
47    programming languages that typically lift <em>units</em> &mdash; not the physical dimensions &mdash; to the type level.
48
49    Also, note that you can completely remove the explicit <code><span class="ace_operator">:</span> <span class="numbat-type-identifier">Type</span></code> annotations and let the compiler infer the types:
50    </p>
51
52    <div id="editor2" class="code-editor">let pendulum_length: Length = 30 cm
53let t_oscillation: Time = 2 π sqrt(pendulum_length / g0)
54
55t_oscillation</div>
56    <pre id="output2" class="numbat-output"></pre>
57
58    <div class="spacer"></div>
59
60    <p>The second example demonstrates how explicit type annotations
61    can help avoid mistakes. We want to compute the ratio of gravitational forces exerted on Earth by both the Sun and the Moon.
62    However, the computation contains a mistake. Try to annotate the definitions of <code>force_sun</code> and <code>force_moon</code> with the intended <span class="numbat-type-identifier">Force</span> dimension
63    and see if the compiler error can help you fix the <a href="https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation">equations</a>.
64    The correct result should be closer to <code class="numbat-value">180</code>.
65    </p>
66
67    <div id="editor3" class="code-editor">let distance_sun: Length = 1 AU  # astronomical unit
68let distance_moon: Length = 384_400 km
69
70let force_sun = G * earth_mass * solar_mass / distance_sun
71let force_moon = G * earth_mass * lunar_mass / distance_moon
72
73force_sun / force_moon</div>
74    <pre id="output3" class="numbat-output"></pre>
75
76    <div class="spacer"></div>
77
78    <p>
79        A type in Numbat can be one of three things. It can be <code class="numbat-value">1</code> &mdash; which is a special type for dimensionless quantities, it can be a base dimension, or it can be an algebraic combination of other types.
80        We use the <code class="numbat-keyword">dimension</code> keyword to introduce new types. For example, this
81        is how basic physical dimensions from classical mechanics are defined in Numbat's <a href="https://github.com/sharkdp/numbat/tree/master/numbat/modules">prelude</a>:
82    </p>
83
84    <div id="editor4" class="code-editor">dimension Length
85dimension Area = Length²
86
87dimension Time
88dimension Frequency = 1 / Time
89dimension Velocity = Length / Time
90dimension Acceleration = Length / Time²
91
92dimension Mass
93dimension Force = Mass × Acceleration
94dimension Pressure = Force / Area
95dimension Energy = Force × Length
96dimension Power = Energy / Time</div>
97
98    <p>
99        Note how the three base dimensions <em>length</em>, <em>time</em> and <em>mass</em> can be combined using multiplication, division and exponentiation. Now there is not a lot we can do with those types until we
100        introduce corresponding <em>units</em> to build quantities that inhabit those types:
101    </p>
102
103    <div id="editor5" class="code-editor">unit metre: Length
104unit second: Time
105unit kilogram: Mass  # in the real prelude, we properly handle prefixes
106
107unit hertz: Frequency = 1 / second
108unit newton: Force = kilogram metre / second²
109unit pascal: Pressure = newton / metre²
110unit joule: Energy = newton metre
111unit watt: Power = joule / second
112
1132 * newton + 1 * watt / (metre / second)</div>
114    <pre id="output4and5" class="numbat-output"></pre>
115
116    <p style="margin-bottom: 0">
117    Now take a look at the last line. When the type checker encounters an expression like this, it infers
118    the overall type (<code class="numbat-type-identifier">Force</code>) by recursively walking the
119    syntax tree. Multiplication and division nodes are easy. We simply combine the types
120    in the same way that we combine the expressions:
121    </p>
122
123    <pre class="type-expr"><span class="numbat-keyword">type</span>(a * b) = <span class="numbat-keyword">type</span>(a) * <span class="numbat-keyword">type</span>(b)
124<span class="numbat-keyword">type</span>(a / b) = <span class="numbat-keyword">type</span>(a) / <span class="numbat-keyword">type</span>(b)</pre>
125
126    <p style="margin-top: 0; margin-bottom: 0">
127    However, addition and subtraction are different. If the types
128    on both hand sides are the same, we return that type. If they are not, we raise a type check
129    error:
130    </p>
131
132    <pre class="type-expr"><span class="numbat-keyword">type</span>(a + b) =
133  <b>if</b> <span class="numbat-keyword">type</span>(a) == <span class="numbat-keyword">type</span>(b) {
134    <span class="numbat-keyword">type</span>(a)
135  } <b>else</b> {
136    error(<span class="numbat-string">"incompatible dimensions in addition …"</span>)
137  }</pre>
138
139    <p style="margin-top: 0">
140    Comparison operators like <code>==</code> or <code>&gt;</code> also work in a
141    similar way &mdash; can't compare apples and oranges &mdash; except that they return a boolean type. You can try this by replacing addition with a comparison operator in the
142    example above.</p>
143
144
145    <p style="margin-bottom: 0">
146    Finally, there is exponentiation: <code>a^b</code>. And it turns out to be quite a bit more complicated.
147    We first note that the exponent <code>b</code> needs to be dimensionless. An expression like <code>(<span class="numbat-value">2</span> <span class="numbat-unit">m</span>)^(<span class="numbat-value">3</span> <span class="numbat-unit">kg</span>)</code> is not
148    meaningful. But even then there is a problem. Imagine something like <code>(<span class="numbat-value">2</span> <span class="numbat-unit">m</span>)^(<span class="numbat-value">1</span> + <span class="numbat-value">2</span>)</code>. It should have a type of <code><span class="numbat-type-identifier">Length</span>^<span class="numbat-value">3</span></code>. But this means that the <em>type</em> of the expression depends on the <em>value</em> of the exponent. It turns out we need to <em>evaluate</em> the expression
149    <code>b</code> <em>at compile time</em> to determine the type of <code>a^b</code>:
150    </p>
151
152    <pre class="type-expr"><span class="numbat-keyword">type</span>(a ^ b) =
153  <b>if</b> <span class="numbat-keyword">type</span>(b) != <span class="numbat-value">1</span> {
154    error(<span class="numbat-string">"exponent needs to be dimensionless"</span>)
155  } <b>else</b> {
156      <b>if</b> <span class="numbat-keyword">type</span>(a) == <span class="numbat-value">1</span> {
157        <span class="numbat-value">1</span>
158      } <b>else</b> {
159        <span class="numbat-keyword">type</span>(a) ^ <span class="numbat-keyword">consteval</span>(b)
160      }
161  }</pre>
162
163    <p style="margin-top: 0">
164    Numbat therefore has a special const-evaluation mode that can compute a subset of expressions as part of the type-checking phase.
165    Note that the restriction to a subset of operations is not a limitation in practice. Real world computations often have complicated expressions in the exponent.
166    But in those cases, the left-hand side (<code>a</code>) is always dimensionless and the overall type is simply <code class="numbat-value">1</code>. And when <code>a</code> is not dimensionless, the exponent expression is typically just a (rational) number.<br>
167    One interesting application of the exponentiation operator is the <code>sqrt</code> function that you
168    saw in the very first example. It can take dimensionful quantities as an argument. And it can be defined in this way:
169    </p>
170
171    <div id="editor6" class="code-editor">fn my_sqrt&lt;D&gt(x: D^2) -&gt; D = x^(1/2)
172
173my_sqrt(ℏ G / c^5)  # Planck time</div>
174    <pre id="output6" class="numbat-output"></pre>
175
176    <p>
177    Here, <code class="numbat-type-identifier">D</code> is a generic type parameter. The function takes an argument of type
178    <code><span class="numbat-type-identifier">D</span>^<span class="numbat-value">2</span></code> and returns a <code class="numbat-type-identifier">D</code>. In the example here, it turns
179    <code><span class="numbat-type-identifier">Time</span>^<span class="numbat-value">2</span></code> into <code class="numbat-type-identifier">Time</code>.
180    In general, type inference for functions is <a href="https://github.com/sharkdp/numbat/issues/29">an interesting topic</a> for another day.
181    </p>
182
183    <p>
184    Our final example demonstrates how you can make use of custom dimensions and units. This
185    is often useful when you want to count things (people, atoms, pixels, or in this case: drops).
186    Say we want to compute the required IV drip rate for an infusion of 1200&nbsp;mL of saline solution
187    over 6&nbsp;hours. Even if it might look like overkill in this simple example, note how the
188    introduction of a new unit not just helps with correctness, but also with readability:
189    </p>
190
191    <div id="editor7" class="code-editor">unit drops  # Implicitly creates a new base dimension 'Drops'
192
193dimension DripRate = Drops / Time
194
195let saline_volume = 1200 mL
196let drop_factor = 15 drops / mL
197let total_time = 6 hours
198
199let iv_drip_rate = saline_volume * drop_factor / total_time
200
201iv_drip_rate -> drops / min</div>
202    <pre id="output7" class="numbat-output"></pre>
203
204    <div class="spacer"></div>
205
206</article>
207
208
209    <p>
210        If you want to learn more about Numbat, consider reading the language <a href="https://numbat.dev/doc/tutorial.html">tutorial</a>.
211        Numbat is <a href="https://github.com/sharkdp/numbat">open source</a>. It is available both <a href="http://numbat.dev">on the web</a> (running locally in your browser) and as a <a href="https://github.com/sharkdp/numbat">command-line application</a>.
212    </p>
213
214    <script type="module" src="index.js"></script>
215</body>
216</html>