ballistics-engine 0.26.0 → 0.30.0

package/README.md

@@ -7,14 +7,16 @@ A high-performance ballistics trajectory calculation engine with comprehensive p
 ## Features
 
 - **Full 3D Trajectory Integration** - Six-state ballistic modeling with adaptive RK45 and fixed-step RK4 integration methods
-- **Advanced Drag Models** - Support for G1 and G7 reference curves (with automatic transonic corrections) plus user-supplied custom Cd(Mach) drag tables (`--drag-table`, used as-is with endpoint hold outside their measured domain, no transonic correction applied — see [CLI_USAGE.md](CLI_USAGE.md#custom-drag-tables); `bc_value` is ignored while a custom table is active)
-- **Automatic Zeroing** - Calculate sight adjustments and apply zero angles automatically
+- **Advanced Drag Models** - Full standard-projectile family (G1, G2, G5, G6, G7, G8, GI, GS, and the British RA4 reference function), each backed by its own real Mach-indexed table with automatic transonic corrections, plus user-supplied custom Cd(Mach) drag tables (`--drag-table`, used as-is with endpoint hold outside their measured domain, no transonic correction applied — see [CLI_USAGE.md](CLI_USAGE.md#custom-drag-tables); `bc_value` is ignored while a custom table is active), with an optional `--cd-scale <FACTOR>` whole-curve truing multiplier (Hornady AFF / AB CDF style; `1.0` = neutral, typical range 0.90-1.10; requires `--drag-table` — see [CLI_USAGE.md](CLI_USAGE.md#whole-curve-drag-scale---cd-scale)). `true-velocity`/`plan-truing`'s forward model is deliberately G1/G7 only. GL is out of scope — its only public source is velocity-domain data, which doesn't fit this engine's Mach-indexed table format.
+- **Automatic Zeroing** - Calculate sight adjustments and apply zero angles automatically; `trajectory` echoes the solved bore angle (degrees, additive across table/JSON/CSV) whenever auto-zero ran, and `zero --from-angle <DEGREES>` solves the zero RANGE(S) a previously solved/stored bore angle produces — a bore angle generally implies two zeros (the classic 25/300-yard relationship), so both are reported rather than one being silently picked — so the angle can be captured once and reused later, independent of the day it was solved — see [CLI_USAGE.md](CLI_USAGE.md#solving-range-from-a-stored-angle---from-angle)
 - **Canted-Rifle Modeling** - Model a rifle zeroed level but fired canted (`--cant <DEGREES>`, alias `--cant-angle`, on `trajectory`/`monte-carlo`); clockwise cant shifts point of impact right and low downrange for a rifle with an upward zero correction — see [CLI_USAGE.md](CLI_USAGE.md#canted-shooting)
 - **Moving-Target Lead** - Wind-aware hold tables for targets moving at a constant speed/angle, with iterative intercept-range correction for non-perpendicular motion (`lead` subcommand; public `ballistics_engine::calculate_lead` API) — see [CLI_USAGE.md](CLI_USAGE.md#moving-target-lead)
 - **Mover Ring** - Field-tested alternative for engaging movers: a per-point ring radius (`target_speed × time-of-flight`) falls out of an already-solved trajectory with no second command or re-entered ballistic data (`trajectory --target-speed`, additive across table/JSON/CSV output); `lead` also gained `trajectory`'s powder-temperature flags for muzzle-velocity parity between the two — see [CLI_USAGE.md](CLI_USAGE.md#mover-ring---target-speed)
+- **Side-by-Side Load Comparison** - Compare 2-8 loads at identical conditions with per-load independent zeroing (`compare --load "NAME:DRAG:BC:MASS:VELOCITY[:DIAMETER]"`, mixable with saved profiles); JSON/CSV output carries per-row deltas against the first load — see [CLI_USAGE.md](CLI_USAGE.md#load-comparison-compare)
+- **Powder Temperature Command** - Resolve the temperature-adjusted muzzle velocity standalone, without a trajectory solve (`powder` subcommand): linear fps-per-degree model or a measured temperature→velocity curve, optional `--sweep` velocity ladder and muzzle energy; shares the solvers' exact resolution code (public `resolve_powder_adjusted_velocity` API) — see [CLI_USAGE.md](CLI_USAGE.md#powder-temperature-velocity-powder)
 - **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
+- **Atmospheric Modeling** - Temperature, pressure, humidity, and altitude effects with ICAO standard atmosphere; also accepts a single **density altitude** reading (`trajectory --density-altitude`, feet imperial / meters metric) as a direct alternative to entering altitude/pressure/temperature separately — back-solves an ISA-equivalent atmosphere (preserving Mach/lapse-rate/segmented-atmosphere behavior, not a density-only shortcut) and supersedes `--altitude`/`--pressure`/`--pressure-type` entirely, with an explicit `--temperature` still honored for correct powder-temperature sensitivity — see [CLI_USAGE.md](CLI_USAGE.md#density-altitude-as-a-direct-input---density-altitude)
 - **Wind Effects** - 3D wind calculations with altitude-dependent wind shear modeling, **downrange-segmented wind** (`--wind-segment SPEED:ANGLE:DIST[:VERTICAL]`, repeatable — model wind that varies along the path, e.g. muzzle plus downrange sensor readings), and **vertical wind** (`--wind-vertical <SPEED>` on `trajectory`/`monte-carlo`, or the segment's optional 4th field; positive = updraft, raises point of impact) — see [CLI_USAGE.md](CLI_USAGE.md#vertical-wind)
 - **Oblique Wind-Drift Cards** - Wind dope cards at any wind-FROM angle, not just full-value 90° crosswind (`wind-card --wind-angle <DEG>` or `--wind-angles <CSV>` for one card per angle); each cell is a real trajectory solve, default (no flags) unchanged from the classic full-value 90° card — see [CLI_USAGE.md](CLI_USAGE.md#wind-card)
 - **Monte Carlo Simulations** - Statistical analysis with parameter uncertainties
@@ -27,7 +29,7 @@ A high-performance ballistics trajectory calculation engine with comprehensive p
   - **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
-- **Terminal Chart** - Inline drop-vs-range and drift-vs-range charts right in the terminal (`trajectory --plot`, Unicode braille-dot canvas by default, `--plot ascii` fallback); pure Rust, zero new dependencies, no ANSI colors — see [CLI_USAGE.md](CLI_USAGE.md#terminal-chart---plot)
+- **Terminal Chart** - Inline drop, drift, velocity, and energy vs. range charts right in the terminal (`trajectory --plot`, Unicode braille-dot canvas by default, `--plot ascii` fallback); pure Rust, zero new dependencies, no ANSI colors — see [CLI_USAGE.md](CLI_USAGE.md#terminal-chart---plot)
 - **Profile import**: `ballistics profile import file.a7p` — imports ArcherBC2 `.a7p` profiles (rifle, bullet, atmosphere, zero) with a full mapping report; `--dry-run` previews without saving
 
 ## Installation
@@ -357,6 +359,16 @@ Calculate the effective muzzle velocity that produces a measured drop at a known
   --chrono-velocity 2822 \
   --offline
 
+# Chronograph measured downrange, not at the muzzle (MBA-1377): most
+# chronographs read 10-15 ft (or 25 m) downrange, so --chrono-distance
+# back-solves the true muzzle velocity from the raw reading
+./ballistics true-velocity \
+  --measured-drop 5.1 --range 600 \
+  --bc 0.27 --drag-model g7 \
+  --mass 140 --diameter 0.264 \
+  --chrono-velocity 2822 --chrono-distance 15 \
+  --offline
+
 # With BC5D tables for improved accuracy
 ./ballistics true-velocity \
   --measured-drop 5.1 --range 600 \
@@ -374,8 +386,87 @@ Calculate the effective muzzle velocity that produces a measured drop at a known
 
 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.
 
+**Downrange chronograph correction (MBA-1377).** Most chronographs (and radar units) read some distance downrange rather than at the muzzle — 10-15 ft is typical for optical screens, 25 m for Lapua/JBM's reference distance — so the raw reading is a few fps low. `--chrono-distance` back-solves the true muzzle velocity from that reading via secant iteration on the same forward drag model (BC/`--drag-model`/atmosphere) the rest of the command uses; zero or absent is an exact no-op. It's a pure display-side correction (`--chrono-velocity` never feeds the drop-based solve either way) and validates its input to a sane 1-98 ft / 0.3-30 m band (100 ft is out of range) rather than silently extrapolating a bad distance into a bad velocity.
+
 **Joint velocity + BC truing.** With two or more `--observed RANGE:DROP` impacts spanning supersonic to transonic ranges, `true-velocity` fits *both* muzzle velocity and ballistic coefficient against the real trajectory solver. When the observation set is too short/closely-spaced to separate the two, it refuses the joint fit, trues velocity only, and says so — no false-precision BC. See [CLI_USAGE.md](CLI_USAGE.md#joint-mv--bc-calibration-multiple-observed-impacts) for details.
 
+**Plan the observations before shooting (MBA-1346).** `plan-truing` evaluates a
+discrete set of ranges with the same forward model and finite-difference Jacobian
+used by the fitter, then chooses an exact-size, minimum-separation-compliant design.
+It reports information gain, singular values, conditioning, rejected/unreachable
+candidates, and an explicit MV-only recommendation when the available facility
+cannot identify BC:
+
+```bash
+./ballistics plan-truing \
+  -v 2700 -b 0.475 --drag-model g1 -m 168 -d 0.308 \
+  --candidate-ranges 200,300,400,500,600,700,800,900 \
+  --observation-count 3 --minimum-separation 100 \
+  --measurement-resolution 0.03 --drop-unit mil
+```
+
+`--measurement-resolution` is the assumed independent **one-standard-deviation**
+impact-reading error, not a tolerance or extreme bound. A saved scalar G1/G7
+profile may replace the explicit load flags (`--profile NAME`); velocity-banded BC
+profiles and custom drag curves are rejected because they do not have one scalar BC
+parameter to identify.
+
+**Quantify what the observations actually learned (MBA-1353).** Add
+`--observation-sigma` to opt into a weighted joint MV/BC MAP fit and local Gaussian
+uncertainty report. A third `--observed RANGE:DROP:SIGMA` field overrides the default
+for one reading. Optional priors are always visible and explicit; predictive output
+separates uncertainty in the modeled drop from the wider interval for a future
+reading:
+
+```bash
+./ballistics true-velocity \
+  --range 500 --measured-drop 3.18 \
+  --observed 600:4.35:0.03 --observed 900:8.89:0.02 \
+  --observation-sigma 0.03 \
+  --bc 0.45 --drag-model g1 --mass 168 --diameter 0.308 \
+  --predict-range 1000 --prediction-sigma 0.03 --output json
+```
+
+The report includes MV/BC 95% intervals, covariance and correlation, chi-square,
+effective degrees of freedom, prior-domination/weak-identification warnings, and
+propagated drop bands. Declared sigmas are treated as absolute known errors, so the
+covariance is not rescaled by residual RMS. With no uncertainty flags, the existing
+point estimate and output schema are unchanged.
+
+### DSF (Drop-Scale-Factor) Truing
+
+Second stage of the Applied Ballistics-style two-stage truing workflow (MBA-1357).
+Once `true-velocity` has fixed the supersonic (Mach > 1.2) muzzle velocity/BC, the
+drop discrepancies that grow through the transonic region and into subsonic flight are
+no longer fixable by a single MV correction — the residual is a slowly-varying function
+of Mach. `dsf` records observed-drop/predicted-drop ratios at specific Mach <= 1.2
+ranges and keys them, one saved profile at a time, to a Mach-indexed table:
+
+```bash
+# Stage 1: true the muzzle velocity from a supersonic-range drop reading (as above).
+./ballistics true-velocity \
+  --measured-drop 3.2 --range 500 \
+  --bc 0.475 --mass 168 --diameter 0.308 \
+  --offline
+
+# Stage 2: record a subsonic/transonic drop observation on the trued, saved profile.
+./ballistics dsf --saved-profile my-rifle --range 900 --observed-drop 5.1mil
+```
+
+`dsf` takes no ballistic parameters of its own — it solves the named saved profile's
+own trajectory (no CLI overrides) and derives everything else from `--range` and
+`--observed-drop` (`mil`, `moa`, or `in`, no separator between number and unit). An
+observation whose target-range Mach exceeds 1.2 is rejected outright, pointing back to
+`true-velocity`. Up to 6 distinct Mach-keyed points accumulate per profile; a new point
+within 0.05 Mach of an existing one supersedes it (announced on stdout); a 7th distinct
+point is rejected, naming `--clear-dsf` to make room. `trajectory --saved-profile` and
+`come-ups --profile` then auto-apply the table as a **drop-only** correction — velocity,
+energy, and time of flight are byte-identical to the untrued solve — printing a
+table-output-only note; JSON/CSV carry the corrected drop numbers with no equivalent
+text. `profile save NAME ... --clear-dsf` removes an existing table. See
+[CLI_USAGE.md](CLI_USAGE.md#dsf-drop-scale-factor-truing) for the full staging-gate
+reference.
+
 ## Advanced Features
 
 ### Online Mode (API Integration)
@@ -495,7 +586,7 @@ Model precession and nutation of spinning projectiles:
 The ballistics engine implements comprehensive physics modeling for accurate trajectory prediction:
 
 ### Aerodynamic Effects
-- **Drag Modeling** - Multiple drag functions (G1-G8, JBM, custom curves) with transonic flow corrections
+- **Drag Modeling** - Full standard-projectile family (G1, G2, G5, G6, G7, G8, GI, GS, RA4) plus custom Cd(Mach) curves, with transonic flow corrections
 - **Form Factor** - Projectile efficiency corrections based on shape and design
 - **Reynolds Number Effects** - Reynolds diagnostics and an opt-in helper for genuinely low-Re flow; standard drag tables are not multiplied by an extra correction
 

package/ballistics_engine.d.ts

@@ -113,6 +113,13 @@ export class WasmBallistics {
      *
      * Returns a short human-readable summary of the loaded table (point count + Mach
      * range). Replaces any previously loaded table.
+     *
+     * MBA-1409: also accepts `.drg` vendor drag-curve text (the same format the native
+     * `--drag-table` CLI accepts by `.drg` file extension) as a fallback. WASM has no
+     * filesystem and thus no extension to dispatch on, so the bytes are tried as CSV first
+     * (exactly as before this change); only on CSV failure, if the text
+     * [`crate::drag_file::looks_like_drg`], it is retried through
+     * [`crate::drag_file::parse_drg`]. If both fail, the returned error names both formats.
      */
     loadDragTable(bytes: Uint8Array): string;
     constructor();

package/ballistics_engine.js

@@ -6,7 +6,6 @@
  */
 export class Calculator {
     static __wrap(ptr) {
-        ptr = ptr >>> 0;
         const obj = Object.create(Calculator.prototype);
         obj.__wbg_ptr = ptr;
         CalculatorFinalization.register(obj, obj.__wbg_ptr, obj);
@@ -98,7 +97,7 @@ export class Calculator {
      */
     constructor() {
         const ret = wasm.calculator_new();
-        this.__wbg_ptr = ret >>> 0;
+        this.__wbg_ptr = ret;
         CalculatorFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
@@ -327,6 +326,13 @@ export class WasmBallistics {
      *
      * Returns a short human-readable summary of the loaded table (point count + Mach
      * range). Replaces any previously loaded table.
+     *
+     * MBA-1409: also accepts `.drg` vendor drag-curve text (the same format the native
+     * `--drag-table` CLI accepts by `.drg` file extension) as a fallback. WASM has no
+     * filesystem and thus no extension to dispatch on, so the bytes are tried as CSV first
+     * (exactly as before this change); only on CSV failure, if the text
+     * [`crate::drag_file::looks_like_drg`], it is retried through
+     * [`crate::drag_file::parse_drg`]. If both fail, the returned error names both formats.
      * @param {Uint8Array} bytes
      * @returns {string}
      */
@@ -352,7 +358,7 @@ export class WasmBallistics {
     }
     constructor() {
         const ret = wasm.wasmballistics_new();
-        this.__wbg_ptr = ret >>> 0;
+        this.__wbg_ptr = ret;
         WasmBallisticsFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
@@ -383,29 +389,28 @@ export class WasmBallistics {
     }
 }
 if (Symbol.dispose) WasmBallistics.prototype[Symbol.dispose] = WasmBallistics.prototype.free;
-
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg___wbindgen_throw_39bc967c0e5a9b58: function(arg0, arg1) {
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
         __wbg_getRandomValues_cc7f052a444bb2ce: function() { return handleError(function (arg0, arg1) {
             globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
         }, arguments); },
-        __wbg_new_cbee8c0d5c479eac: function() {
+        __wbg_new_32b398fb48b6d94a: function() {
             const ret = new Array();
             return ret;
         },
-        __wbg_new_ed69e637b553a997: function() {
+        __wbg_new_da52cf8fe3429cb2: function() {
             const ret = new Object();
             return ret;
         },
-        __wbg_push_a6f9488ffd3fae3b: function(arg0, arg1) {
+        __wbg_push_d2ae3af0c1217ae6: function(arg0, arg1) {
             const ret = arg0.push(arg1);
             return ret;
         },
-        __wbg_set_bad5c505cc70b5f8: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_set_8535240470bf2500: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
@@ -437,10 +442,10 @@ function __wbg_get_imports() {
 
 const CalculatorFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
-    : new FinalizationRegistry(ptr => wasm.__wbg_calculator_free(ptr >>> 0, 1));
+    : new FinalizationRegistry(ptr => wasm.__wbg_calculator_free(ptr, 1));
 const WasmBallisticsFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
-    : new FinalizationRegistry(ptr => wasm.__wbg_wasmballistics_free(ptr >>> 0, 1));
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmballistics_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
@@ -454,8 +459,7 @@ function getArrayU8FromWasm0(ptr, len) {
 }
 
 function getStringFromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return decodeText(ptr, len);
+    return decodeText(ptr >>> 0, len);
 }
 
 let cachedUint8ArrayMemory0 = null;
@@ -558,8 +562,9 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-let wasmModule, wasm;
+let wasmModule, wasmInstance, wasm;
 function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
     wasm = instance.exports;
     wasmModule = module;
     cachedUint8ArrayMemory0 = null;

package/package.json

@@ -5,7 +5,7 @@
     "Alex Jokela <email@tinycomputers.io>"
   ],
   "description": "High-performance ballistics trajectory engine with professional physics",
-  "version": "0.26.0",
+  "version": "0.30.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",