145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# 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/) |