{"id":15047865,"url":"https://github.com/ninivert/chaotic-billiard","last_synced_at":"2026-01-31T22:31:19.152Z","repository":{"id":128919896,"uuid":"406533497","full_name":"ninivert/chaotic-billiard","owner":"ninivert","description":"A chaotic billiard simulator written in C++, with Python bindings for data analysis.","archived":false,"fork":false,"pushed_at":"2022-05-21T15:27:00.000Z","size":5165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T11:09:56.448Z","etag":null,"topics":["chaotic-billiard","chaotic-systems","cplusplus-11","python","simulation"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ninivert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-09-14T22:02:27.000Z","updated_at":"2024-01-01T07:19:08.000Z","dependencies_parsed_at":"2023-03-24T04:48:03.700Z","dependency_job_id":null,"html_url":"https://github.com/ninivert/chaotic-billiard","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"e79fbd57c971d7ff069ce1afb34ea3511e4069d9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ninivert/chaotic-billiard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninivert%2Fchaotic-billiard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninivert%2Fchaotic-billiard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninivert%2Fchaotic-billiard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninivert%2Fchaotic-billiard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ninivert","download_url":"https://codeload.github.com/ninivert/chaotic-billiard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ninivert%2Fchaotic-billiard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28958341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T22:20:19.638Z","status":"ssl_error","status_checked_at":"2026-01-31T22:18:07.061Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["chaotic-billiard","chaotic-systems","cplusplus-11","python","simulation"],"created_at":"2024-09-24T21:05:23.613Z","updated_at":"2026-01-31T22:31:19.123Z","avatar_url":"https://github.com/ninivert.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chaotic billiard demo\n\nA chaotic billiard simulator written in C++, with Python bindings for data analysis.\n\nFeatures\n- `dt`-agnostic collision resolution (can resolve multiple collisions per frame)\n- supports arbitrary parametrized mathematical curves (currently implemented : `Line`, `Segment`, `Arc`, `BezierCurve`)\n- OpenGL renderer (via SFML) and headless rendering\n- Python bindings to perform data analysis while using the performance of C++\n\n[![Demo](images/thumb_demo.png)](https://www.youtube.com/watch?v=G_yAgBOhJOE\u0026list=PLbdJZHRJVb0fmdZQhT87H0tJvsRJSCuWR\u0026index=1)\n[See the a demo https://www.youtube.com/watch?v=G_yAgBOhJOE\u0026list=PLbdJZHRJVb0fmdZQhT87H0tJvsRJSCuWR\u0026index=1](https://www.youtube.com/watch?v=G_yAgBOhJOE\u0026list=PLbdJZHRJVb0fmdZQhT87H0tJvsRJSCuWR\u0026index=1)\n\n## Building the C++ source\n\nPrerequisite : `cmake` and `SFML` (for the gui)\n\n```sh\ncmake -S. -Bbuild\ncmake --build ./build --target physics gui\n```\n\n## Running the C++ GUI\n\n```\n$ ./build/gui/gui --help\nUsage: chaotic billiard [options] worldfile \n\nPositional arguments:\nworldfile       \t.json file containing world information\n\nOptional arguments:\n-h --help       \tshows help message and exits\n-v --version    \tprints version information and exits\n--window        \tdisplay a render window [default: false]\n--render        \trender to file (not recommended when --window is used) [default: false]\n--adaptative-dt \tuse a flexible dt determined by framerate [default: false]\n--duration      \tduration of the simulation [default: 100]\n--nsamples      \tnumber of steps the simulation has to undergo [default: 100]\n```\n\nLoad a worldfile and show the rendering window with adaptative timestep\n\n```\n./build/gui/gui worldfiles/world_circle.json --adaptative-dt --window\n```\n\nRender individual frames (n=100 frames, total duration=1000) (requires `ffmpeg` to stitch frames together)\n\n```\nmkdir -p frames render\n./build/gui/gui worldfiles/world_circle.json --render --duration 1000 --nsamples 100\nffmpeg -framerate 30 -i frames/frame%d.png -c:v libx264 -r 30 -pix_fmt yuv420p render/world_circle.mp4\nrm -r frames\n```\n\n## Custom world files\n\nUncomment the `export_world_json.cpp` target executable from `gui/CMakeLists.txt`, build and run.\n\nAlternatively this could also be done in Python, using the bindings.\n\n## Python bindings\n\nUsing `pybind11`, it is possible to use C++ for the simulation, and use the results directly in Python for data analysis.\n\n### Building steps\n\nPrerequisite : install the pybind11 `smart_holder` branch ([see also this demo for instructions](https://github.com/ninivert/pybind11-smart-holder-demo))\n\n```sh\ncd pychaotic_billiard\nmake build\n```\n\n### Run a demo\n\nPrerequisites : `pyglet`, `numpy`\n\nLaunch a demo with all the curves (Segment, Arc, Bezier)\n\n```sh\npython demo.py\n```\n\nLaunch a demo from a world file\n\n```sh\npython demo.py ../worldfiles/world_circle3.json\n```\n\nOther demos\n- `demo_from_worldfile` : demonstrates loading a World from a world file\n- `demo_to_worldfile` : demonstrates saving a World state, generated in Python\n\n\n### Computing a Lyapunov exponent\n\nOne example is tracking the distance of two balls as a function of time, which can be use to compute the Lyapunov exponent of the system. See [`pychaotic_billiard/demo_lyapunov.py`](pychaotic_billiard/demo_lyapunov.py)\n\n```python\nworld = World()\nangle0 = 0.02\ndelta0 = 0.001\n\nworld.add_curve(Segment(vec2(50, 50), vec2(450, 50)))\nworld.add_curve(Segment(vec2(450, 50), vec2(450, 450)))\nworld.add_curve(Segment(vec2(450, 450), vec2(50, 450)))\nworld.add_curve(Segment(vec2(50, 450), vec2(50, 50)))\nworld.add_curve(Arc(vec2(250, 250), 50, 0, 2*np.pi))\nworld.add_ball(Ball(vec2(350, 250), vec2(np.cos(angle0-delta0/2), np.sin(angle0-delta0/2))))\nworld.add_ball(Ball(vec2(350, 250), vec2(np.cos(angle0+delta0/2), np.sin(angle0+delta0/2))))\n\nnsteps = 100_000\nnballs = len(world.balls)\npos = np.empty((nsteps, nballs, 2))\nfor i in range(nsteps):\n\tworld.step(0.2)\n\tfor j in range(nballs):\n\t\tpos[i, j, 0] = world.get_ball(j).pos.x\n\t\tpos[i, j, 1] = world.get_ball(j).pos.y\n\nfig, ax = plt.subplots()\n# ...\nfor j in range(pos.shape[1]):\n\tax.plot(pos[:, j, 0].T, pos[:, j, 1].T)\n\nfig, ax = plt.subplots()\n# ...\nax.plot(np.linalg.norm(pos[:20_000, 0, :] - pos[:20_000, 1, :], axis=-1))\n\nplt.show()\n```\n\n![Lyapunov XY](images/lyapunov_xy.png)\n\n![Lyapunov Delta](images/lyapunov_delta.png)\n\n### Testing bindings\n\n```sh\n$ python test_segment.py\n\u003e\u003e\u003e initializing segments\nSegment(p1=(-1.000000, 0.000000), p2=(1.000000, 0.000000))\nSegment(p1=(0.000000, -1.000000), p2=(0.000000, 1.000000))\n\u003e\u003e\u003e casting to Line\nLine(p=-0.000000, q=2.000000, r=0.000000)\nLine(p=-2.000000, q=0.000000, r=-0.000000)\n\u003e\u003e\u003e testing coefs\nOK\n\u003e\u003e\u003e intersecting\ncollision at [ParamPair(t1=0.500000, t2=0.500000)]\nto points (0.000000, 0.000000) (0.000000, 0.000000)\nOK\n```\n\n```sh\n$ python test_world.py\n\u003e\u003e\u003e initial world\nBalls:\n\tBall(pos=(-1.000000, 1.000000), vel=(2.000000, 1.000000))\n\tBall(pos=(0.000000, 1.000000), vel=(2.000000, 1.000000))\nCurves:\n\tSegment(p1=(2.000000, 1.000000), p2=(2.000000, 4.000000))\n\tSegment(p1=(1.000000, 2.000000), p2=(4.000000, 2.000000))\n\u003e\u003e\u003e stepping\nBalls:\n\tBall(pos=(-15.000000, -7.000000), vel=(-2.000000, -1.000000))\n\tBall(pos=(-16.000000, -7.000000), vel=(-2.000000, -1.000000))\nCurves:\n\tSegment(p1=(2.000000, 1.000000), p2=(2.000000, 4.000000))\n\tSegment(p1=(1.000000, 2.000000), p2=(4.000000, 2.000000))\nOK\n```\n\n## TODO\n\n- bugfixes\n  - [ ] fix collisions with BezierCurve (probably a problem with the third degree polynomial root solver)\n- code improvements\n  - [ ] put the physics in a namespace\n  - [ ] move json out of physics library (serializer class)\n  - [ ] build the python bindings with cmake\n- features\n  - [ ] ellipse implementation\n  - [ ] python world generator\n  - [ ] python level editor\n  - [ ] trajectory heatmap\n  - [ ] maze world https://twitter.com/matthen2/status/1440443280827699206?s=1","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninivert%2Fchaotic-billiard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fninivert%2Fchaotic-billiard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fninivert%2Fchaotic-billiard/lists"}