squish/docs/source/usage.rst

Usage

If all you need is to run the simulation, then you need not write at code. You can simply use the command line tool provided tool for you, squish! Of course, it's also possible to use the library to do whatever you may need.

Note

Squish will automatically create a figures and simulations folder in the directory you run it from.

Squish Utility

The command line utility squish outputs simulation results given the input parameters. There are many input parameters, so it's necessary to create a config .json file.

Configuration

Domain

The 'domain' section defines the basic setup. The n_objects parameter represents the number of objects in the domain of width by height. The natural_radius parameter is the radius of the circle that represents the natural 'zero energy' state of the object. Lastly, the energy parameter is just the type of energy to simulate with. There are currently three: "area", "radial-al", "radial-t".

Note

You can also set the above parameters with a command line argument.

Optionally, its also possible to set the initial sites/points with an array or the file path to a NumPy binary (.npy) file.

{
  "domain": {
    "n_objects": 15,
    "width": 10.0,
    "height": 10.0,
    "natural_radius": 4.0,
    "energy": "radial-t",
    "points": [
      [1,1], [2,2], [3,3], [4,4], [5,5],
      [1,2], [2,3], [3,4], [4,5], [5,6],
      [1,3], [2,4], [3,5], [3,6], [5,7]
    ]
  },
  ...
}

Simulation

There are currently three simulation modes, and the configuration changes slightly for each one.

Flow

This mode simulates the relaxing of the objects to its equilibrium. The threshold is the sufficient condition where the gradient is sufficiently close to zero. Specifically, the simulation stops when the L1 norm of the gradient divided by the number of objects is less than the threshold. The step-size parameter only represents the initial step size. If adaptive is set to true, then adaptive step size is used to make convergence faster.

{
  ...
  "simulation": {
    "mode": "flow",
    "step_size": 0.05,
    "threshold": 0.0001,
    "adaptive": true
  },
  ...
}

Search

This mode searches for equilibrium until eq_stop_count equilibria are found. Additionally, the nullity of the Hessian at the equilibrium may be greater than 2. (2 is guaranteed by periodicity, as any translation is another equilibrium.) In this case, the manifold_step_size parameter is used to traverse along it.

{
  ...
  "simulation": {
    "mode": "search",
    "step_size": 0.05,
    "threshold": 0.0001,
    "adaptive": true,
    "eq_stop_count": 100,
    "manifold_step_size": 0.1
  },
  ...
}

Shrink

This mode simulates the the change in the equilibrium as the width is decreased. Both the width_change and width_stop parameters should be set as a percentage of the width.

{
  ...
  "simulation": {
    "mode": "shrink",
    "step_size": 0.05,
    "threshold": 0.0001,
    "adaptive": true,
    "width_change": 1,
    "width_stop": 0.3
  },
  ...
}

Additionally, the save_sim parameter determines whether or not the .sim file is generated. Additionally, you can provide a name that will be used to for the output files.

Note

This is optional! A filename is automatically generated by default.

{
  ...
  "simulation": {
    ...
    "save_sim": true
    "name": "my_awesome_simulation",
    ...
  }
  ...
}

Diagram

It's also possible to visualize the data, but this section is optional. It's possible to output the frames as individual images ("img"), or as a video ("mp4").

Note

Rendering as an mp4 requires ffmpeg to be installed on your system.

While it's possible to customize the figures that are drawn and outputted, there are already a few preset modes: animate, energy, stats, and eigs, which outputs the simulation steps as a video, a video with the graph of energy, compiled statistics, and the eigenvalues, respectively. Lastly, you can optionally specify a time for the video, which is default 30 seconds.

{
  ...
  "diagram": {
    "filetype": "mp4",
    "figures": "animate",
    "time": 30
  }
}

Running

Here's a sample file you can feel free to download or copy and paste:

assets/test_sim.json

With the config to run and saved, you can run

(.venv): squish my_test_sim.json