Comments, questions, feature requests, and bug reports should be sent to bryan.head@gmail.com.

More information about sandpiles work can be found here.

$ LD_LIBRARY_PATH = .:$LD_LIBRARY_PATH

$ export LD_LIBRARY_PATH

With "add vertex" selected, click on the canvas and gray block will appear. If it doesn't, make sure you are just clicking and not dragging the mouse at all. This is a vertex of a graph on which you will be running your sandpile simulation.

To get a closer look, you can zoom in using either the mouse wheel or the zoom controls at the top toolbar. Clicking and dragging moves around the canvas.

Create four more vertices in a kite shape so that you end with something that looks like:

If you make a mistake, ctrl-z/ctrl-y (or cmd-z/cmd-y on a Mac) will undo/redo. This can also be accessed in the "Edit" menu. If you want to start over, press "Del. Graph".

Now, this graph won't do a lot in its current state since none of the vertices are connected. So we need to create some edges. First, select "Add Edge" on the side panel. Next, hold down shift, click on the vertex at the top, then let go of shift. This selects the vertex.

Alternatively, you can click on "Select" at the top right and then click on the vertex, but you will have to click on "Edit" afterwards to create the edges. Holding down shift is equivalent to being in "Select" mode.

This should look like:

Now, with "Add Edge" selected, click on the rightmost and leftmost vertices. You will see white lines appear between your selected vertex and those two vertices. These are the edges. In fact, these edges are directed and weighted, but you can't currently see what direction they are pointing or their weight is. To remedy this, go the "Visual Options" tab and check "Draw Edge Labels". Little "1"s should appear next to the white lines, closer to the bottom vertices, like so:

They are off by default because on larger graphs, they can really slow things down.

Notice that the vertex changed size when you created the edges. The size of the vertex is dependent on the amount of sand on it divided by its outgoing degree. This vertex now has degree 2 and 0 grains of sand on it, so it is quite small. You can turn this feature off in the "Visual Options" tab.

Also, notice the bottom toolbar:

It contains some useful pieces of information.

- "Center" shows the current coordinates of the center of the canvas.
- The grayed out "None: Cancel" allows you to cancel operations that may take a long time.
- "Sel. Center" shows the coordinates of the center of the selected vertices (vertex in this case). Clicking on it will center the canvas at that point.
- Sand is total amount of sand on the selected vertices.
- Degree is total outgoing degree of the selected vertices.
- Firings is total number of times the selected vertices have fired (you can reset this counter using "Reset Firings Count").

Hold down shift again and click on one of the selected vertices. Clicking on a vertex with shift down both selects and unselects vertices. Switch to "Add Undirected Edge" in the side panel. Click on the vertex you just unselected (without holding down shift). An edge appears with "1"s on either side, indicating that the weight of the edge is 1 in both directions.

Finally, unselect the vertex and select the second lowest one. Create a directed edge from it to the topmost vertex and another one to the bottom most vertex. The result should look like:

Go to the "Config Manager" tab. It looks like this:

A configuration is a distribution of sand on the vertices of a graph. The list in the config manager contains all stored configurations. At first, it contains only a set of calculated configurations, but if you've found a configuration you would like to keep track of, you can click "Store" to add it to the list.

"Add" and "Subtract" will, respectively, add and substract the selected configuration from the current configuration. "Set" will set the current configuration to the selected one. The "Times" counter will multiply the selected configuration by the number for whatever operation you've chosen. So, to add 1000 grains of sand to the configuration, you would select "Random Grain", set "Times" to 1000, and press "Add".

To add, remove, or set sand for specific vertices, you select the operation you want under "On click:" and click on the vertex. Go ahead and try it. Notice that the colors change in correspondence to the number of grains you add. By default, the number of grains is not written on the vertices. You can change this in the visual options. You can also see the number of grains by selecting the vertex. You can change the colors in Edit->Preferences. The preferences dialogue is very much a work in progress at this point, though color changing is fully functional and it will remember your preferences between sessions.

Try adding an amount of sand equal to or greater than the degree of a vertex (for any but the bottom vertex). Press "Run". The colors change as the vertices fire. After a couple of steps, the sandpile will stabilize and stop moving. To change the speed at which the simulation runs, change the "Delay" field above (either by using the buttons or directly editing).

If you wish to save your work on a graph, you can use Ctrl-s (or Cmd-s for Mac). Saved Sandpile projects are just folders that contain a graph file (.sg) and any configurations that were stored.

NOTE: Currently, very large graphs can take up a lot of memory, and may cause Java to run out. Anything less than 100,000 vertices should perform decently. 400,00 will still run, but editing the graph may result in problems. Larger graphs should be possible in the near future.

Also, to speed up the drawing of large graphs, it is highly recommended you turn off "Draw Edges" in visual options.

The border options include:

- Directed - Sink vertices will be created along the border. This is usually considered the standard sandpile graph.
- Undirected - Vertices will be created along the border, but they will be connected by undirected edges, making them reflectors.
- None - No special border edges or vertices will be generated. The vertices along the side will have degree 3 instead of 4.
- Loop to opposite - Directed edges will be created from the side to its opposite, so that vertices directly across from each other are connected.
- Loop to opposite reverse - Same as above, but, if the side is n vertices long, vertex i will connect to vertex n-i.

- Ring - Set N and S to "loop to opposite". E and W can be directed, undirected, or none.
- Möbius strip - Set N and S to "loop to opposite reverse". E and W can be directed, undirected, or none.
- Torus - Set everything to "loop to opposite".
- Klein Bottle - Set N and S to "loop to opposite reverse", and E and W to "loop to opposite".
- Projective Space - Set everything to "loop to opposite reverse".

I've expanded it slightly so you can read each column header in full. The basic idea is that you provide a list of integer vectors with certain parameters. The lattice builder will create a lattice of vertices, putting an edge between any two vertices that differ in position by one of the vectors. The different parameters are as follows (note that the bottom left of the lattice is considered (0,0)):

- x - The x value of the vector.
- y - The y value of the vector.
- x start - No vertex with an x-coordinate (relative to the lattice) lower than this will be affected by this vector.
- x freq - How frequently after x start to apply this vector. For instance, x start=0 and x freq=2 would apply the vector to all vertices with even x-coordinates. If the x freq is zero, the vector will be apply only to vertices with x coordinate equal to x start.
- y start and y freq - Same as x start and x freq, but with respect to the coordinate.
- Dir - Whether or not the resulting edges will be directed. If checked, the edges will point in the direction of the vector.
- Weight - The weight of the resulting edges.

- Number of Grains - Color depends on the amount of sand.
- Stability - Color depends on whether or not the vertex is stable.
- Total firings - Color depends on how many times the vertex has fired. To reset the counters, click on "Reset Firings Count".
- Difference from Base - Color depends on the amount of sand relative to another configuration. To set the base configuration to the current configuration, click on "Set Base Config".

Last modified: Mon Aug 17 15:01:56 PDT 2009