Skip to content

Commit bfeaee4

Browse files
alberthlislecleach
alberthli
and
slecleach
authored
Update documentation (#43)
* add a CHANGELOG.md file to track changes publicly * update with contribution guidelines * incomplete task readme * finish task descriptions * move the description of the changelog file addition in the changelog under the documentation section * add disclaimer about high numbers of default threads to certain task descriptions * add a CONTRIBUTING.md file --------- Co-authored-by: simon lecleach <135636415+slecleach@users.noreply.github.com>
1 parent bda474c commit bfeaee4

4 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# v0.0.2
2+
This release contains bugfixes prior to RSS 2025.
3+
4+
## Added
5+
* New `judo`-specific branding! (@slecleach, #42)
6+
7+
## Fixed
8+
* Brandon's last name misspelling in citation in README.md (@pculbertson, #15)
9+
* Fixed `max_opt_iters` not correctly being applied (@lujieyang and @tzhao-bdai, #14)
10+
* Added a test to check for this case (@alberthli, #16)
11+
* Fix bug where if no `exclude_geom_substring` is passed to the model visualizer, all geoms are accidentally excluded (@alberthli, #17)
12+
* Fix bug where when `max_opt_iters>1`, the shape of `nominal_knots` is not correct. **NEW BEHAVIOR:** in the controller, `self.nominal_knots` now has shape `(num_knots, nu)` instead of `(1, num_knots, nu)` (@yunhaif, #29).
13+
* Update model loading so that textures appear correctly in the visualizer (@pculbertson, #32)
14+
* Fix bug where leap cube task encountered division by 0 in axis normalization (@alberthli, #34)
15+
* Fixed bug where changing tasks added accumulating grey lines to the GUI (@slecleach, #44)
16+
17+
## Documentation
18+
* Changelog file to track changes in the repository (@alberthli, #43)
19+
* Added contributor guidelines to the README (@alberthli, #43)
20+
* Added information about the tasks in a task README (@alberthli, #43)
21+
22+
## Dev
23+
* Bump prefix-dev/setup-pixi from 0.8.8 to 0.8.10 (#18)
24+
* Create workflow for manually publishing releases to PyPi (@alberthli, #33)
25+
* Update a bunch of versions for pixi (@alberthli, #40)
26+
27+
# v0.0.1
28+
Initial release!

‎CONTRIBUTING.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Contributing to Judo 🥋
2+
3+
Thank you for your interest in contributing to `judo`! 🎉
4+
We welcome bug reports, feature suggestions, documentation improvements, and pull requests of all kinds.
5+
6+
## 📌 Guidelines Overview
7+
8+
- **Bug reports**: Please include a minimal reproducible example and relevant log output.
9+
- **Feature requests**: Keep them concise and focused. If you're unsure, open an issue for discussion first.
10+
- **Pull requests**: Follow our style guide, write clear commit messages, and document any new features or changes.
11+
12+
## ⚙️ Development Setup
13+
14+
We recommend using either `conda` or [`pixi`](https://pixi.sh) to manage your development environment.
15+
16+
### Conda Setup
17+
18+
```bash
19+
conda create -n judo python=3.13
20+
conda activate judo
21+
pip install -e .[dev]
22+
pre-commit install
23+
pybind11-stubgen mujoco -o typings/
24+
```
25+
26+
### Pixi Setup
27+
28+
```bash
29+
# Install pixi (once)
30+
curl -fsSL https://pixi.sh/install.sh | sh
31+
32+
# Activate dev environment
33+
pixi shell -e dev
34+
35+
# First-time setup
36+
pre-commit install
37+
pybind11-stubgen mujoco -o typings/
38+
```
39+
40+
## 🧹 Code Style and Linting
41+
42+
We use the following tools:
43+
44+
| Tool | Purpose |
45+
|------------|----------------------------|
46+
| Ruff | Formatting and linting |
47+
| Pyright | Static type checking |
48+
| Pre-commit | Auto-formatting and checks |
49+
| Pytest | Unit and integration tests |
50+
| Sphinx | Documentation |
51+
| Codecov | Code coverage reporting |
52+
53+
To check your code before committing:
54+
55+
```bash
56+
pre-commit run --all-files # style, formatting, etc.
57+
pyright # type checks (not part of pre-commit)
58+
pytest # run the test suite
59+
```
60+
61+
All CI checks must pass before a PR can be merged.
62+
63+
---
64+
65+
## 🧪 Adding a New Task or Optimizer
66+
67+
If you add a new task or optimizer:
68+
69+
1. Register it with the appropriate entry point in the codebase.
70+
2. Update [`judo/tasks/README.md`](judo/tasks/README.md) with:
71+
- Task name
72+
- Brief description
73+
- Default parameters
74+
- Known limitations or tips
75+
76+
## 📝 Submitting a Pull Request
77+
78+
Before opening a pull request, please:
79+
80+
- Ensure your code is tested and documented.
81+
- Run all pre-commit and type checks.
82+
- Keep PRs focused and concise (open multiple PRs if needed).
83+
- Use clear and descriptive commit messages.
84+
85+
Example:
86+
```
87+
feat(task): add fr3_stack task with novel constraints
88+
fix(mppi): guard against div-by-zero in cost calculation
89+
```
90+
91+
## 📄 Docs
92+
93+
To build the documentation locally:
94+
95+
```bash
96+
pip install -r docs/requirements.txt
97+
sphinx-build docs/source docs/build -b dirhtml
98+
python -m http.server --directory docs/build 8000
99+
```
100+
101+
## 💬 Discussions
102+
103+
Have questions or ideas?
104+
105+
- Use [GitHub Issues](https://github.com/bdaiinstitute/judo/issues) to report bugs or suggest features.
106+
- For general discussion, clarifications, or help, open a "Discussion" or start a draft PR.
107+
108+
## 🙏 Thanks
109+
110+
Judo is an early-stage research project maintained by a small team. We greatly appreciate community feedback and help. Whether you fix a typo or add a new planning strategy, your contribution makes a difference!
111+
112+
Thank you for supporting open-source robotics. 🤖

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,8 @@ if __name__ == "__main__":
107107
app() # this runs the app from your own script
108108
```
109109

110+
To see more information about the available tasks, please refer to [the task README](judo/tasks/README.md).
111+
110112
## 3. Running `judo` as a Dependency
111113
You can easily install `judo` as a dependency in your own project. A few comments:
112114
* You can still use the `judo` CLI command from anywhere, so long as you are working in an environment where `judo` is installed.
@@ -130,6 +132,10 @@ sphinx-build docs/source docs/build -b dirhtml
130132
python -m http.server --directory docs/build 8000
131133
```
132134

135+
## 🤝 Contributing
136+
We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) guide to get started.
137+
138+
133139
# Citation
134140
If you use `judo` in your research, please use the following citation:
135141
```

‎judo/tasks/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Tasks
2+
This README documents all of the tasks that are currently available in Judo.
3+
4+
| Task | Description |
5+
| ---- | ----------- |
6+
| [cylinder_push](#cylinder-push) | Push a cylinder to a target position with another actuated cylinder. |
7+
| [cartpole](#cartpole) | Swing up a cartpole with actuator limits to a target angle. |
8+
| [fr3_pick](#fr3-pick) | Pick up a cube with a Franka robot and place it in a target location. |
9+
| [leap_cube](#leap-cube) | Rotate a cube to a target orientation using a LEAP hand. |
10+
| [leap_cube_down](#leap-cube-down) | Rotate a cube to a target orientation using a LEAP hand, but with the palm facing down. |
11+
| [caltech_leap_cube](#caltech-leap-cube) | Rotate a cube to a target orientation using a modified LEAP hand at Caltech. |
12+
13+
## Cylinder Push
14+
The cylinder push task has the following weights:
15+
16+
| Weight | Description |
17+
| ------ | ----------- |
18+
| `w_pusher_proximity` | Penalizes the distance between the pusher and a point offset from the cart along the direction to the goal. |
19+
| `w_pusher_velocity` | Penalizes the squared linear velocity of the pusher. |
20+
| `w_cart_position` | Penalizes the distance from the cart to the goal. |
21+
22+
There are other tunable parameters:
23+
24+
| Parameter | Description |
25+
| --------- | ----------- |
26+
| `pusher_goal_offset` | The offset distance from the cart that defines the pusher's target. |
27+
| `goal_pos` | The 2D target position for the cart. |
28+
29+
## Cartpole
30+
The cartpole task has the following weights:
31+
32+
| Weight | Description |
33+
| ------ | ----------- |
34+
| `w_vertical` | Penalizes the distance between the pole's angle and its upright (vertical) position. |
35+
| `w_centered` | Penalizes the distance of the cart from the origin. |
36+
| `w_velocity` | Penalizes the squared linear and angular velocities of the cart and pole. |
37+
| `w_control` | Penalizes the amount of control effort applied. |
38+
39+
---
40+
41+
There are other tunable parameters:
42+
43+
| Parameter | Description |
44+
| --------- | ----------- |
45+
| `p_vertical` | The threshold parameter for the smooth L1 norm used in the `w_vertical` penalty. |
46+
| `p_centered` | The threshold parameter for the smooth L1 norm used in the `w_centered` penalty. |
47+
48+
## FR3 Pick
49+
The FR3 Pick task involves a Franka Research 3 picking up an object and placing it at a goal location. The task is divided into four phases, the first three of which have reward weights, and also includes global reward weights applied throughout the task.
50+
51+
> ⚠️ **Disclaimer** ⚠️
52+
>
53+
> This task is currently configured to use up to 64 threads by default (depending on the optimizer)! For most users, this is too many, and will be very slow. You can adjust this in the GUI or update the default value.
54+
55+
### Reward Weights
56+
57+
#### Lift Phase Weights
58+
These weights are active during the "LIFT" phase, when the object is being lifted from the table.
59+
60+
| Weight | Description |
61+
| ------ | ----------- |
62+
| `w_lift_close` | Penalizes the distance between the end-effector's grasp site and the object. Encourages the robot to grasp the object. |
63+
| `w_lift_height` | Penalizes the squared difference between the object's current height and a predefined `pick_height`. Encourages lifting the object to a certain height. |
64+
65+
#### Move Phase Weights
66+
These weights are active during the "MOVE" phase, when the object is being moved towards the goal position.
67+
68+
| Weight | Description |
69+
| ------ | ----------- |
70+
| `w_move_goal` | Penalizes the distance between the object's XY position and the target `goal_pos`. Encourages moving the object to the goal. |
71+
| `w_move_close` | Penalizes the distance between the end-effector's grasp site and the object. Encourages maintaining a grasp on the object. |
72+
73+
#### Place Phase Weights
74+
These weights are active during the "PLACE" phase, when the object is being placed on the table at the goal.
75+
76+
| Weight | Description |
77+
| ------ | ----------- |
78+
| `w_place_table` | Penalizes the distance between the object and the table. Encourages placing the object on the table. |
79+
| `w_place_goal` | Penalizes the distance between the object's XY position and the target `goal_pos`. Encourages placing the object accurately at the goal. |
80+
81+
#### Home Phase Weights
82+
Once placed, the system enters the "HOME" phase and homes the arm, but there is only one reward term in this phase, so no additional weights.
83+
84+
#### Global Weights
85+
These weights are applied across all phases of the task.
86+
87+
| Weight | Description |
88+
| ------ | ----------- |
89+
| `w_upright` | Penalizes the deviation of the end-effector's Z-axis from a purely downward (upright) orientation. Encourages maintaining an upright end-effector. |
90+
| `w_coll` | Rewards avoiding contact between the robot hand (fingers) and the table. |
91+
| `w_qvel` | Penalizes the norm of the robot's joint velocities, with a decay over time. Encourages smoother, less erratic movements. |
92+
| `w_open` | Penalizes the squared difference between the gripper position and an "open" position (0.04). Encourages the gripper to be open. |
93+
94+
### Other Tunable Parameters
95+
96+
| Parameter | Description |
97+
| --------- | ----------- |
98+
| `goal_pos` | The 2D (x, y) target position for the object to be placed. |
99+
| `goal_radius` | The radius around `goal_pos` that defines the goal region for the object. |
100+
| `pick_height` | The desired height the object should reach during the `LIFT` phase. |
101+
102+
## Leap Cube
103+
The LEAP Cube Rotation task involves a robotic hand manipulating a cube to achieve a desired orientation while maintaining its position.
104+
105+
| Weight | Description |
106+
| ------ | ----------- |
107+
| `w_pos` | Penalizes the squared difference between the cube's current 3D position and a fixed `goal_pos`. Encourages the cube to stay at the target position. |
108+
| `w_rot` | Penalizes the squared difference in orientation (using SO(3) distance) between the cube's current quaternion and a target `goal_quat`. Encourages the cube to achieve the desired rotation. |
109+
110+
## Leap Cube Down
111+
This works the same way as the LEAP Cube task, but the palm is facing downwards.
112+
113+
> ⚠️ **Disclaimer** ⚠️
114+
>
115+
> This task is currently configured to use up to 64 threads by default (depending on the optimizer)! For most users, this is too many, and will be very slow. You can adjust this in the GUI or update the default value.
116+
117+
## Caltech Leap Cube
118+
This works the same way as the LEAP Cube task, but uses a modified LEAP hand model from Caltech.
119+
120+
> ⚠️ **Disclaimer** ⚠️
121+
>
122+
> This task is currently configured to use up to 32 threads by default (depending on the optimizer)! For many users, this is too many, and will be very slow. You can adjust this in the GUI or update the default value.

0 commit comments

Comments
 (0)