197 lines
5.0 KiB
ReStructuredText
197 lines
5.0 KiB
ReStructuredText
Usage
|
|
*****
|
|
|
|
If using the library is all that is needed, then a few scripts are provided to easily access the main functionalities, without needing to write code at all! Otherwise, there are further examples here.
|
|
|
|
These scripts are simple simple command line utilities. Currently, the following are available:
|
|
|
|
- :ref:`Simulate`
|
|
- :ref:`Width Diagrams`
|
|
|
|
.. note::
|
|
|
|
**Squish** will automatically create a ``figures`` and ``simulations`` folder in the directory you run it from.
|
|
|
|
|
|
.. _Simulate:
|
|
|
|
Simulate
|
|
========
|
|
|
|
This script 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.
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
"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. This is because adaptive step size is employed.
|
|
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
...
|
|
"simulation": {
|
|
"mode": "flow",
|
|
"step_size": 0.05,
|
|
"threshold": 0.0001
|
|
},
|
|
...
|
|
}
|
|
|
|
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.
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
...
|
|
"simulation": {
|
|
"mode": "search",
|
|
"step_size": 0.05,
|
|
"threshold": 0.0001,
|
|
"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.
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
...
|
|
"simulation": {
|
|
"mode": "shrink",
|
|
"step_size": 0.05,
|
|
"threshold": 0.0001,
|
|
"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.
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
...
|
|
"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.
|
|
|
|
.. code-block:: json
|
|
:force:
|
|
|
|
{
|
|
...
|
|
"diagram": {
|
|
"filetype": "mp4",
|
|
"figures": "animate",
|
|
}
|
|
}
|
|
|
|
|
|
Running
|
|
-------
|
|
|
|
|
|
Here's a sample file you can feel free to `download <https://github.com/ksjdragon/squish>`_ or copy and paste:
|
|
|
|
.. literalinclude:: assets/test_sim.json
|
|
:language: JSON
|
|
|
|
|
|
With the config to run and saved, you can run
|
|
|
|
.. code-block:: bash
|
|
|
|
(.venv) /path/to/squish: simulate my_test_sim.json
|
|
|
|
|
|
.. _Width Diagrams:
|
|
|
|
Width Diagrams
|
|
==============
|
|
|
|
This script compiles the simulation results into their relevant diagrams. Specifically, given *Search* simulation files at desired widths, it will compile the data and output the diagrams.
|
|
|
|
To run it, you need only provide the folder of *Search* simulations:
|
|
|
|
.. code-block:: bash
|
|
|
|
(.venv) /path/to/squish: width_diagrams /path/to/my/searches
|
|
|
|
Then, it will process and generate diagrams in the `figures` folder.
|
|
|