Ballistics Insight on Android: A Solver That Admits What It Assumed

A.C. Jokela — Mon, 12 Oct 2026 17:00:00 GMT

Ballistics Insight is on Google Play. It is a long-range ballistic calculator: give it a load, a rifle and the day's conditions, and it gives you the drop and the wind hold at every distance in MIL or MOA, with time of flight, velocity and energy. The solver is ballistics-engine, the Rust library I open-sourced last year and wrote about testing in August. On the phone it runs entirely on the device. A rifle range is a bad place to depend on a cell signal, so nothing about a solve touches the network.

The Android repository's first commit is from August 16, 2025. It has 560 commits now, 217 Kotlin source files and about 57,800 lines, and the build I submitted on October 8 ran 1,982 unit tests and 167 on-device tests without a failure. Most of those tests exist because something went wrong first. This post is about how the app is put together and about the mistakes that shaped it, because nearly all of them reduce to one lesson. The worst failure a ballistic calculator can have is not a crash. It is a confident number built on an assumption the shooter never saw.

One JNI function and a JSON envelope

The app is Kotlin and Jetpack Compose with Material 3: five tabs on a phone (Solve, DOPE, Loads, Tools, Account) and a navigation rail on a tablet. The physics is a prebuilt Rust shared library, libballistics_engine.so, about 5 MB for each of the two ABIs the app ships, arm64-v8a and x86_64. Between Kotlin and Rust sits a 612-line C++ shim.

The first version of that shim did what JNI shims usually do. Every engine function got a native method, a C struct, and hand-written marshalling for each field. That holds up until the engine grows. Each new feature meant touching Rust, C, C++ and Kotlin in lockstep, and a field added on one side and forgotten on another does not fail loudly: three doubles still come back, they are just the wrong three doubles. So in August I replaced the pattern with a single entry point. The engine exports ballistics_bridge_call_n, which takes a JSON envelope naming a command and returns a JSON envelope holding either a result or an error. On the Kotlin side the whole bridge is one function:

fun callEnvelope(command: String, request: JsonElement? = null): Envelope {
    val envelope = buildJsonObject {
        put("api_version", API_VERSION)
        put("command", command)
        if (request != null) put("request", request)
    }
    val raw = nativeCall(envelope.toString())
    val response = json.parseToJsonElement(raw).jsonObject
    val ok = response["ok"]?.jsonPrimitive?.booleanOrNullSafe() ?: false
    // ...a false "ok" becomes a BridgeException carrying the engine's error code

The app now uses sixteen commands through that one function: solve; card.range_table, card.come_ups, card.wind and card.pdf for range cards; true.fit and true.wind for truing; bc5d.info for correction tables; three profile.* commands for importing profiles from other solvers; three reticle.* commands for holds read off a reticle; and two meta.* queries. A new engine capability is a new command name, and the C++ does not change. Serializing JSON costs microseconds next to a trajectory integration, so I have not missed the typed interface once. The four original typed C functions are still in the library, and only the shot-spread screen still calls them.

The other half of the integration is knowing exactly which engine shipped. A file called engine.ref holds the commit the app is pinned to, currently the v0.43.0 tag from September 17. A build script checks that commit out into a throwaway git worktree and runs the engine's own Android build with cargo-ndk, the bridge, ffi, pdf and profile-import features, and 16 KB page alignment, which Google Play now requires of native code. A CI job then reads the version string out of the committed .so and checks it against the pin and against the list of bridge commands the Kotlin calls. That job exists because the pin and the binary had drifted apart once already, and nothing noticed.

The rule: say what you assumed

Ballistics punishes defaults. A solver needs air pressure, temperature, humidity, the barrel's twist rate and, for Coriolis, your latitude. People leave fields blank, and every blank has an obvious default. Every default is also a claim about the world that the shooter did not make.

The Solve tab at 1,000 yards. The two lines above the results say which inputs were assumed, and what was assumed.

Pressure is the clearest case. Early versions filled a blank pressure field by computing a standard-atmosphere value in Kotlin and sending it to the engine. The engine had no way to tell that number from one a Kestrel had measured, so it had nothing to report. Now a blank pressure is simply left out of the request, and the engine resolves the ICAO standard atmosphere at the given altitude and says that it did. The comment in the request builder is the whole design:

// ABSENT when nothing was measured. The engine resolves ICAO
// standard pressure at `altitude_m` and reports that it did; a
// number computed here would arrive indistinguishable from a
// Kestrel reading and silence the assumption.
pressurePa = atmosphere.pressureHpa?.times(PASCALS_PER_HECTOPASCAL),

That is where "25.65 inHg, standard atmosphere for 4200 ft, not measured" comes from. When a pressure is measured, the app asks which kind it is. A Kestrel reports station pressure, the absolute pressure where you are standing. A weather app, an ATIS broadcast or a METAR reports QNH, the altimeter setting corrected to sea level. At 4,200 feet the two differ by more than four inches of mercury, and typing a QNH into a station-pressure field tells the solver you are shooting at sea level, roughly the 0.6 mil of elevation at 1,000 yards that a card bug I describe below cost. The engine reduces QNH to station pressure itself, through the troposphere layer of the standard atmosphere, so the app only has to record which one the shooter typed.

The barrel twist taught me the same rule more expensively. Until September 12, every solve on both platforms assumed a 1:12 twist. The load screen stored the real one, and the field had been nullable since the day it was added, with a comment explaining why: "a silent wrong twist is worse than an empty field." Then the code that built the solver's inputs never read it. Miller stability scales with the inverse square of the twist in calibers, so a 1:8 barrel is about 2.25 times as stable as the app believed, and every faster-twist rifle was shown less spin drift than it has. Now the load's twist travels with it to the solver. When no twist is recorded, the solver skips spin drift and Magnus and the screen says so, instead of leaving a switched-on toggle quietly doing nothing.

Coriolis follows the same rule. The engine computes it fully, but the Solve tab does not collect a shooting latitude yet, and I would rather the toggle say "Coriolis needs a shooting latitude, which this screen doesn't collect, so it is not applied" than invent a latitude.

Weather from the meter, not from memory

The most common source of a wrong input is typing. So the app reads two Bluetooth weather meters directly: the Kestrel 5700 LiNK and the WeatherFlow WEATHERmeter.

Left: choosing a meter. Right: live mode, filling the fields from a Kestrel and averaging the wind over 30 seconds.

The Kestrel's sensor characteristic packs wind speed, temperature, humidity and station pressure into little-endian 16-bit fields, each with a reserved value that means "not available":

val wind = LittleEndian.u16(bytes, 0)
val temperature = LittleEndian.u16(bytes, 2)
val humidity = LittleEndian.u16(bytes, 6)
val pressure = LittleEndian.u16(bytes, 8)

return KestrelSensorReading(
    windSpeedMps = if (wind == NOT_AVAILABLE_U16) null else wind / 1000.0,
    temperatureC = if (temperature in TEMPERATURE_NOT_AVAILABLE) {
        null
    } else {
        OnesComplement.i16(temperature) / 100.0
    },
    // ...humidity and pressure are decoded the same way

The order of those checks is not cosmetic. Temperature is signed, and if you apply the sign rule before testing for the not-available marker, 0x8001 decodes as minus 327.66 °C, a number the solver will use without complaint. Wind direction is in the frame as well, and the first version discards it and leaves direction to the wind dial on the Solve tab.

The WEATHERmeter carries the word "uncalibrated" in the chooser, and the label is earned: side by side with the Kestrel it read 1.2 °C warm and 15 to 17 points high on relative humidity. The app recognizes it by its advertised name only, and says that too. With either meter it only ever subscribes to notifications and never writes to the device, and it declares its Bluetooth scan permission neverForLocation, which a unit test pins. The newest build adds the phone itself as a source: its barometer, where it has one, and its GPS altitude converted to height above sea level.

Truing has to report its own error bars

Every ballistic calculator eventually disagrees with the rifle. The published ballistic coefficient was measured with someone else's barrel, and the velocity on the ammunition box is optimistic. Truing closes the gap: shoot at known distances, record where the bullet actually went, and fit the model to what happened.

Four measured drops, each with its reading error, and the fit they produce: 2,682 fps instead of the 2,710 entered, and a BC of 0.3006 instead of 0.3150, each with a 95% interval.

The engine fits muzzle velocity and ballistic coefficient together. Each measured drop carries a plus-or-minus, and the app requires one, because a drop read to 0.05 mil and one estimated to half a mil should not count equally. The fit is a weighted two-parameter maximum a posteriori estimate, solved with Levenberg–Marquardt in scaled coordinates (100 fps and 0.1 of BC each count as one unit, so neither parameter dominates a step), followed by a pattern search that confirms the minimum. The 95% intervals come from a local Gaussian approximation of the posterior. The engine withholds them when the fit lands on a parameter bound or the information matrix is singular, because an interval computed there is fiction.

Those intervals earned their place on the screen in an embarrassing way. The first store screenshot for this feature used three drops I picked by hand, at 400, 600 and 800 yards. The fit came back with two engine warnings, one of them that the observations "weakly constrain BC", and a BC interval of 0.2674 to 0.3254, which contained the 0.3150 the fit was supposed to be correcting. The engine was right. Over that short a spread, a slow barrel and a draggy bullet bend the trajectory in almost the same way, and no fit can tell them apart. The engine ships a planner for exactly this question, true.plan, which chooses the distances that best separate the two parameters. Asked for four stations at least 300 yards apart, it chose 300, 600, 900 and 1,200, and the screenshot above is the result: both intervals now exclude the numbers they replaced.

The screen is blunt about what a fit proves. Below the result it shows how much closer the model now lands at the fitted distances, then explains that a fit always improves the distances it was fitted to, "so this is not a test of whether it worked. The test is a new shot at a distance you did not fit."

One sentence on the input side mattered as much as any of the maths. The engine wants each drop as a positive number below the line of sight. Enter the drops with the opposite sign and the request is still perfectly valid. It fits. It converges on a bullet that climbs, prints a confident interval around it, spends one of your five free fits and offers to write the result onto your load. Nothing below the keyboard can detect that, so the screen now states the sign convention, and a test pins the sentence word for word on both Android and iOS.

The second kind of truing works from wind. Given a horizontal miss at a known distance, true.wind finds the crosswind that reproduces it, after subtracting the spin drift that the load's twist predicts. It is a one-dimensional root find over plus or minus 100 mph by false position, with the Illinois modification that keeps one end of the bracket from stalling:

// Illinois: halve the retained endpoint's function value so one side cannot stall.
if f < 0.0 {
    low = candidate;
    f_low = f;
    f_high *= 0.5;
} else {
    high = candidate;
    f_high = f;
    f_low *= 0.5;
}

With several observations the answer is an inverse-variance weighted mean, so the careful reading counts for more than the hurried one.

A DOPE card is a record, not a recipe

A range card in MIL from 100 to 1,000 yards. Row color says whether the bullet is still supersonic.

A DOPE card is the sheet you tape to the stock or keep in a chest pocket. Once saved, it must not change because the weather changed, a correction table was updated, or I shipped a new engine. So a saved card stores the engine's request and response as raw bytes, exactly as they came back, along with the version of the engine that solved them. Those bytes go into the local database and into the cloud and come back out without being parsed and re-serialized, and tests check that at every hop. Opening a card renders those rows; nothing re-solves. "Regenerate for current conditions" exists, but it shows what changed before it writes anything. The PDF export is rendered by the engine itself, with the printpdf crate, so the printed card and the screen are built from the same bytes.

Getting the card right took more than one pass. One release laid six columns totalling 456 density-independent pixels into a 379 dp card, so energy and time of flight ran off the edge. Worse, the card ignored the atmosphere entirely, which at 4,200 feet is about 0.6 mil of missing elevation at 1,000 yards. Fixing that exposed a units bug of its own: the engine takes altitude in meters, and 4,200 sent raw is the atmosphere at 13,780 feet.

The bugs lived in the seams

The engine's physics has fuzzing harnesses and closed-form oracles behind it. The app's bugs were in the places those cannot reach: the joints between the engine and the app, between two devices, and between the source tree and the thing that actually shipped.

In August I upgraded the engine binaries from 0.13 to 0.33. Between those versions the typed interface's axis convention changed from (lateral, vertical, downrange) to (downrange, vertical, lateral). The functions still returned three valid doubles, so no test failed. Every horizontal figure on the shot-spread screen became exactly zero. Separately, the engine marks a simulated shot that falls short of the target with a vertical position of minus a billion meters, and nothing filtered it, so the vertical standard deviation came out near 2 × 10¹⁰ inches. The fix moved the maths into a Kotlin class a unit test can reach and wrote the convention into the C header, where the next upgrade will trip over it.

Sync is opt-in. Until you sign in with Google or Apple, your loads, logs and cards stay on the phone, and the sync workers skip anonymous users entirely. Once you sign in, a background job syncs every 15 minutes, and for its first weeks it corrupted data on that schedule. Android writes timestamps as epoch milliseconds, and the decoder handled ISO strings and Firestore timestamps but had no branch for a plain number. Every Android row read back as "now", the cloud copy always looked newer, last-write-wins fired on every cycle, and a G7 load on one device could turn back into G1 on another. None of it appeared with one device. All of it appeared with two, which is exactly the setup that a Pro purchase covering both platforms encourages.

An internal test build once went out with the template google-services.json, which contains the literal string YOUR_API_KEY. The Google Services plugin only checks that the fields exist, the file is gitignored so git status stayed clean, and CI copies the template on purpose, so CI could never have caught it. A tester's Account screen reading "API key not valid" did. There is now a pre-upload script that checks the configuration and the built bundle both, since a stale bundle built before a fix passes every check made against the source.

And a 5911 × 3941 PNG, drawn behind the interface at 5% opacity, was 46% of the download. Re-encoded as a 2560-pixel WebP it is 291 KB, and the app bundle went from 45.1 MB to 28.1 MB.

Free solver, one-time Pro

The solver is free, with no ads and no tracking. So are the downloadable BC correction tables, which matter more than they sound. They are BC5D tables: binary cubes of correction factors indexed by drag model, bullet weight, BC, muzzle velocity and current velocity, generated from the machine-learning model I described when I wrote about turning it into lookup tables so the corrections work offline. The app downloads one table per caliber to a temporary file, checks it against the manifest's CRC-32, has the engine validate the header and confirm the caliber, and only then renames it into place. The current set covers thirteen calibers in 3.3 MB.

Pro is a one-time purchase rather than a subscription. It unlocks DOPE range cards and their PDF export, importing .a7p profiles from other solvers, and truing, and the first five truing fits are free without it. A calculator is a tool, and a tool should be bought once.


Package	`io.tinymachines.ballisticsinsight`
Version	2.0.0
Android	8.0 (API 26) and up, targeting API 36
Engine	ballistics-engine 0.43.0, pinned by commit
Native code	about 5 MB per ABI, arm64-v8a and x86_64
App code	217 Kotlin files, about 57,800 lines
Tests at submission	1,982 unit, 167 on-device
Bridge commands in use	16

Ballistics Insight is on Google Play now, free to install. The engine underneath it is open source under MIT or Apache 2.0 on GitHub, with documentation at ballistics.rs, and the iPhone build pins the same engine commit. When I wrote about the engine in August, the point was that its hard bugs were never in the physics. The app taught me where they go instead: into whatever the software assumed while the shooter was not looking. So the rule now is that every assumption ends up on the screen.

TinyComputers.io (Posts about jetpack compose)