Visualization software for hard-core particle models and tilings
Go to file
2023-05-10 15:20:48 -04:00
src Add License 2023-05-10 15:08:58 -04:00
TeX Add License 2023-05-10 15:08:58 -04:00
LICENSE Add License 2023-05-10 15:08:58 -04:00 Dependencies in README 2023-05-10 15:20:48 -04:00

Jam is visualization software for hard-core lattice particle systems. It is designed to explore configurations of particles while enforcing that no two particles overlap.

Jam is a work in progress and is nowhere near ready for production.

Basic usage

Run with

  ./src/jam [configuration_file]

where [configuration_file] is an optional argument that specifies a file with a list of particle positions that will be loaded on initial execution.


Jam is written in Python 3, and uses Kivy to run the GUI.

User interface

  • <right-click>: create a new particle under the mouse pointer (if the particle fits)

  • <shift><left-click>: select/unselect multiple particles

  • <left-click> and drag: move selected particle(s).

  • backspace: delete selected particle(s)


Commands can be executed by typing : (similarly to vim).

  • :q: exit

  • :w [path_to_file]: Write particle configuration to file. This will not overwrite existing files; use :w! to overwrite.

  • :e <path_to_file>: edit file.

  • :export <path_to_file>: Export configuration to LaTeX (using TikZ)

  • :set color <color_spec>: Set color of selected particles to <color_spec>. The supported format for <color_spec> is either r,g,b with r, g, and b in [0,1], or one of red|green|blue|brown|lime|orange|pink|purple|teal|violet|cyan|magenta|yellow|olive|black|darkgray|gray|lightgray|white.

  • :set zoom <zoom_level>: Scale all particles by <zoom_level>.

  • :set grid [on|off]: Add a visual grid centered on one of the selected particles. The size of the mesh can be specified by passing :set grid <size_of_mesh>.

Current developments

So far, Jam only supports cross-shaped particles, but work is in progress to support arbitrary shapes consisting of rectangles, circle arcs and triangles (check out the dev branch to follow the progress).

Support for lattice configurations is also ongoing.


Jam is distributed under the Apache 2.0 License.

Copyright 2021-2023 Ian Jauslin