Metadata-Version: 2.4
Name: ballistic-solver
Version: 1.3.0
Summary: Numerical launch-angle solver for moving targets under gravity and quadratic drag.
Keywords: ballistics,ballistic-solver,intercept,interception,moving-target,launch-angle,trajectory,projectile,numerical-methods,ode-solver,broyden-method,physics,simulation,game-development,robotics
Author-Email: Ujin Kwon <ujin@tukorea.ac.kr>
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Project-URL: Homepage, https://github.com/ujinf74/ballistic-solver
Project-URL: Repository, https://github.com/ujinf74/ballistic-solver
Project-URL: Documentation, https://github.com/ujinf74/ballistic-solver#readme
Project-URL: Changelog, https://github.com/ujinf74/ballistic-solver/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ujinf74/ballistic-solver/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ballistic-solver

[![PyPI](https://img.shields.io/pypi/v/ballistic-solver)](https://pypi.org/project/ballistic-solver/)
[![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)

Given a moving target, a muzzle speed and a drag coefficient, this returns the
launch angles that hit it. It integrates the projectile and solves the intercept
numerically, so it stays accurate where closed-form vacuum formulas drift: strong
drag, high arcs, wind, and targets that keep moving while the round is in flight.

The core is C++17 with a stable C ABI; this package is its native Python
extension, not a pure-Python reimplementation.

## Install

```bash
pip install ballistic-solver
```

Wheels cover CPython 3.9-3.15 on Linux (`x86_64`, `aarch64`; manylinux and
musllinux), macOS (`universal2`) and Windows (`AMD64`, `ARM64`). The
free-threaded `3.14t` and `3.15t` builds are covered on Linux and macOS. Other
combinations build from the sdist, which needs CMake and a C++17 compiler.

## Use

```python
import ballistic_solver as bs

result = bs.solve(
    relPos0=(120, 30, 5),    # target position relative to the muzzle, metres
    relVel=(2, -1, 0),       # target velocity, m/s
    v0=90,                   # muzzle speed, m/s
    kDrag=0.002,             # quadratic drag coefficient
)

print(result["success"], result["theta"], result["phi"])
```

`theta` and `phi` are elevation and azimuth in radians. `miss` is the
closest-approach distance and `tStar` the time it occurs; `success` reports
whether the miss landed inside the tolerance. A best-effort answer comes back
even when it does not, so an unreachable target degrades rather than throws.

Derive the drag coefficient from physical quantities if you have them:

```python
kDrag = bs.k_drag_from_physical(
    airDensity=1.225, dragCoefficient=0.30, area=0.00426, mass=0.145,
)
```

Three presets trade speed against tolerance — `bs.params_preset("fast")`,
`"balanced"`, `"precise"` — and `bs.solve_accel` accepts a constant target
acceleration. For a noisy position-only feed, `bs.TargetTracker` denoises the
track and fires through the same solver without you supplying velocity.

## Scope

A point-mass model: quadratic drag with a single coefficient, constant gravity,
uniform wind. No spin drift or Magnus effect, no Mach-dependent drag table, no
terrain collision. It solves launch angles only — muzzle speed and arc branch
are inputs. Intended for games, simulation, robotics and research; it is not a
certified fire-control system.

## Documentation

The full API reference, the C ABI, the C++ surface, the Unity and Godot
bindings, benchmarks and the numerical method all live in the repository:

**https://github.com/ujinf74/ballistic-solver**

- [Numerical method](https://github.com/ujinf74/ballistic-solver/blob/main/docs/numerical_method.md)
- [Benchmarks](https://github.com/ujinf74/ballistic-solver/blob/main/docs/benchmarks.md)
- [Limitations](https://github.com/ujinf74/ballistic-solver/blob/main/docs/limitations.md)
- [Changelog](https://github.com/ujinf74/ballistic-solver/blob/main/CHANGELOG.md)

## License

MIT
