stark-sim 0.0.2

Stark is a C++ and Python simulation _platform_ that provides easy access to state-of-the-art methods to robustly solve challenging simulations of rigid and/or deformable objects in a strongly coupled manner.

Note: This repository is a work in progress. More documentation, examples, tutorials, etc. will be coming as the rest of our responsibilities permit. In any case, Stark itself is fully functional and actively used in our own research. We appreciate your patience and interest.

Stark

  

Stark is a C++ and Python simulation platform that provides easy access to state-of-the-art methods to robustly solve challenging simulations of rigid and/or deformable objects in a strongly coupled manner. Stark 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. Adding new models (e.g. materials, joints, interactions, ...) in Stark is as simple as specifying their energy potential in symbolic form together with the entities they depend on. Stark collects all the potentials, both built-in and user-specified, and uses Newton's Method to find the solution to the non-linear implicit time-stepping problem. We call Stark a platform because it is designed from the ground up to be easily extended with new models by providing a powerful pipeline that effortlessly allows for automatic coupling with the rest of the existing models. Presently, even though Stark has a C++ and Python API, models can only be defined in C++.

By default, Stark comes out-of-the-box with important widely used models:

• 3D and 2D FEM with the non-linear Stable Neo-Hookean material
• Discrete Shells for cloths and stiff shells
• Rigid Bodies with joints and motors
• Frictional Contact with IPC

See the ICRA'24 paper about Stark here.

Hello World

The following is a script example using Stark's Python API to run a simulation of a piece of cloth falling on a rigid box with a prescribed spinning motion.

import numpy as np
import pystark

settings = pystark.Settings()
settings.output.simulation_name = "spinning_box_cloth"
settings.output.output_directory = "output_folder"
settings.output.codegen_directory = "codegen_folder"
simulation = pystark.Simulation(settings)

# Global frictional contact IPC parameters
contact_params = pystark.EnergyFrictionalContact.GlobalParams()
contact_params.default_contact_thickness = 0.001  # Can be overriden by per-object thickness
contact_params.friction_stick_slide_threshold = 0.01
simulation.interactions().contact().set_global_params(contact_params)

# Add deformable surface
cV, cT, cH = simulation.presets().deformables().add_surface_grid("cloth",
    size=np.array([0.4, 0.4]),
    subdivisions=np.array([20, 20]),
    params=pystark.Surface.Params.Cotton_Fabric()
)

# Add rigid body box
bV, bT, bH = simulation.presets().rigidbodies().add_box("box", mass=1.0, size=0.08)
bH.rigidbody.add_translation(np.array([0.0, 0.0, -0.08]))
fix_handler = simulation.rigidbodies().add_constraint_fix(bH.rigidbody)

# Set friction pair
cH.contact.set_friction(bH.contact, 1.0)

# Script
duration = 10.0
def script(t):
    fix_handler.set_transformation(
        translation=np.array([0.0, 0.0, -0.08 - 0.1*np.sin(t)]), 
        angle_deg=100.0*t, 
        axis=np.array([0.0, 0.0, 1.0]))
simulation.add_time_event(0, duration, script)

# Run
simulation.run(duration)

The output is a sequence of VTK files per output group (in this case one sequence for the cloth and another for the box). VTK files can be viewed in Blender with this add-on or in Paraview. You can use meshio to transform VTK meshes to other formats.

Stark code will always follow the same structure:

• Define global settings and parameters.
• Add objects, boundary conditions and define interactions. In this example, presets are used but custom objects and composed materials can be used.
• Optionally, specify time-dependent events (script).
• Run.

See the folder stark/pystark/examples for more scenes using the Python API and stark/examples for scenes written in C++.

Get Stark

Stark's C++ and Python APIs are essentially equivalent. A user who just wants to use Stark with the models that it comes with, probably will prefer the Python API. 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.

Every time Stark encounters a new potential energy, it will generate and compile code to compute its derivatives. Therefore, a C++17 compiler is required. 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++. By default, it is "g++" in Unix and a common location for the "vcvarsx86_amd64.bat" in Windows.

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. Don't forget to point Stark to the folder containing those in settings.output.codegen_directory.

Python API

pip install stark-sim

Build from source

To build from source you will need CMake and a C++17 compiler. All dependencies are bundled with Stark or are downloaded by CMake at build time.

Examples with code

twisting_cloth.py	boxes_on_cloth.py
inflation.py	viscoelasticity.py

Features

• Deformable objects
  • 3D and 2D linear FEM (tets and triangles) with the Stable Neo-Hookean constitutive model (paper)
  • Discrete Shells (paper)
  • Strain limiting (paper)
  • Inertial and material damping
• Rigid bodies
  • Soft joints (linear)
  • Smooth force/torque capped motors here
  • List of all joints and motors here
• Triangle mesh based attachments
  • Deformable - Deformable
  • Deformable - Rigid
  • Rigid - Rigid
• Triangle mesh based frictional contact
  • IPC paper
  • Adaptive logarithmic and cubic contact potentials
• Symbolic differentiation
  • Automatic generation of gradients and Hessians
  • Parallel evaluation and assembly
• Solver
  • Newton's Method
  • Intersection free line search (CDD coming soon)
  • Conjugate Gradient or Direct LU linear solver
  • Adaptive time step size
  • Optional projection to PD of element Hessians
• Event-based scripts

Works using Stark

Micropolar Elasticity in Physically-Based Animation - Löschner et al.

Cite Stark

@INPROCEEDINGS{FLL+24,
  author={Fernández-Fernández, José Antonio and Lange, Ralph and Laible, Stefan and Arras, Kai O. and Bender, Jan},
  booktitle={2024 IEEE International Conference on Robotics and Automation (ICRA)}, 
  title={STARK: A Unified Framework for Strongly Coupled Simulation of Rigid and Deformable Bodies with Frictional Contact}, 
  year={2024}
}

Acknowledgments

Stark was made possible by Bosch Reseach and the Computer Animation Group at RWTH Aachen University.

List of collaborators to the codebase:

• José Antonio Fernández-Fernández
• Fabian Löschner