Jax Official Implementation of Paper: K Garg*, J Arkin, S Zhang, N Roy, C Fan: "Large Language Models to the Rescue: Deadlock Resolution in Multi-Robot Systems".
We recommend to use CONDA to install the requirements:
conda create -n gcbfplus python=3.10
conda activate gcbfplus
cd gcbfplusThen install jax following the official instructions, and then install the rest of the dependencies:
pip install -r requirements.txtInstall GCBF:
pip install -e .To run the high-level planner for deadlock resolution, use:
python -u test_with_LLM.py --path logs/SingleIntegrator/gcbf+/model_with_traj/seed0_20240227110346 -n 10 --epi 20 --obs 25 --max-step 2500 --area-size 4 --keep-mode 20 --nojit-rollout --num-incontext-prompts 0 --leader_model 'gpt3.5' --num_LLM_calls 1
where the flags are:
-n: number of agents--obs: number of obstacles--area-size: side length of the environment--max-step: maximum number of steps for each episode, increase this if you have a large environment--path: path to the log folder--keep-mode: keep mode for the high-level planner--num-incontext-prompts: number of in-context examples--leader_model: leader model for the high-level planner including- 'gpt3.5'
- 'gpt4'
- 'hand' for hand-designed heuristic leader-assignment
- 'fixed' for fixed leader-assignment
- 'random' for random leader-assignment
- 'none' for no leader-assignment
--num_LLM_calls: number of LLM calls for "Ensemble" implementation of the high-level planner
For testing on "Randomized room" environment, use:
python -u test_with_LLM.py --path logs/SingleIntegrator/gcbf+/model_with_traj/seed0_20240227110346/ -n 1 --epi 20 --obs 1 --preset_reset --preset_scene 'rand box' --max-step 2500 --area-size 1 --keep-mode 20 --nojit-rollout --num-incontext-prompts 0 --leader_model 'gpt3.5' --num_LLM_calls 1 where
---preset_reset is used to reset the environment to a fixed initial state from
- 'rand box' for a random room environment
- 'original box' for a fixed room environment
- 'box' for room-like environment with more obstacles.
We provide 3 2D environments including SingleIntegrator, DoubleIntegrator, and DubinsCar, and 2 3D environments including LinearDrone and CrazyFlie.
We provide algorithms including GCBF+ (gcbf+), GCBF (gcbf), centralized CBF-QP (centralized_cbf), and decentralized CBF-QP (dec_share_cbf). Use --algo to specify the algorithm.
To reproduce the results shown in our paper, one can refer to settings.yaml.
To train the model (only GCBF+ and GCBF need training), use:
python train.py --algo gcbf+ --env DoubleIntegrator -n 8 --area-size 4 --loss-action-coef 1e-4 --n-env-train 16 --lr-actor: 1e-5 --lr-cbf: 1e-5 --horizon: 32In our paper, we use 8 agents with 1000 training steps. The training logs will be saved in folder ./logs/<env>/<algo>/seed<seed>_<training-start-time>. We also provide the following flags:
-n: number of agents--env: environment, includingSingleIntegrator,DoubleIntegrator,DubinsCar,LinearDrone, andCrazyFlie--algo: algorithm, includinggcbf,gcbf+--seed: random seed--steps: number of training steps--name: name of the experiment--debug: debug mode: no recording, no saving--obs: number of obstacles--n-rays: number of LiDAR rays--area-size: side length of the environment--n-env-train: number of environments for training--n-env-test: number of environments for testing--log-dir: path to save the training logs--eval-interval: interval of evaluation--eval-epi: number of episodes for evaluation--save-interval: interval of saving the model
In addition, use the following flags to specify the hyper-parameters:
--alpha: GCBF alpha--horizon: GCBF+ look forward horizon--lr-actor: learning rate of the actor--lr-cbf: learning rate of the CBF--loss-action-coef: coefficient of the action loss--loss-h-dot-coef: coefficient of the h_dot loss--loss-safe-coef: coefficient of the safe loss--loss-unsafe-coef: coefficient of the unsafe loss--buffer-size: size of the replay buffer
To test the learned model, use:
python test.py --path <path-to-log> --epi 5 --area-size 4 -n 16 --obs 0This should report the safety rate, goal reaching rate, and success rate of the learned model, and generate videos of the learned model in <path-to-log>/videos. Use the following flags to customize the test:
-n: number of agents--obs: number of obstacles--area-size: side length of the environment--max-step: maximum number of steps for each episode, increase this if you have a large environment--path: path to the log folder--n-rays: number of LiDAR rays--alpha: CBF alpha, used in centralized CBF-QP and decentralized CBF-QP--max-travel: maximum travel distance of agents--cbf: plot the CBF contour of this agent, only support 2D environments--seed: random seed--debug: debug mode--cpu: use CPU--u-ref: test the nominal controller--env: test environment (not needed if the log folder is specified)--algo: test algorithm (not needed if the log folder is specified)--step: test step (not needed if testing the last saved model)--epi: number of episodes to test--offset: offset of the random seeds--no-video: do not generate videos--log: log the results to a file--dpi: dpi of the video--nojit-rollout: do not use jit to speed up the rollout, used for large-scale tests
To test the nominal controller, use:
python test.py --env SingleIntegrator -n 16 --u-ref --epi 1 --area-size 4 --obs 0To test the CBF-QPs, use:
python test.py --env SingleIntegrator -n 16 --algo dec_share_cbf --epi 1 --area-size 4 --obs 0 --alpha 1We provide the pre-trained models in the folder logs.