User Guide

Table of Contents

  • More than its parts
  • Mathshell
  • Datasets
  • Distributions
  • Graphs
  • Plots
  • Truth Tables
  • L-Systems

MathBlocks is an environment for playing around with mathematics, create content and share with others.

Learn how to use MathBlocks in this hands-on guide.

More than its parts

On the surface mathblocks is a suite of specialized apps to play with designated objects of a more or less mathematical nature.

Through the use of mathshell scripting, drag'n drop and import/export features, mathblocks tries to unlock powers that are beyond the scope of any single app.


Mathshell is mathblocks very own language and the foundation for much of its functionality. Knowledge of this language makes you capable of achieving a lot more with mathblocks, including making nicely typeset math notation, calculations/algorithms and scripting of the environment.


  • Nicely typeset math-notation output (optional)
  • Complex arithmetic
  • Linear algebra
  • Boolean algebra
  • Bignums and infinite precision rationals
  • Library of mathematical objects
  • Symbolic computations (very experimental)

Complex arithmetic

The i symbol is reserved for the imaginary unit. Making complex arithmetic straightforward.

The real and imaginary parts are parsed as two separate numbers. Use paranthesis when you want to make shure the two parts are tied together.

1 + 2i * 3 (1 + 2i) * 3

Variables and functions

Variables and functions are defined using the := operator (while = signifies that something has been computed).

Define and call a function:

f(x, y) := x - x^y f(2, 3)

Assigments are done right to left. Defining a, b and c to all equal 5:

a := b := c := 5 a

Argument matching (maps)

A function is simply a mapping from one thing to another. And some times we just have a small domain of input values and no obvious formula for how to map them. Defining such functions is simple with argument matching.

f(1) := 3 f(2) := 1 f(3) := 42 f(2)

Argument matching works for numbers and strings, and you can mix them in the same function.

Muliple arguments are allowed. But you must use the same number of arguments for each added mapping. Once you use a different number of arguments you will redefine the function completely.

The last match wins. So if there is a general case, it should be defined first and overridden with special cases.

f(x, y) := "work" f("sun", "sunday") := "beer" f("rain", "sunday") := "tv"

Since functions are so wonderfull, mathshell does not have a separate Map structure like many other languages have.


f(x) := "positive" if x > 0 "negative" if x < 0 "zero" else


Functions in mathshell resemble mathematical functions. That is, they don't have side effects (can't change the state of "the world"), they depend only on their input and always give the same output from the same input. (At least, that's what the documentation says).

This leaves as a lot to be desired for scripting capabilities in an interactive environment. Which is why mathshell also has routines.

catState := ["dead", "alive"] look() { catState := "dead" if random() < 0.5 "alive" else } look()

Distinct notions of pure math functions and effectfull programming routines allows for playing around with pure functions without beeing restrained by them. And the nice properties of pure functions allows for some unique features themselves.

The distinction also examplifies the meta perspective mathshell tries to take on maths in general.

Vectors and matrices

Vectors and matrices are defined by separating row entries with "," and rows with ";", and putting brackets around it.

[1, 2; 3, 4] * [a; b]

Addition, subtraction, multiplication and exponentiation are defined for matrices.


As seen with functions and routines, mathshell tries to facilitate both pure computation and effectfull scripting, while keeping the two somewhat distinct. The same is seen with object methods.

There are two ways of calling methods, depending on wheter you want a new object or change the existing one.

s := "Hamburger"
s.replace("burger", "sandwich")
will give you a new string "Hamsandwich".

s := "Hamburger"
s..replace("burger", "sandwich")
will change the string s to "Hamsandwich"

The mutation operator .. may not be called from within a pure context (i.e. inside a function).

So what's the point of this dirty effectfull capability? The various views of mathematical objects will auto-update to show any changes, making it easy to create dynamic visuals by using the .. operator. In the case of large objects, say a large graph, it is also more computationally efficient to mutate the existing graph than to create a new one.


The double slash operator works like normal division, but displays with a horizontal fraction bar.

12/3 12//3

Underscore denotes a subscript.

t_2 := pi
f_3(x_r) := cos(x_r)


A dataset in mathblocks is a collection of numeric values.


The following distributions are available as built-in objects.

  • Bernoulli
  • Binomial
  • Cauchy
  • Exponential
  • Log-normal
  • Normal
  • Pareto
  • Poisson
  • Uniform continuous
  • Uniform discrete
  • Weibull


The Graph app allows you to visually (and textually) create graph structures and perform computations on them.

The graph is simultaneously presented by a html5 canvas and by a typical declarative definition in a text box. Changes done through the canvas are automatically reflected in the defintion. When you manually edit the definition, a refresh button will be become available to update the canvas and internal graph model.

The default graph type is an undirected, euclidean graph, but digraphs and "custom" weights or unweighted graphs are also supported. The weights must be edited through the text definition unless you set the graph to be euclidean (edge weights corresponding to edge lengths).

To let you create and interact with graphs, the canvas has five different input modes.

  • Select. Select existing vertices and edges by pressing them.

  • Vertex. Add new vertices by pressing the canvas.

  • Edge. Add new edges to the graph by pressing the source vertex, dragging to a destination vertex and releasing.

  • Move. Move vertices and labels around the canvas.

  • Delete. Delete vertices or edges by pressing them. Any edges connected to a deleted vertex will also be removed.

Currently, minimal spanning three, shortest path and eulerian circuit algorithms for are implemented and available through the solve menu. The solution is presented by highlighting the edges with color. A highlighted solution may be cleared from the canvas with the clear effects button.

The import entry in the menu lets you open graph definition, which may be in mathblocks' homegrown format, or in a supported subset of GEXF (Graph Exchange XML Format).

Graph app


Input function definitions (or simpler, just the expressions) in the designated fields and click the draw button to have the function plotted on the canvas.

The functions (or expressions) can be of either one or two arguments (or unknowns). When writing expressions, the variables x and t will be intepreted as a unit on the x-axis and a unit of the running time variable, respectively.

If writing the full function definition you can choose the argument names yourself, but the first argument will always be x-axis and the second will be the running variable.

The "rate of time" can be adjusted in the input field labeled "unit t". The field accepts a number possibly followed by a unit of measurement - currently it supports "s" for seconds and "ms" for milliseconds. Milliseconds is the default if no unit is specified. Mind that this rate of time does not control the animation frame rate, though it might affect it indirectly.

Truth Tables

With the TruthTable app you can quickly generate truth tables for boolean formulas. Adjust the number of variables and formulas you want with the + and - buttons above the table. Type your expressions in the designated formula cells and press enter. Voila! The column of truth values for this formula should be generated. Repeat for as many formulas as you want.

The app also lets you export the table as html code or a png image. There will be no css styling in the exported html code.


L-systems are in essence a way to create something complex from something simple using replacement rules.

In practice, we use strings to represent the something and our rules are rules for rewriting the strings.

rule 1 : replace A with B A A
rule 2 : replace B with A B.

So lets say we take the string "A B" as our starting point - the axiom. Iteratively applying the two rules above we get

A B axiom
B A A A B rules applied once
A B B A A B A A B A A A B rules applied twice
B A A A B A B B A A B A A A B B A A B A A A B B A A B A A B A A A B rules applied three times

As you may imagine, with more iterations and more complicated rules, the result quickly seems complex. But let's not forget that the simplicity is still in there. Our rules and axiom unambiguasly defined this whole structure for the given number of iterations.

Ok. So long string of symbols may only be entertaining for so long. But as mentioned earlier, the symbols may be seen as representations of something else. In fact, l-systems where originally devised to study the development of simple multicellular organisms.

So we map symbols to cells and suddenly our string represents an organism and the iterations simulates its growth.

Unfortunately mathblocks is not yet able to provide you with actual organisms. But it can map the symbols to other stuff. In particular, the LSystem app is set up to interpret symbols as drawing actions on a canvas.

LSystems in mathshell

"Replacement rules" are of course nothing but a function from String to String, and straightforward to define in mathshell using argument matching. Define the example l-system in mathshell and expand to the third generation:

axiom := "A B" rules("A") := "B A A" rules("B") := "A B" lsys := LSystem(axiom, rules) lsys.expand(3)

Strange Attractors

Peter De Jong strange attractor.
Peter de Jong attractor from seed 3200075647
Quadratic strange attractor.
Quadratic attractor from seed 1267531276
Trigonometric strange attractor.
Trigonometric attractor from seed 4197194269