Ballistics Engine

A high-performance ballistics trajectory calculation engine with comprehensive physics modeling, automatic zeroing, and statistical analysis capabilities.

Project Website: https://ballistics.rs/

Features

• Full 3D Trajectory Integration - Six-state ballistic modeling with adaptive RK45 and fixed-step RK4 integration methods
• Advanced Drag Models - Support for G1, G7, and custom drag curves with automatic transonic corrections
• Automatic Zeroing - Calculate sight adjustments and apply zero angles automatically
• Unit Conversion - Seamless switching between Imperial (default) and Metric units
• BC Segmentation - Velocity-dependent ballistic coefficient modeling with automatic estimation
• Atmospheric Modeling - Temperature, pressure, humidity, and altitude effects with ICAO standard atmosphere
• Wind Effects - 3D wind calculations with altitude-dependent wind shear modeling and downrange-segmented wind (--wind-segment SPEED:ANGLE:DIST, repeatable — model wind that varies along the path, e.g. muzzle plus downrange sensor readings)
• Monte Carlo Simulations - Statistical analysis with parameter uncertainties
• BC Estimation - Estimate ballistic coefficients from trajectory data
• Advanced Physics:
• Spin Effects: Magnus effect, enhanced spin drift with decay modeling
• Earth Effects: Coriolis effect with latitude-dependent calculations
• Angular Motion: Gyroscopic precession and nutation physics
• Transonic Analysis: Pitch damping coefficients and stability warnings
• Trajectory Sampling: Regular interval data collection for analysis
• Form Factor Corrections: Bullet-specific drag adjustments
• Multiple Output Formats - JSON, CSV, formatted tables, and printable PDF dope cards

Installation

From crates.io

cargo install ballistics-engine

From Source

git clone https://github.com/ajokela/ballistics-engine.git
cd ballistics-engine
cargo build --release

The binary will be at: target/release/ballistics

Feature Flags

Feature	Default	Description
online	✅ Yes	HTTP client for API integration (--online flag)

To build without network capabilities:

cargo build --release --no-default-features

Quick Start

Basic Trajectory (Imperial Units - Default)

# .308 Winchester, 168gr bullet at 2700 fps
./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --max-range 1000

# With automatic zeroing at 200 yards
./ballistics trajectory -v 2700 -b 0.475 -m 168 -d 0.308 --auto-zero 200 --max-range 500

Metric Units

# Same bullet in metric units
./ballistics trajectory --units metric -v 823 -b 0.475 -m 10.9 -d 7.82 --max-range 1000

Unit Systems

The engine supports two unit systems, selectable with the --units flag:

Imperial (Default)

• Velocity: feet per second (fps)
• Mass: grains
• Distance: yards
• Diameter: inches
• Temperature: Fahrenheit
• Pressure: inHg
• Wind: mph

Metric

• Velocity: meters per second (m/s)
• Mass: grams
• Distance: meters
• Diameter: millimeters
• Temperature: Celsius
• Pressure: hPa (millibars)
• Wind: m/s

Commands

Trajectory Calculation

Calculate ballistic trajectory with environmental conditions:

# Imperial units (default)
./ballistics trajectory \
  -v 2700          # Velocity (fps)
  -b 0.475         # Ballistic coefficient
  -m 168           # Mass (grains)
  -d 0.308         # Diameter (inches)
  --drag-model g7  # G7 drag model
  --angle 0        # Launch angle (degrees)
  --max-range 1000 # Maximum range (yards)
  --wind-speed 10  # Wind speed (mph)
  --wind-direction 90  # Wind from right (degrees)
  --temperature 59     # Temperature (Fahrenheit)
  --pressure 29.92    # Pressure (inHg)
  --humidity 50       # Relative humidity (%)
  --altitude 0        # Altitude (feet)
  --full             # Show all trajectory points

Auto-Zero Feature

Automatically calculate and apply the zero angle for a specific distance:

# Zero at 200 yards and show trajectory to 500 yards
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --auto-zero 200 \  # Automatically zero at 200 yards
  --max-range 500 \
  --full

# Custom sight height for auto-zero
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --auto-zero 100 \
  --sight-height 0.055  # 2.2 inches in yards

Zero-Day Conditions (zero shift)

A rifle's zero is a fixed barrel angle set on the day you sighted in. If you later shoot in different weather — or with a different muzzle velocity (e.g. a cold vs. warm powder temperature) — the point of impact shifts. By default --auto-zero solves the zero angle using the same conditions you pass for the shot, which assumes you zeroed in today's conditions. The --zero-* flags let you decouple the two: the zero angle is solved under the conditions the rifle was actually zeroed in, while the trajectory itself runs under the current shot-day conditions.

# Zeroed on a cold morning (28 F) at 2600 fps; shooting this afternoon at 85 F / 2700 fps.
# The zero angle is solved for the cold/slow load, then the warm/fast trajectory is
# computed against it — so the dope correctly shows the point of impact drifting high.
./ballistics trajectory \
  -v 2700 -b 0.19 -m 77 -d 0.224 --drag-model g7 \
  --temperature 85 --pressure 29.92 \
  --auto-zero 100 --max-range 1000 --full \
  --zero-velocity 2600 \
  --zero-temperature 28

Available overrides (each independently optional; any omitted flag falls back to the shot-day value, so leaving them all off reproduces the previous behavior exactly):

Flag	Meaning	Units (imperial / metric)
--zero-velocity	Muzzle velocity on the zeroing day	fps / m·s⁻¹
--zero-temperature	Air temperature on the zeroing day	°F / °C
--zero-pressure	Barometric pressure on the zeroing day	inHg / hPa
--zero-humidity	Relative humidity on the zeroing day	percent
--zero-altitude	Altitude on the zeroing day	feet / meters

Powder Temperature

Propellant temperature changes muzzle velocity. Two models are available:

Linear — a constant sensitivity (fps or m/s per degree) applied relative to the temperature the load was chronographed at:

./ballistics trajectory -v 2700 -b 0.19 -m 77 -d 0.224 --drag-model g7 \
  --temperature 85 --use-powder-sensitivity \
  --powder-temp-sensitivity 1.2 --powder-temp 70   # +1.2 fps per F above 70 F

Measured curve (non-linear) — real powders aren't perfectly linear (temperature- stable powders flatten; others steepen when hot). If you've chronographed the load at several temperatures, pass the points directly and the muzzle velocity is interpolated at the powder temperature (clamped at the endpoints — no extrapolation). This overrides --powder-temp-sensitivity when supplied:

./ballistics trajectory -v 2700 -b 0.19 -m 77 -d 0.224 --drag-model g7 \
  --temperature 85 \
  --powder-temp-curve "40:2620,70:2700,100:2760"   # TEMP:VELOCITY points

Powder temperature vs air temperature. The curve maps powder temperature to velocity, while --temperature drives air density. These are decoupled: the curve is looked up at --powder-temp when given, otherwise at --temperature (powder assumed at air temperature). So a load left in a hot chamber or a cold pocket:

# 85 F air (density), but the powder is at 60 F (velocity from the curve at 60 F)
./ballistics trajectory ... --temperature 85 --powder-temp 60 \
  --powder-temp-curve "40:2620,70:2700,100:2760"

The curve also composes with --auto-zero, symmetrically. On the zeroing day the zero velocity is resolved from the curve at --zero-powder-temp (or --zero-temperature if unset), while --zero-temperature/--zero-pressure/etc. drive the zero-day air density. An explicit --zero-velocity still takes precedence over the curve.

Bore Height and Ground Impact

Control bore height above ground and ground impact detection:

# Set bore height for prone shooting position (2 feet)
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --auto-zero 100 \
  --bore-height 2  # 2 feet (imperial) or meters (metric)

# Disable ground impact detection for full trajectory to max range
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --auto-zero 100 \
  --max-range 1000 \
  --ignore-ground-impact

Bore height defaults: 5 feet (imperial) / 1.5 meters (metric) - standing position.

Advanced BC Modeling

Enable velocity-dependent BC modeling for more accurate long-range predictions:

# Enable BC segmentation (velocity-based BC changes)
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --use-bc-segments \
  --auto-zero 600 \
  --max-range 1000

Advanced Physics - Magnus and Spin Drift

Enable advanced gyroscopic and aerodynamic effects:

# Magnus effect and spin drift calculation
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --twist-rate 10      # 1:10" barrel twist
  --twist-right        # Right-hand twist
  --enable-magnus      # Enable Magnus effect
  --enable-spin-drift  # Enable enhanced spin drift
  --wind-speed 10 \
  --wind-direction 90 \
  --max-range 1000

# Coriolis effect for extreme long range
./ballistics trajectory \
  -v 3000 -b 0.750 -m 250 -d 0.338 \
  --enable-coriolis \
  --latitude 45        # Shooting latitude
  --shooting-angle 90  # Azimuth (0=N, 90=E)
  --max-range 2000

Zero Calculation

Calculate the sight adjustment needed to zero at a specific distance:

# Calculate zero for 200 yards
./ballistics zero \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --target-distance 200

# With custom sight height (default is 0.05 yards / 1.8 inches)
./ballistics zero \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --target-distance 300 \
  --sight-height 0.055  # 2.2 inches

# Metric example
./ballistics zero --units metric \
  -v 823 -b 0.475 -m 10.9 -d 7.82 \
  --target-distance 200  # 200 meters

Output includes: - Zero angle in degrees - Adjustment in MOA (Minutes of Angle) - Adjustment in mrad (milliradians) - Maximum ordinate (highest point of trajectory)

Monte Carlo Simulation

Run statistical analysis with parameter variations:

./ballistics monte-carlo \
  -v 2700         # Base velocity (fps)
  -b 0.475        # Base BC
  -m 168          # Mass (grains)
  -d 0.308        # Diameter (inches)
  -n 1000         # Number of simulations
  --velocity-std 10    # Velocity std dev (fps)
  --angle-std 0.5     # Angle std dev (degrees)
  --bc-std 0.01       # BC std dev
  --wind-std 2        # Wind speed std dev (mph)
  --target-distance 300  # Target distance for hit probability

BC Estimation

Estimate ballistic coefficient from observed trajectory data:

./ballistics estimate-bc \
  -v 2700 -m 168 -d 0.308 \
  --distance1 100 --drop1 0.0   # First data point
  --distance2 200 --drop2 0.023  # Second data point

True Velocity (Velocity Truing)

Calculate the effective muzzle velocity that produces a measured drop at a known range. This helps "true" your ballistic system by identifying discrepancies between chronograph readings and real-world performance.

# Basic offline calculation
./ballistics true-velocity \
  --measured-drop 5.1 --range 600 \
  --bc 0.27 --drag-model g7 \
  --mass 140 --diameter 0.264 \
  --offline

# With chronograph comparison
./ballistics true-velocity \
  --measured-drop 5.1 --range 600 \
  --bc 0.27 --drag-model g7 \
  --mass 140 --diameter 0.264 \
  --chrono-velocity 2822 \
  --offline

# With BC5D tables for improved accuracy
./ballistics true-velocity \
  --measured-drop 5.1 --range 600 \
  --bc 0.27 --drag-model g7 \
  --mass 140 --diameter 0.264 \
  --bc-table-auto --offline

Use case: A shooter measures 5.1 MIL of drop at 600 yards. Their chronograph showed 2822 fps. The command calculates the effective velocity is actually ~2740 fps, suggesting a -82 fps adjustment for accurate ballistic predictions.

Advanced Features

Online Mode (API Integration)

The CLI can query a remote ballistics API server instead of calculating locally. This enables access to enhanced BC data, ML-augmented predictions, and doppler-derived drag curves.

Important: The --online feature connects to a proprietary cloud service that is not covered by the MIT license. When using --online, trajectory parameters and your IP address are transmitted to our servers. See ONLINE_SERVICE.md for full terms, privacy policy, and data handling practices.

# Use online mode to query the API
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --online \
  --max-range 1000

# Custom API endpoint
./ballistics trajectory \
  -v 2700 -b 0.475 -m 168 -d 0.308 \
  --online \
  --api-url https://your-api.example.com/v1/calculate \
  --max-range 1000

Default API: https://api.ballistics.7.62x51mm.sh/v1/calculate

Online mode benefits: - Enhanced BC data - Access to doppler-derived ballistic coefficients - ML predictions - Machine learning augmented trajectory calculations - BC segments - Velocity-dependent BC modeling from measured data - Form factor corrections - Bullet-specific drag adjustments

Data transmitted when using --online: - All trajectory parameters (BC, mass, velocity, wind, atmospheric conditions, etc.) - Your IP address and client version - Request logs retained for 30 days, then deleted

To use only local calculations (no network, no data transmission):

cargo install ballistics-engine --no-default-features

Integration Methods

The engine supports two numerical integration methods:

• **RK