https://github.com/zhehaoli1999/DiffFR
Tip revision: f7dc063b7f3c0330f345c5d52454c52c1f6f1f26 authored by Li Zhehao on 31 March 2024, 14:19:09 UTC
update readme to fix typo
update readme to fix typo
Tip revision: f7dc063
README.md
# DiffFR: Differentiable SPH-based Fluid-Rigid Coupling for Rigid Body Control
![](./images/teaser.jpg)
## 1. Introduction
This is the code base for our SIGGRAPH Asia 2023 paper.
We develop our method based on the open-source library [SPlisHSPlasH](https://github.com/InteractiveComputerGraphics/SPlisHSPlasH) and we sincerely thank the effort of its authors.
## 2. Installation
We have built and tested the code on Ubuntu22.04.
### 2.1 Prerequisite
Required infrastructures can be installed via:
```
sudo apt install git cmake xorg-dev freeglut3-dev build-essential libomp-dev
```
Required python packages can be directly installed by `pip install -r requirements.txt`.
### 2.2 How to build
First shallow clone this repo with git:
```
git clone --depth=5 git@github.com:zhehaoli1999/DiffFR.git
```
Then we recommend to create a new conda environment (such as "diffFR") and
activate it:
```
conda create --name diffFR python=3.7
conda activate diffFR
```
Then find `build.sh` under the root dir of the project, and use commands like `bash build.sh` to execuate this shell (please ensure your
shell has already execuated `conda init`). It will use cmake to configure the
project and then compile it with your compiler.
## 3. Experiments in paper
**You can find all raw data records and the scripts for figure plotting of our experiments in the `experiments` folder.**
The simulation scene settings are described as json files, and the initial setting of velocities and positions of fluid and rigid particles are stored as bgeo and binary files.
To run each task, you need to input a scene json file, as well as an optional binary file of the initial settings of the fluid environment (without specification, all fluid particles will have the positions described in the json file with zero velocities. )
### 3.1. Rigid body trajectory optimization
#### Data
| Task | Scene json file | state file | taskType | design variables | notes |
|---------------------------|--------------------------------|-----------------------------|------------------|------------------|-------------------------------------------------|
| water rafting | diff-water-rafting-bunny.json | water_rafting/state_130.bin | 'water-rafting' | vx, vz omega | load-fluid-pos-and-vel |
| high diving | diff-high-diving-duck.json | high_diving/state_98.bin | 'high-diving' | omega | load-fluid-pos |
| stone skipping | diff-stone-skipping.json | stone_skipping/state_18.bin | 'stone-skipping' | v, omega | load-fluid-pos |
| bottle flipping (stage 1) | diff-bottle-model.json | bottle_flip/state_54.bin | 'bottle-flip' | v, omega | load-fluid-pos |
| bottle flipping (stage 2) | diff-bottle-model-collide.json | bottle_flip/state_54.bin | 'bottle-flip' | v, omega | load-fluid-pos |
| on-water billiards | billiards-on-water-2balls.json | billiards/state_17.bin | - | v, omega | use `diff-rigid-contact-multi.py`, load-fluid-pos |
#### Commands to run
First, `cd ./experiments/rigid_body_trajectory_optimization/python`.
For gradient-based optimization (ours), use `gradient-based-optimize.py`. For gradient-free optimization (CMA-ES & 1+1 ES), use `opt-ng.py`.
+ bottle flipping
```
python gradient-based-optimize.py --scene=../scene/diff-bottle-model.json --state=../state/bottle_flip/state_54.bin --load-fluid-pos --taskType=bottle-flip
```
+ stone skipping
```
python gradient-based-optimize.py --scene=../scene/diff-stone-skipping.json --state=../state/stone_skipping/state_18.bin --load-fluid-pos --taskType=stone-skipping
```
+ water rafting
```
python gradient-based-optimize.py --scene=../scene/diff-water-rafting-bunny.json --state=../state/water_rafting/state_130 --load-fluid-pos-and-vel --taskType=water-rafting
```
+ high diving
```
python gradient-based-optimize.py --scene=../scene/diff-high-diving-duck.json --state=../state/high_diving/state_98.bin --load-fluid-pos --taskType=high-diving
```
+ on-water billiards
```
python diff-rigid-contact-multi.py --scene=../scene/billiards-on-water-2balls.json --state=../state/billiards/state_17.bin --load-fluid-pos
```
### 4.2. Self-supervised bottle flipping control policy
#### Commands to run
First, `cd ./experiments/bottle_flip_robot/python`
```
python bottle-flip-robot.py --scene=../scene/diff-bottle-model-360degree.json --state=../state/state_1.365999.bin --load-fluid-pos
```
### 4.3. On-water inverted pendulum robot controller
#### Commands to run
First, `cd ./experiments/on_water_inverted_pendulum/python`
Train:
```
python cartpole-diff-controller.py --scene=../scene/cartpole-diff-controller.json --state=../state/state_0.879992.bin --load-fluid-pos
```
Test:
```
python cartpole-diff-controller.py --scene=../scene/cartpole-diff-controller.json --state=../state/state_0.879992.bin --load-fluid-pos --test=../saved_models/success8s-2023-01-14-23-07-05-cartpole-epoch6.pth
```
### 4.4. Other comparison & ablation experiments
Please see the content of `./experiments/others` for code and raw data.
## 5. Postprocess & Rendering
For postprocess we use Houdini to reconstruct the fluid surface mesh from particles, and use Blender Cycles for rendering.
## 6. Contact & citation
If you have any question, please feel free to open an issue or email `zhehaoli@mail.ustc.edu.cn`.
To cite our paper, here is the bibtex:
```
@article{10.1145/3618318,
author = {Li, Zhehao and Xu, Qingyu and Ye, Xiaohan and Ren, Bo and Liu, Ligang},
title = {DiffFR: Differentiable SPH-Based Fluid-Rigid Coupling for Rigid Body Control},
year = {2023},
issue_date = {December 2023},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
volume = {42},
number = {6},
issn = {0730-0301},
url = {https://doi.org/10.1145/3618318},
doi = {10.1145/3618318},
journal = {ACM Trans. Graph.},
articleno = {179},
numpages = {17}
}
```
## 7. License
MIT License