diff --git a/README.md b/README.md deleted file mode 100644 index 85fde08..0000000 --- a/README.md +++ /dev/null @@ -1,145 +0,0 @@ -# PackSim - -PackSim is Python program which perform simulations for the flow of 'soft' or 'compressible' objects under some energy in a periodic domain. - - -## Installing -Currently, this isn't packaged as a standalone program. Python 3.8+ is needed to use this. - -## Building - -Before running, first install the necessary requirements. A virtual environment is recommended. - -```bash -pip install -r requirements.txt -``` -It is also necessary to build the Cython components. So, simply run: - -```bash -foo@bar:/path/to/packsim: ./build.sh -``` -If video output of the simulation is desired, `ffmpeg` **must** be installed on system. Otherwise, it's all ready to go! - -## Usage - -The primary usage is to run `packsim.py` to output simulation results. There are many parameters, so it's recommended that you use a JSON configuration file. There are two required sections, `calculation` and `simulation`. - -### 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'`. These parameters can also be overridden by a command line argument. - -You can also set the initial sites/points with an array or the file path to a NumPy binary (.npy) file. - -```jsonc -{ - "domain": { - "n_objects": 15, - "width": 10.0, - "height": 10.0, - "natural_radius": 4.0, - "energy": "radial-t", - "points": [ // Optional - [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. - -```jsonc -{ - //... - "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. - -```jsonc -{ - //... - "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. -```jsonc -{ - //... - "simulation": { - "mode": "shrink", - "step_size": 0.05, - "threshold": 0.0001, - "width_change": 1, - "width_stop": 0.3 - }, - //... -} -``` - -Additionally, a filename is automatically generated by default, but it's also possible to provide it with the `name` parameter. The `save_sim` parameter determines whether or not the `.sim` file is saved. This allows simulations to be loaded again at a later time, if other processing is desired. Setting points is also possible, with the `points` parameter. - -```jsonc -{ - //... - "simulation": { - //... - "name": "my_awesome_simulation", // Optional - "save_sim": true - //... - } - //... -} -``` - -### 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. - -```jsonc -{ - //... - "diagram": { - "filetype": "mp4", - "figures": "animate", - } -} -``` - -Now with, all that configuration nonsense out of the way, to run, simply type -```bash -foo@bar:/path/to/packsim: python3 packsim.py my_sim.json -``` -where `my_sim.json` is your configuration file. - -## Contributions - -This project welcomes contributors, so feel free to make a pull request! - -## License -[GNU AGPLv3.0](https://choosealicense.com/licenses/agpl-3.0/) \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e1c72bd --- /dev/null +++ b/README.rst @@ -0,0 +1,31 @@ +Squish: Soft Packing Simulations +================================ + +**Squish** is a Python library that handles simulations for the flow of 'soft' or 'compressible' objects, +under some energy in a *periodic* domain. The gradient flow of the objects are simulated and is able to be saved and rendered into diagrams. **Squish** also provides simple to use scripts for basic usage, as well as a simple API for more advanced functionality. + +Fast parallelized Cython code is used to compute the simulations efficienctly. Also, `NumPy `_ arrays are used, enabling easy integratation with the standard scientific Python ecosystem. + +Resources +--------- + +- `Documentation `_: Examples, guides, and Squish API. +- `GitHub repository `_: View and download the **Squish** source code. +- `Issue tracker `_: Report issues or request features for **Squish**. + + +Installation +------------ +The simplest way to install **Squish** is to use ``pip``: + +.. code-block:: bash + + (.venv) /path/to/squish: pip install squish + +License +------- +This project uses `GNU AGPLv3.0 `_. + +Support and Contribution +------------------------ +Feel free to visit our repository on `GitHub `_ for source code of this library. Any issues or bugs may be reported at the `issue tracker `_. All contributions to **Squish** are welcome! \ No newline at end of file diff --git a/docs/source/_static/ellipses.css b/docs/source/_static/ellipses.css new file mode 100644 index 0000000..4839b92 --- /dev/null +++ b/docs/source/_static/ellipses.css @@ -0,0 +1,4 @@ +.highlight .err { + border: inherit; + box-sizing: inherit; +} \ No newline at end of file diff --git a/docs/source/api.rst b/docs/source/api.rst index ec94338..b8bc495 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -3,5 +3,3 @@ API .. autosummary:: :toctree: generated - - lumache diff --git a/docs/source/assets/test_sim.json b/docs/source/assets/test_sim.json new file mode 100644 index 0000000..c45925f --- /dev/null +++ b/docs/source/assets/test_sim.json @@ -0,0 +1,19 @@ +{ + "domain": { + "n_objects": 15, + "width": 10.0, + "height": 10.0, + "natural_radius": 4.0, + "energy": "radial-t" + }, + "simulation": { + "mode": "flow", + "step_size": 0.05, + "threshold": 0.00001, + "save_sim": true + }, + "diagram": { + "filetype": "mp4", + "figures": "energy" + } +} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 6e9e8c0..f93de20 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,9 +2,9 @@ # -- Project information -project = 'Lumache' -copyright = '2021, Graziella' -author = 'Graziella' +project = 'Squish' +copyright = '2021, ksjdragon' +author = 'ksjdragon' release = '0.1' version = '0.1.0' @@ -29,7 +29,11 @@ templates_path = ['_templates'] # -- Options for HTML output +html_static_path= ['_static'] html_theme = 'sphinx_rtd_theme' +html_css_files = [ + "ellipses.css" +] # -- Options for EPUB output epub_show_urls = 'footnote' diff --git a/docs/source/index.rst b/docs/source/index.rst index 03d09a5..7c6273c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,22 +1,40 @@ -Welcome to Lumache's documentation! -=================================== +Squish: Soft Packing Simulations +================================ -**Lumache** (/lu'make/) is a Python library for cooks and food lovers -that creates recipes mixing random ingredients. -It pulls data from the `Open Food Facts database `_ -and offers a *simple* and *intuitive* API. +**Squish** is a Python library that handles simulations for the flow of 'soft' or 'compressible' objects, +under some energy in a *periodic* domain. The gradient flow of the objects are simulated and is able to be saved and rendered into diagrams. **Squish** also provides simple to use scripts for basic usage, as well as a simple API for more advanced functionality. -Check out the :doc:`usage` section for further information, including -how to :ref:`installation` the project. +Fast parallelized Cython code is used to compute the simulations efficienctly. Also, `NumPy `_ arrays are used, enabling easy integratation with the standard scientific Python ecosystem. -.. note:: +Resources +--------- - This project is under active development. +- `Documentation `_: Examples, guides, and Squish API. +- `GitHub repository `_: View and download the **Squish** source code. +- `Issue tracker `_: Report issues or request features for **Squish**. -Contents --------- + +Installation +------------ +The simplest way to install **Squish** is to use ``pip``: + +.. code-block:: bash + + (.venv) /path/to/squish: pip install squish + +License +------- +This project uses `GNU AGPLv3.0 `_. + +Support and Contribution +------------------------ +Feel free to visit our repository on `GitHub `_ for source code of this library. Any issues or bugs may be reported at the `issue tracker `_. All contributions to **Squish** are welcome! .. toctree:: + :hidden: + :maxdepth: 4 + :caption: Getting Started + installation usage api diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..ff1c563 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,43 @@ +Installation +============ + +Basic Installation +------------------ + +.. important:: + + This library requires Python 3.8+! Also, if you need to export diagrams + as a video, the ``ffmpeg`` library must be installed on your system and in your ``PATH``! + +To use **Squish**, first install it using `pip`: + +.. code-block:: console + + (.venv) $ pip install squish + +The **Squish** library depends on matplotlib, numpy, and scipy, which all will be installed along with it. + +Documentation +------------- + +This documentation for **Squish** is `hosted online `_ at **ReadTheDocs**. However, you may also build the documentation for yourself locally. + + +Building the documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You will need to install ``sphinx`` and ``sphinx_rtd_theme`` packages via ``pip``: + +.. code-block:: bash + + (.venv) /path/to/squish: pip install sphinx sphinx_rtd_theme + +Then, to build, run the go into the documentation source directory and execute ``make``: + +.. code-block:: bash + + (.venv) /path/to/squish: cd docs + (.venv) /path/to/squish/docs: make html + +.. autosummary:: + :toctree: generated diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 924afcf..e970f53 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,34 +1,196 @@ Usage -===== +***** -.. _installation: +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. -Installation ------------- +These scripts are simple simple command line utilities. Currently, the following are available: -To use Lumache, first install it using pip: +- :ref:`Simulate` +- :ref:`Width Diagrams` -.. code-block:: console +.. note:: - (.venv) $ pip install lumache + **Squish** will automatically create a ``figures`` and ``simulations`` folder in the directory you run it from. -Creating recipes ----------------- -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: +.. _Simulate: -.. autofunction:: lumache.get_random_ingredients +Simulate +======== -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. +This script outputs simulation results given the input parameters. There are many input parameters, so it's necessary to create a config ``.json`` file. -.. autoexception:: lumache.InvalidKindError -For example: +Configuration +------------- ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] +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 `_ 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.