{"id":24741210,"url":"https://github.com/hybridrobotics/car-racing","last_synced_at":"2025-07-18T22:36:52.203Z","repository":{"id":40361846,"uuid":"336110871","full_name":"HybridRobotics/car-racing","owner":"HybridRobotics","description":"A toolkit for testing control and planning algorithm for car racing.","archived":false,"fork":false,"pushed_at":"2024-04-19T23:15:30.000Z","size":40661,"stargazers_count":177,"open_issues_count":2,"forks_count":32,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-03T12:45:51.988Z","etag":null,"topics":["car-racing","casadi","control-barrier-functions","learning","model-predictive-control","nonlinear-optimization","obstacle-avoidance","optimization-algorithms","simulation","trajectory-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HybridRobotics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-02-04T23:32:58.000Z","updated_at":"2025-03-31T06:07:52.000Z","dependencies_parsed_at":"2024-04-20T00:35:31.896Z","dependency_job_id":null,"html_url":"https://github.com/HybridRobotics/car-racing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HybridRobotics/car-racing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HybridRobotics%2Fcar-racing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HybridRobotics%2Fcar-racing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HybridRobotics%2Fcar-racing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HybridRobotics%2Fcar-racing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HybridRobotics","download_url":"https://codeload.github.com/HybridRobotics/car-racing/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HybridRobotics%2Fcar-racing/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265846883,"owners_count":23838160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["car-racing","casadi","control-barrier-functions","learning","model-predictive-control","nonlinear-optimization","obstacle-avoidance","optimization-algorithms","simulation","trajectory-optimization"],"created_at":"2025-01-27T23:49:36.347Z","updated_at":"2025-07-18T22:36:52.162Z","avatar_url":"https://github.com/HybridRobotics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Status:** This repository is still under development, expecting new features/papers and a complete tutorial to explain it. Feel free to raise questions/suggestions through GitHub Issues, if you want to use the current version of this repository.\n\ncar-racing\n==========\n\nThis repository provides a toolkit to test control and planning problems for car racing simulation environment.\n\u003cdetails\u003e\n \u003csummary\u003eClick to open Table of Contents\u003c/summary\u003e\n\n## Table of Contents\n- [Preview](#preview)\n- [References](#references)\n- [Features](#features)\n- [Installation](#installation)\n- [Contributing](#contributing)\n- [Quick-Demos](#quick-demos)\n- [Docs](#docs)\n    - [Offboard](#offboard)\n    - [Realtime](#realtime)\n\u003c/details\u003e\n\n## Preview\n\u003cimg src=\"/media/release/icra2022.gif?raw=true\" width=\"800\"/\u003e\n\n## References\nIf you find this project useful in your work, please consider citing following papers:\n\nParallelized optimization for overtake racing behavior with multiple autonomous vehicles [[IEEE]](https://ieeexplore.ieee.org/document/9811969) [[arXiv]](https://arxiv.org/abs/2112.06435) [[Video]](https://youtu.be/1zTXfzdQ8w4)\n```\n@inproceedings{he2022parallel,\n  title={Autonomous racing with multiple vehicles using a parallelized optimization with safety guarantee using control barrier functions},\n  author={He, Suiyi and Zeng, Jun and Sreenath, Koushil},\n  booktitle={2022 IEEE International Conference on Robotics and Automation (ICRA)},\n  year={2022}\n}\n```\n\nDesign model predictive control with control barrier functions for obstacle avoidance in car racing problems [[IEEE]](https://ieeexplore.ieee.org/abstract/document/9483029) [[arXiv]](https://arxiv.org/abs/2007.11718) [[NorCal Control Workshop Talk]](https://youtu.be/IfNgogcLSjE)\n```\n@inproceedings{zeng2021mpccbf,\n  title={Safety-critical model predictive control with discrete-time control barrier function},\n  author={Zeng, Jun and Zhang, Bike and Sreenath, Koushil},\n  booktitle={2021 American Control Conference (ACC)},\n  year={2021},\n  volume={},\n  number={},\n  pages={3882-3889}\n}\n```\n\n## Features\n\n## Installation\n* We recommend creating a new conda environment:\n```\nconda env create -f environment.yml\nconda activate car-racing\n```\n\nRun following command in terminal to install the car racing simulator package.\n```\npip install -e .\n```\n\n## Auto Testing\n\nIn this project, `pytest` is used to test the code autonomously after pushing new code to the repository. Currently, three files in the `tests` folder are used for testing pid or mpc tracking controller, mpc-cbf controller and racing game planner, respectively. To test other features, add files to the `tests` folder and update the `tests.yml` file under the `.github/workflows` folder.\n\n## Contributing\nExecute `pre-commit install` to install git hooks in your `.git/` directory, which allows auto-formatting if you are willing to contribute to this repository.\n\nPlease contact major contributors of this repository for additional information.\n\n## Quick-Demos\n\n## Docs\nThe following documentation contains documentation and common terminal commands for simulations and testing.\n\n### Offboard\n\n#### System Identification\nRun\n```\npython car_racing/tests/system_identification_test.py\n```\nThis allows to identify the linearized dynamics of the racing car by regression.\n\n#### Tracking performance with controllers\nRun\n```\npython car_racing/tests/control_test.py --ctrl-policy mpc-lti --track-layout l_shape --simulation --plotting --animation \n```\nThis allows to test algorithm for tracking. The argparse arguments are listed as follow,\n| name | type | choices | description |\n| :---: | :---: | :---: | :---: |\n| `ctrl_policy` | string | `pid`, `mpc-lti`, `lqr` | control policy |\n| `track_layout` | string | `l_shape`, `m_shape`, `goggle`, `ellipse` | track layouts |\n| `simulation` | action | `store_true` | generate simulation data if true, otherwise read simulation data from existing files |\n| `plotting` | action | `store_true` | save plotting if true |\n| `animation` | action | `store_true` | save animation if true |\n\n#### Racing competition with ego controller (MPC-CBF)\nRun\n```\npython car_racing/tests/mpccbf_test.py --track-layout l_shape --simulation --plotting --animation\n```\nThis allows to test algorithm for MPC-CBF controller. The argparse arguments are listed as follow,\n| name | type | choices | description |\n| :---: | :---: | :---: | :---: |\n| `track_layout` | string | `l_shape`, `m_shape`, `goggle`, `ellipse` | track layouts |\n| `simulation` | action | `store_true` | generate simulation data if true, otherwise read simulation data from existing files |\n| `plotting` | action | `store_true` | save plotting if true |\n| `animation` | action | `store_true` | save animation if true |\n\n#### Racing competition with ego controller (iLQR)\nRun\n\n```\npython car_racing/tests/ilqr_test.py --track-layout l_shape --simulation --plotting --animation\n```\n\nThis allows to test algorithm for iLQR controller. The argparse arguments are listed as follow,\n\n|      name      |  type  |                  choices                  |                         description                          |\n| :------------: | :----: | :---------------------------------------: | :----------------------------------------------------------: |\n| `track_layout` | string | `l_shape`, `m_shape`, `goggle`, `ellipse` |                        track layouts                         |\n|  `simulation`  | action |               `store_true`                | generate simulation data if true, otherwise read simulation data from existing files |\n|   `plotting`   | action |               `store_true`                |                    save plotting if true                     |\n|  `animation`   | action |               `store_true`                |                    save animation if true                    |\n\n#### Racing competition with ego controller (LMPC)\nTo save the historic states and inputs used for learning-based MPC, run the following command for each track layout firstly:\n```\npython car_racing/tests/lmpc_test.py \\\n--track-layout l_shape --lap-number 7 --simulation --save-trajectory\n```\nThen you can run the following command: \n```\npython car_racing/tests/lmpc_test.py \\\n--track-layout l_shape --lap-number 10 --simulation --direct-lmpc --animation --plotting\n```\nThis allows to test algorithm for learning-based MPC. The argparse arguments are listed as follow,\n| name | type | choices | description |\n| :---: | :---: | :---: | :---: |\n| `track_layout` | string | `l_shape`, `m_shape`, `goggle`, `ellipse` | track layouts |\n| `lap_number` | int | any number that is greater than `2` | number of laps that will be simulated |\n| `direct_lmpc` | action | `store_true` | if true, the simulator will begin the LMPC controller directly using store trajectories |\n| `zero_noise` | action | `store_true` | no noises in dynamic update if true |\n|`save_trajectory`| action |`store_true`|if true and when the controller is LMPC, simulator will store the history states and inputs|\n| `simulation` | action | `store_true` | generate simulation data if true, otherwise read simulation data from existing files |\n| `plotting` | action | `store_true` | save plotting if true |\n| `animation` | action | `store_true` | save animation if true |\n\n#### Racing competition with ego planner and controller\nTo save the historic states and inputs used for learning-based MPC, run the following command for each track layout firstly:\n```\npython car_racing/tests/overtake_planner_test.py \\\n--track-layout l_shape --lap-number 7 --simulation --number-other-agents 0 --save-trajectory\n```\nThen you can run the following command: \n```\npython car_racing/tests/overtake_planner_test.py \\\n--track-layout l_shape --lap-number 10 --simulation --direct-lmpc --animation --plotting --number-other-agents 3\n```\nThis allows to test algorithm for racing competition. The argparse arguments are listed as follow,\n| name | type | choices | description |\n| :---: | :---: | :---: | :---: |\n| `track_layout` | string | `l_shape`, `m_shape`, `goggle`, `ellipse` | track layouts |\n| `lap_number` | int | any number that is greater than `2` | number of laps that will be simulated |\n| `direct_lmpc` | action | `store_true` | if true, the simulator will begin the LMPC controller directly using store trajectories |\n| `sim_replay` | action | `store_true` | if true, by changingfile path, the simulator will simulate with different parameters but from same initial conditions |\n| `zero_noise` | action | `store_true` | no noises in dynamic update if true |\n| `diff_alpha` | action | `store_true` | if true, different alpha values will be used for same initial conditions |\n| `random_other_agents` | action | `store_true` | other agents will be generated randomly if true |\n| `number_other_agents` | int | any number that is greater than `0`, when it is set to `0`, the algorithm is LMPC | number of agents that will be generated |\n|`save_trajectory`| action |`store_true`|if true and when the controller is LMPC, simulator will store the history states and inputs|\n|`multi_tests`| action | `store_true`| if ture, 100 groups of randomly generated tests will be simulated|\n| `simulation` | action | `store_true` | generate simulation data if true, otherwise read simulation data from existing files |\n| `plotting` | action | `store_true` | save plotting if true |\n| `animation` | action | `store_true` | save animation if true |\n\n\nCurrently, path planner and trajecotry planner are available for the overtaking maneuver. Changing the varibale `self.path_planner` in `base.py` to `True` allows the controller to simulate with path planner.\n\n### Realtime (under development)\nTo start the simulator, run the following command in terminal:\n```\nroslaunch car_racing car_racing_sim.launch track_layout:=goggle\n```\nThis allows you to run the simulator and visualization node. Change the `track_layout`, you can get differnt tracks. The center line of the race track is plotted in red dash line; the optimal trajectory of the race track is plotted in green line.\nTo add new vehicle with controller in the simulator, run the following commands in new terminals:\n```\nrosrun car_racing vehicle.py --veh-name vehicle1 --color blue --vx 0 --vy 0 --wz 0 --epsi 0 --s 0 --ey 0\n\nrosrun car_racing controller.py --ctrl-policy mpc-lti --veh-name vehicle1\n```\nThese allow to start nodes for the vehicle and corresponding controller. The argparse arguments are listed as follow,\n| name | type | choices | description |\n| :---: | :---: | :---: | :---: |\n| `veh_name` | string | a self-defined name | vehicle's name |\n| `color` | string | color's name | vehicle's color in animation |\n| `vs`, `vy`, `wz`, `epsi`, `s`, `ey` | float | initial states |vehicle's initial states in Frenet coordinates |\n| `ctrl_policy` | string | `pid`, `mpc-lti`, `mpc-cbf` , `lmpc`| vehicle's controller type|\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhybridrobotics%2Fcar-racing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhybridrobotics%2Fcar-racing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhybridrobotics%2Fcar-racing/lists"}