diff --git a/README.md b/README.md index 41602d4..9f1be80 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,17 @@ This repository implements Motion Planning via Optimal Transport `mpot` in PyTorch. The philosophy of `mpot` follows Monte Carlo methods' argument, i.e., more samples could discover more better modes with high enough initialization variances. -In other words, `mpot` enables better **brute-force** planning with GPU vectorization, for robustness against bad local minima, which is common in optimization-based motion planning. +In other words, within multi-modal motion planning scope, `mpot` enables better **brute-force** planning with GPU vectorization. This enhances robustness against bad local minima, which is common in optimization-based motion planning. -![Point-mass with three goals](demos/planar.gif) +

+ + + +

## Installation -Simply install `mpot` by +Simply activate your conda/Python environment and run ```azure pip install -e . @@ -21,7 +25,7 @@ pip install -e . Please find in `examples/` folder the demo of vectorized planning in planar environments with occupancy map: ```azure -python examples/mpot_planar.py +python examples/mpot_occupancy.py ``` and with signed-distance-field (SDF): @@ -30,23 +34,23 @@ and with signed-distance-field (SDF): python examples/mpot_sdf.py ``` -We also added a demo with vectorized Panda planning with dense obstacle environments with SDF: +We also added a demo with vectorized Panda planning with dense obstacle environments (SDF): ```azure python examples/mpot_panda.py ``` -The resulting optimization visualizations are stored at your current directory. +Every run is associated with **a different seed**. The resulting optimization visualizations are stored at your current directory. Please refer to the example scripts for playing around with options and different goal points. Note that for all cases, we normalize the joint space to the joint limits and velocity limits, then perform Sinkhorn Step on the normalized state-space. Changing any hyperparameters may require tuning again. **Tuning Tips**: The most sensitive parameters are: -- `polytope`: for small state-dimension that is less than 20, `cube` or `orthoplex` are good choices. For much higer state-dimension, the only choice is `simplex`. -- `step_radius`: the step size +- `polytope`: for small state-dimension that is less than 10, `cube` is a good choice. For much higer state-dimension, the sensible choices are `orthoplex` or `simplex`. +- `step_radius`: the step size. - `probe_radius`: the probing radius, which projects towards polytope vertices to compute cost-to-go. Note, `probe_radius` >= `step_radius`. - `num_probe`: number of probing points along the probe radius. This is critical for optimizing performance, usually 3-5 is enough. - `epsilon`: decay rate of the step/probe size, usually 0.01-0.05. -- `ent_epsilon`: Sinkhorn entropy regularization, usually 1e-2 to 5e-2 for balancing between sharpness and speed. +- `ent_epsilon`: Sinkhorn entropy regularization, usually 1e-2 to 5e-2 for balancing between optimal coupling's sharpness and speed. - Various cost term weightings. This depends on your applications. ## Troubleshooting diff --git a/demos/occupancy.gif b/demos/occupancy.gif new file mode 100644 index 0000000..0e3b090 Binary files /dev/null and b/demos/occupancy.gif differ diff --git a/demos/panda.gif b/demos/panda.gif new file mode 100644 index 0000000..9aebc98 Binary files /dev/null and b/demos/panda.gif differ diff --git a/demos/planar.gif b/demos/planar.gif deleted file mode 100644 index 1f74a22..0000000 Binary files a/demos/planar.gif and /dev/null differ diff --git a/demos/sdf_grid.gif b/demos/sdf_grid.gif new file mode 100644 index 0000000..ea6b588 Binary files /dev/null and b/demos/sdf_grid.gif differ