{"id":37228065,"url":"https://github.com/ujinf74/ballistic-solver","last_synced_at":"2026-01-17T02:53:06.398Z","repository":{"id":332197857,"uuid":"1131259618","full_name":"ujinf74/ballistic-solver","owner":"ujinf74","description":"Native C/C++ numerical launch-angle solver for moving targets under quadratic air drag","archived":false,"fork":false,"pushed_at":"2026-01-12T21:15:28.000Z","size":6660,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T01:17:40.478Z","etag":null,"topics":["ballistic-solver","ballistics","broyden-method","c-abi","cpp","ffe","game-development","header-only","mechanics","numerical-methods","ode","ode-solver","optimization","physics","projectile","rk4","simulation","trajectory","unity","unity3d"],"latest_commit_sha":null,"homepage":"","language":"C++","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/ujinf74.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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T18:03:58.000Z","updated_at":"2026-01-12T21:15:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ujinf74/ballistic-solver","commit_stats":null,"previous_names":["ujinf74/ballistic-solver"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/ujinf74/ballistic-solver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujinf74%2Fballistic-solver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujinf74%2Fballistic-solver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujinf74%2Fballistic-solver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujinf74%2Fballistic-solver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ujinf74","download_url":"https://codeload.github.com/ujinf74/ballistic-solver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ujinf74%2Fballistic-solver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ballistic-solver","ballistics","broyden-method","c-abi","cpp","ffe","game-development","header-only","mechanics","numerical-methods","ode","ode-solver","optimization","physics","projectile","rk4","simulation","trajectory","unity","unity3d"],"created_at":"2026-01-15T03:25:44.511Z","updated_at":"2026-01-15T03:25:45.010Z","avatar_url":"https://github.com/ujinf74.png","language":"C++","readme":"\u003cimg width=\"2024\" height=\"512\" alt=\"banner\" src=\"https://github.com/user-attachments/assets/f4e57e3f-f584-4938-a321-e9dd83dbbac3\" /\u003e\n\n[![CI](https://github.com/ujinf74/ballistic-solver/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ujinf74/ballistic-solver/actions/workflows/ci.yml)\n[![Release Native + PyPI](https://github.com/ujinf74/ballistic-solver/actions/workflows/release.yml/badge.svg)](https://github.com/ujinf74/ballistic-solver/actions/workflows/release.yml)\n[![CodeQL Advanced](https://github.com/ujinf74/ballistic-solver/actions/workflows/codeql.yml/badge.svg)](https://github.com/ujinf74/ballistic-solver/actions/workflows/codeql.yml)\n[![PyPI](https://img.shields.io/pypi/v/ballistic-solver)](https://pypi.org/project/ballistic-solver/)\n\n**ballistic-solver** is a native C/C++ numerical solver that computes launch angles to intercept **moving targets** under **gravity** and **quadratic air drag**, with optional **wind**.\n\nUnlike vacuum / closed-form solvers, this project **simulates the projectile** and **solves the intercept numerically**, aiming for robust real-time use even when trajectories are strongly curved.\n\n---\n\n## Quick start\n\n### Python (PyPI)\n\n```bash\npip install ballistic-solver\n````\n\nRequires Python **\u003e= 3.10**.\n\n```python\nimport ballistic_solver as bs\n\nresult = bs.solve(\n    relPos0=(120, 30, 5),\n    relVel=(2, -1, 0),\n    v0=90,\n    kDrag=0.002,\n)\n\nprint(result[\"theta\"], result[\"phi\"], result[\"miss\"])\nprint(result[\"success\"], result[\"status\"], result[\"message\"])\n```\n\n---\n\n## Demo (Unity)\n\nHighly curved trajectories under strong air drag, still converging to a hit against moving targets.\n\nhttps://github.com/user-attachments/assets/c0c69cdd-0dd4-4606-9c7d-f21dd002d7f7\n\n---\n\n## Why this solver\n\nMany launch-angle solvers depend on vacuum assumptions or partially linearized models.\nThis project instead **simulates the projectile** and **solves the intercept numerically**, targeting robustness in real-time simulations and integration scenarios.\n\n---\n\n## Key properties\n\n* Moving targets supported\n* Strong air resistance (quadratic drag) supported\n* Low / High arc selection (since v0.2)\n* Wind vector supported (since v0.3)\n* Robust in strongly nonlinear regimes (no analytic assumptions)\n* Best-effort result returned even without perfect convergence\n* Explicit success / failure reporting (+ diagnostic message)\n* Stable C ABI for multi-language use\n* Header-only C++ core\n* Easy install via PyPI: `pip install ballistic-solver`\n\n---\n\n## Python API\n\n### `solve(...)`\n\n```python\nsolve(relPos0, relVel, v0, kDrag, arcMode=0, params=None) -\u003e dict\n```\n\n* `relPos0`: target relative position at t=0 (x,y,z)\n* `relVel`: target relative velocity (x,y,z)\n* `v0`: muzzle speed (scalar)\n* `kDrag`: quadratic drag coefficient\n* `arcMode`: `0/1` or `\"low\"/\"high\"` (case-insensitive)\n* `params`: optional `BallisticParams` for advanced tuning (gravity, wind, integrator and solver knobs)\n\nReturned dict keys include:\n\n* `success` (bool)\n* `theta`, `phi` (radians)\n* `miss` (closest-approach distance)\n* `tStar` (time of closest approach)\n* `relMissAtStar` (3-vector miss at `tStar`)\n* `status` (SolveStatus integer)\n* `message` (short diagnostic string)\n* plus convergence diagnostics (`iterations`, `acceptedSteps`, `lastLambda`, `lastAlpha`)\n\n### Advanced tuning: `BallisticParams`\n\nExample (wind + high arc):\n\n```python\nimport ballistic_solver as bs\n\np = bs.BallisticParams()\np.g = 9.80665                # gravity\np.wind = (3.0, 0.0, 0.0)     # wind vector\np.dt = 0.01                  # RK4 step\np.tMax = 20.0                # max sim time\np.tolMiss = 1e-2             # hit tolerance\np.maxIter = 20               # LM iterations\n\nresult = bs.solve(\n    relPos0=(120, 30, 5),\n    relVel=(2, -1, 0),\n    v0=90,\n    kDrag=0.002,\n    arcMode=\"high\",\n    params=p,\n)\nprint(result[\"theta\"], result[\"phi\"], result[\"miss\"])\n```\n\n---\n\n## Arc mode (since v0.2)\n\nC ABI convention:\n\n* `arcMode = 0` → Low\n* `arcMode = 1` → High\n\nHigh arc example:\n\nhttps://github.com/user-attachments/assets/4334ed87-597e-4ad4-b21e-c1a1a17e8cd8\n\n---\n\n## Wind (since v0.3)\n\nC ABI convention:\n\n- `wind[3]` = air velocity vector (same frame as `relPos0/relVel`)\n- Drag uses relative airspeed: `v_rel = v_projectile - wind`\n\nWind demo:\n\nhttps://github.com/user-attachments/assets/1cd998cf-34db-4a74-8817-c6393227ef4e\n\n---\n\n## C ABI (stable interface)\n\n```c\nvoid ballistic_inputs_init(BallisticInputs* in);\nint32_t ballistic_solve(const BallisticInputs* in, BallisticOutputs* out);\n```\n\nSee `ballistic_solver_c_api.h` for `BallisticInputs/Outputs` definitions and defaults.\n\nThis enables usage from:\n\n* C / C++\n* Python (ctypes via the C ABI)\n* C# / .NET / Unity (P/Invoke)\n* Others via FFI\n\nPrebuilt native binaries are provided via GitHub Releases.\n\n---\n\n## Using prebuilt binaries (C ABI)\n\nDownload the archive for your platform from **Releases**.\n\nEach release contains:\n\n* Shared library\n\n  * Windows: `ballistic_solver.dll`\n  * Linux: `libballistic_solver.so`\n  * macOS: `libballistic_solver.dylib`\n* C ABI header: `ballistic_solver_c_api.h`\n\n---\n\n## C# / Unity usage\n\nA C# P/Invoke example is available in:\n\n```text\nexamples/dotnet/\n```\n\nOn Windows, place `ballistic_solver.dll` next to the executable\n(or ensure it is discoverable via PATH),\nthen call `ballistic_solve` via `DllImport`.\n\nThis works directly inside Unity.\n\n---\n\n## How it works (high level)\n\n1. Simulate projectile motion using RK4 integration with drag (+ wind)\n2. Track the closest approach between projectile and target\n3. Express the miss at closest approach as an angular residual\n4. Solve the nonlinear system using damped least squares (Levenberg–Marquardt)\n5. Accelerate Jacobian updates with Broyden-style refinement\n6. Return the best solution found\n\nFailure cases are explicitly detected and reported.\n\n---\n\n## Status codes (SolveStatus)\n\n`BallisticOutputs.status` / Python `result[\"status\"]` corresponds to:\n\n* `0` = Ok\n* `1` = InvalidInput\n* `2` = InitialResidualFailed\n* `3` = JacobianFailed\n* `4` = LMStepSingular\n* `5` = ResidualFailedDuringSearch\n* `6` = LineSearchRejected\n* `7` = LambdaTriesExhausted\n* `8` = MaxIterReached\n\n`message` contains a short diagnostic string.\n\n---\n\n## Build from source\n\n```bash\ncmake -S . -B build\ncmake --build build -j\nctest --test-dir build\n```\n\nThe shared library target is `ballistic_solver`.\n\n---\n\n## ABI notes\n\n* Plain C layout across the ABI boundary\n* Fixed-size arrays only\n* No dynamic allocation across the boundary\n\n---\n\n## License\n\nMIT License\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fujinf74%2Fballistic-solver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fujinf74%2Fballistic-solver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fujinf74%2Fballistic-solver/lists"}