Jam/README.md

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
```bash
  ./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