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] [-L lattice]

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

• [-L lattice] is an optional argument that specifies a background grid that constrains the position of the particles. So far, the lattice argument must be square for the square lattice, or, to specify the unit length of the lattice: square:<unit_length>.

Dependencies

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

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 supports particles made of combinations of rectangles, but there is no infrastructure to set the shape of the particle at runtime.

License

Jam is distributed under the Apache 2.0 License.

Copyright 2021-2023 Ian Jauslin