|
1 | | -COMING SOON!!! |
| 1 | +**Note:** This repository is a *work in progress*. |
| 2 | +More documentation, examples, tutorials, etc. will be coming as the rest of our responsibilities permit. |
| 3 | +In any case, Stark itself is fully functional and actively used in our own research. |
| 4 | +We appreciate your patience and interest. |
2 | 5 |
|
3 | | -Paper: https://www.animation.rwth-aachen.de/publication/0588/ |
| 6 | +# Stark |
| 7 | +<p align=center> |
| 8 | + <img src="https://github.com/JoseAntFer/stark/blob/jose/release_v01/docs/images/robotic_hand.png" width="400"> |
| 9 | + |
| 10 | + <img src="https://github.com/JoseAntFer/stark/blob/jose/release_v01/docs/images/franka_plastic_cup.jpg" width="400"> |
| 11 | +</p> |
| 12 | + |
| 13 | +Stark is a C++ and Python simulation _platform_ that provides easy access to state-of-the-art methods to robustly solve simulations of rigid and deformable objects in a strongly coupled manner. |
| 14 | +To the best of our knowledge, no other existing open source simulation environment provides such a rich collection of models, including coupling, with the same level of robustness. |
| 15 | +Stark has been validated through real-world, challenging cases of interactions between robots and deformable objects, see the [Stark ICRA'24 paper](https://www.animation.rwth-aachen.de/publication/0588/). |
| 16 | + |
| 17 | +One of the main features of Stark is that it uses a powerful symbolic differentiation and code generation engine that allows for a concise formulation of the global variational form of the non-linear dynamic problem. |
| 18 | +Adding new models (e.g. materials, joints, interactions, ...) in Stark is as simple as specifying their energy potential in symbolic form together with the data they depend on. |
| 19 | +This removes the tedium of manually deriving, implementing, testing and optimizing new models and integrating them in existing complex simulation environments. |
| 20 | +Stark collects all the potentials and uses Newton's Method to find the solution to the non-linear implicit time-stepping problem. |
| 21 | +Presently, even though Stark has a C++ and Python API, models can only be defined in C++. |
| 22 | + |
| 23 | +By default, Stark comes out-of-the-box with important widely used models: |
| 24 | +- 3D and 2D **FEM** discretizations for deformable non-linear materials |
| 25 | +- **Discrete Shells** for cloths and stiff shells |
| 26 | +- **Rigid Bodies** with joints and motors |
| 27 | +- Frictional Contact with **IPC** |
| 28 | + |
| 29 | +See [Features](#features) section for more details. |
| 30 | + |
| 31 | +There are two use cases for Stark: |
| 32 | + - As an external, black-box, powerful simulator that can handle very challenging scenarios. |
| 33 | + No knowledge of Stark internals are needed in this case, and users can directly use the high-level C++ or Python APIs. |
| 34 | + - As a research and development tool for simulation. |
| 35 | + Thanks mainly to the symbolic differentiation and integrated collision detection, Stark can dramatically increase productivity of simulation technology research. |
| 36 | + See [here](stark/src/models) how the models contained in Stark are implemented. |
| 37 | + |
| 38 | + |
| 39 | +## Hello World |
| 40 | +The following is a script example using Stark's Python API to execute a simulation of a piece of cloth falling on a rigid box with a prescribed spinning motion. |
| 41 | + |
| 42 | +<p align=center> |
| 43 | + <img src="https://github.com/JoseAntFer/stark/blob/jose/release_v01/docs/images/spinning_box_cloth.gif?raw=true"> |
| 44 | +</p> |
| 45 | + |
| 46 | +```python |
| 47 | +import numpy as np |
| 48 | +import pystark |
| 49 | + |
| 50 | +settings = pystark.Settings() |
| 51 | +settings.output.simulation_name = "spinning_box_cloth" |
| 52 | +settings.output.output_directory = "output_folder" |
| 53 | +settings.output.codegen_directory = "codegen_folder" |
| 54 | +simulation = pystark.Simulation(settings) |
| 55 | + |
| 56 | +# Global frictional contact IPC parameters |
| 57 | +contact_params = pystark.EnergyFrictionalContact.GlobalParams() |
| 58 | +contact_params.default_contact_thickness = 0.001 # Can be overriden by per-object thickness |
| 59 | +contact_params.friction_stick_slide_threshold = 0.01 |
| 60 | +simulation.interactions().contact().set_global_params(contact_params) |
| 61 | + |
| 62 | +# Add deformable surface |
| 63 | +cV, cT, cH = simulation.presets().deformables().add_surface_grid("cloth", |
| 64 | + size=np.array([0.4, 0.4]), |
| 65 | + subdivisions=np.array([20, 20]), |
| 66 | + params=pystark.Surface.Params.Cotton_Fabric() |
| 67 | +) |
| 68 | + |
| 69 | +# Add rigid body box |
| 70 | +bV, bT, bH = simulation.presets().rigidbodies().add_box("box", mass=1.0, size=0.08) |
| 71 | +bH.rigidbody.add_translation(np.array([0.0, 0.0, -0.08])) |
| 72 | +fix_handler = simulation.rigidbodies().add_constraint_fix(bH.rigidbody) |
| 73 | + |
| 74 | +# Set friction pair |
| 75 | +cH.contact.set_friction(bH.contact, 1.0) |
| 76 | + |
| 77 | +# Script |
| 78 | +duration = 10.0 |
| 79 | +def script(t): |
| 80 | + fix_handler.set_transformation( |
| 81 | + translation=np.array([0.0, 0.0, -0.08 - 0.1*np.sin(t)]), |
| 82 | + angle_deg=100.0*t, |
| 83 | + axis=np.array([0.0, 0.0, 1.0])) |
| 84 | +simulation.add_time_event(0, duration, script) |
| 85 | + |
| 86 | +# Run |
| 87 | +simulation.run(duration) |
| 88 | +``` |
| 89 | + |
| 90 | +The output is a sequence of VTK files per output group (in this case one sequence for the cloth and another for the box). |
| 91 | +VTK files can be viewed in Blender with [this](https://github.com/InteractiveComputerGraphics/blender-sequence-loader) add-on or in [Paraview](https://www.paraview.org/). |
| 92 | +You can use [meshio](https://github.com/nschloe/meshio) to transform VTK meshes to other formats. |
| 93 | + |
| 94 | +Stark code will always follow the same structure: |
| 95 | + - Define global settings and parameters. |
| 96 | + - Add objects, boundary conditions and define interactions. In this example, `presets` are used but custom objects and composed materials are also possible. |
| 97 | + - Optionally, specify time-dependent events (script). |
| 98 | + - Run. |
| 99 | + |
| 100 | +See the folder [`stark/pystark/examples`](pystark/examples) for more scenes using the Python API and [`stark/examples`](examples/) for scenes written in C++. |
| 101 | + |
| 102 | + |
| 103 | +## Get Stark |
| 104 | +Stark's C++ and Python APIs are essentially equivalent. |
| 105 | +A user who just wants to _use_ Stark with the models that it comes with, probably will prefer the Python API. |
| 106 | +Users looking to work on their own new models to _extend_ Stark with new functionality will have to work directly in the C++ source code. |
| 107 | + |
| 108 | +Every time Stark encounters a new potential energy, it will generate and compile code to compute its derivatives. |
| 109 | +Therefore, a C++17 compiler is required. |
| 110 | +You can specify the command to invoke a compatible compiler using `pystark.set_compiler_command(str)` in Python and `stark::set_compiler_command(str)` in C++. |
| 111 | +By default, it is `"g++"` in Unix and `"C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Auxiliary/Build/vcvarsx86_amd64.bat"` in Windows. |
| 112 | + |
| 113 | +If you don't have a C++17 compiler and just want to use the models shipped with Stark by default, you can download the corresponding compiled binaries [here](https://rwth-aachen.sciebo.de/s/5NXgsPtoDyVl8Yo). |
| 114 | +Don't forget to point Stark to the folder containing those in `settings.output.codegen_directory`. |
| 115 | + |
| 116 | +### Python API |
| 117 | +You can install Stark for Python 3.8+ using |
| 118 | +``` |
| 119 | +pip install stark-sim |
| 120 | +``` |
| 121 | + |
| 122 | +### Build from source |
| 123 | +To build from source you will need [CMake](https://cmake.org/) and a C++17 compiler. |
| 124 | +All dependencies are bundled with Stark or are downloaded by CMake at build time. |
| 125 | + |
| 126 | +## Examples with code |
| 127 | +<div align="center"> |
| 128 | +<table> |
| 129 | + <tr> |
| 130 | + <td align="center"> |
| 131 | + <img src="docs/images/twisting_cloth.gif" alt="Alt text for gif1" style="width:100%; max-width: 300px;" /> |
| 132 | + <br> |
| 133 | + <a href="pystark/examples/twisting_cloth.py">twisting_cloth.py</a> |
| 134 | + </td> |
| 135 | + <td align="center"> |
| 136 | + <img src="docs/images/boxes_on_cloth.gif" alt="Alt text for gif1" style="width:100%; max-width: 300px;" /> |
| 137 | + <br> |
| 138 | + <a href="pystark/examples/boxes_on_cloth.py">boxes_on_cloth.py</a> |
| 139 | + </td> |
| 140 | + </tr> |
| 141 | + <tr> |
| 142 | + <td align="center"> |
| 143 | + <img src="docs/images/inflation.gif" alt="Alt text for gif1" style="width:100%; max-width: 300px;" /> |
| 144 | + <br> |
| 145 | + <a href="pystark/examples/inflation.py">inflation.py</a> |
| 146 | + </td> |
| 147 | + <td align="center"> |
| 148 | + <img src="docs/images/viscoelasticity.gif" alt="Alt text for gif1" style="width:100%; max-width: 300px;" /> |
| 149 | + <br> |
| 150 | + <a href="pystark/examples/viscoelasticity.py">viscoelasticity.py</a> |
| 151 | + </td> |
| 152 | + </tr> |
| 153 | + <!-- Continue adding rows here --> |
| 154 | +</table> |
| 155 | +</div> |
| 156 | + |
| 157 | + |
| 158 | +## Features |
| 159 | + |
| 160 | +### Models |
| 161 | +Besides a simulator, Stark is a repository of potential energies commonly used for deformable and rigid objects and frictional contact. |
| 162 | +The following models can be found in symbolic form in `stark/stark/src/models/`: |
| 163 | + |
| 164 | +* Deformable objects |
| 165 | + - 2D and 3D linear FEM (triangles and tets) with the Neo-Hookean and Stable Neo-Hookean constitutive models, respectively ([paper](https://dl.acm.org/doi/10.1145/3180491)) |
| 166 | + - Discrete Shells ([paper](https://dl.acm.org/doi/10.5555/846276.846284)) |
| 167 | + - Strain limiting ([paper](https://dl.acm.org/doi/10.1145/3450626.3459767)) |
| 168 | + - Inertial and material damping |
| 169 | +* Rigid bodies |
| 170 | + - Soft joints (linear) |
| 171 | + - Smooth force/torque capped motors [(paper)](https://www.animation.rwth-aachen.de/publication/0588/) |
| 172 | + - Comprehensive collection of constraints (ball joints, hinge joints, sliders, ...) |
| 173 | +* Frictional contact (based on triangle meshes) |
| 174 | + - IPC [(paper)](https://dl.acm.org/doi/abs/10.1145/3386569.3392425) |
| 175 | +* Attachments (based on triangle mesh distances) |
| 176 | + |
| 177 | +### Solver |
| 178 | +* Symbolic differentiation |
| 179 | + - Automatic generation of gradients and Hessians |
| 180 | + - Parallel autonomous global evaluation and assembly |
| 181 | +* Triangle-based collision detection |
| 182 | +* Solver |
| 183 | + - Newton's Method |
| 184 | + - Intersection free line search (CCD coming soon) |
| 185 | + - Conjugate Gradient or Direct LU linear solver |
| 186 | + - Optional adaptive time step size |
| 187 | + - Optional numerical PSD projection of element Hessians |
| 188 | +* Event-based scripts |
| 189 | + |
| 190 | +## Research using Stark |
| 191 | +[Micropolar Elasticity in Physically-Based Animation](https://www.animation.rwth-aachen.de/publication/0582/) - Löschner et al. |
| 192 | + |
| 193 | +## Cite Stark |
| 194 | +```bibtex |
| 195 | +@INPROCEEDINGS{FLL+24, |
| 196 | + author={Fernández-Fernández, José Antonio and Lange, Ralph and Laible, Stefan and Arras, Kai O. and Bender, Jan}, |
| 197 | + booktitle={2024 IEEE International Conference on Robotics and Automation (ICRA)}, |
| 198 | + title={STARK: A Unified Framework for Strongly Coupled Simulation of Rigid and Deformable Bodies with Frictional Contact}, |
| 199 | + year={2024} |
| 200 | +} |
| 201 | +``` |
| 202 | + |
| 203 | +## Acknowledgments |
| 204 | +Stark was made possible by Bosch Research and the Computer Animation Group at RWTH Aachen University. |
| 205 | + |
| 206 | +List of collaborators to the codebase: |
| 207 | + - [José Antonio Fernández-Fernández](https://github.com/JoseAntFer) |
| 208 | + - [Fabian Löschner](https://github.com/w1th0utnam3) |
0 commit comments