--- name: ballistic-calculator description: > Use whenever writing, reviewing, or debugging .NET/C# code that uses the BallisticCalculator NuGet package (namespace BallisticCalculator) or its Gehtsoft.Measurements unit types — even when the user doesn't name the package explicitly but is clearly doing external/interior ballistics in .NET (bullet drop, velocity, energy, windage, spin drift, time of flight, zeroing a scope) for rifles, air rifles, bows, or artillery. Covers the full public API (Ammunition, Rifle, Atmosphere, Wind, ShotParameters, TrajectoryCalculator, TrajectoryPoint); standard, custom, .drg, and multi-BC drag tables; saving/loading data and building your own file format around it (BXml and System.Text.Json serialization); and building or rendering scope reticles (e.g. to SVG). Also use it for this library's Gehtsoft.Measurements Measurement unit types (DistanceUnit, VelocityUnit, AngularUnit, WeightUnit, PressureUnit, …). Skip for: generic physics or projectile-motion exercises, a different ballistics library (e.g. GNU/JBM), game-engine or Unity projectile motion, plain unit conversions, and non-code ballistics questions (load-data or forensics advice). Self-contained: no access to the library source or binaries is required — prefer this over scanning the package to rediscover the API. Describes 1.1.13+, including the named ZeroRangeCantBeReachedException / TrajectoryCannotBeCalculatedException failures. --- # BallisticCalculator A .NET library (`netstandard2.0`) that models the trajectory of a projectile through the atmosphere using a 3DOF (point-mass) model. - NuGet: **`BallisticCalculator`** (namespace `BallisticCalculator`). This describes **1.1.13+**; where behaviour changed, the version that changed it is named. - Depends on **`Gehtsoft.Measurements`** (namespace `Gehtsoft.Measurements`) — every physical quantity is a strongly-typed `Measurement`. - License: LGPL 2.1. ```csharp using BallisticCalculator; using Gehtsoft.Measurements; ``` The workflow is always: **(1)** describe the ammunition, rifle, and atmosphere → **(2)** compute the zero (sight) correction with `CalculateZeroParameters` and `Apply` it to the `ShotParameters` → **(3)** call `Calculate` → **(4)** read the returned `TrajectoryPoint[]`. --- ## 1. Measurements (the value type used everywhere) Every dimensional value is a `Measurement` struct — a `double` value plus a unit. You pick the unit at construction and again when you read it; metric and US units interoperate freely. ```csharp var d = new Measurement(100, DistanceUnit.Yard); // value + unit var d2 = new Measurement("100yd"); // parse "" double meters = d.In(DistanceUnit.Meter); // convert & read as double double raw = d.Value; // value in its own unit (100) DistanceUnit u = d.Unit; // DistanceUnit.Yard var zero = Measurement.ZERO; // 0 double mm = Measurement.Convert(1, DistanceUnit.Inch, DistanceUnit.Meter); // static double->double var d3 = 100.As(DistanceUnit.Yard); // extension sugar: (double|int).As(unit) var d4 = DistanceUnit.Yard.New(100); // unit-first sugar: unit.New(value) ``` Operators: `+` `-` (same unit), `*` `/` by a scalar, and comparisons. Nullable `Measurement?` marks optional inputs. The three construction forms above (`new`, `.As`, `.New`) are equivalent — use whichever reads best. **Unit enums** (use the exact member names): | Enum | Members | |------|---------| | `DistanceUnit` | Millimeter, Centimeter, Meter, Kilometer, Inch, Foot, Yard, Mile, NauticalMile, Line, RussianLine, Point, Pica | | `VelocityUnit` | MetersPerSecond, KilometersPerHour, FeetPerSecond, MilesPerHour, Knot | | `AngularUnit` | Radian, Degree, MOA, Mil, MRad, Thousand, InchesPer100Yards, CmPer100Meters, Percent, Turn, Gradian | | `WeightUnit` | Grain, Ounce, Gram, Pound, Kilogram, Neuton, Dram, TroyOz, Tonne, USTonne, UKTonne | | `PressureUnit` | Pascal, KiloPascal, Bar, Millibar, Atmosphere, TechincalAtmosphere, MillimetersOfMercury, InchesOfMercury, PoundsPerSquareInch, MillimetersOfWater | | `TemperatureUnit` | Fahrenheit, Celsius, Kelvin, Rankin, Reaumur, Delisle | | `EnergyUnit` | FootPound, Joule, BTU, HpH, Wh | | `DensityUnit` | GramPerCubicCentimeter, KilogramPerCubicMeter, PoundsPerCubicInch, OuncesPerCubicFeet, PoundsPerCubicFoot | (`TechincalAtmosphere` is spelled that way in the library.) --- ## 2. Describing the shot (inputs) ### Ammunition ```csharp public Ammunition( Measurement weight, BallisticCoefficient ballisticCoefficient, Measurement muzzleVelocity, Measurement? bulletDiameter = null, // required only for spin drift Measurement? bulletLength = null) // required only for spin drift ``` Properties: `Weight`, `BallisticCoefficient`, `MuzzleVelocity`, `BulletDiameter?`, `BulletLength?`, `CustomTableFileName`. `double GetBallisticCoefficient()` returns the effective BC. ### BallisticCoefficient (struct) and drag tables ```csharp new BallisticCoefficient(0.325, DragTableId.G7) // a coefficient new BallisticCoefficient(1.0, DragTableId.GC, BallisticCoefficientValueType.FormFactor) new BallisticCoefficient("0.325G7") // parse text form ``` - `DragTableId`: `G1, G2, G5, G6, G7, G8, GI, GS, RA4` (standard curves) and `GC` (custom — see §6). - `BallisticCoefficientValueType`: `Coefficient` (a BC number) or `FormFactor`. - Text form: `"0.325G7"`, or `"F1GC"` (leading `F` = form factor; last two chars = table id). ### Sight, Rifling, ZeroingParameters, Rifle ```csharp new Sight(Measurement sightHeight, Measurement verticalClick, Measurement horizontalClick) // clicks may be Measurement.ZERO new Rifling(Measurement riflingStep, TwistDirection direction) // step = distance per turn; TwistDirection.Left|Right new ZeroingParameters(Measurement distance, Ammunition ammunition, Atmosphere atmosphere) // ammunition/atmosphere may be null; when set they override the shot's ammo/atmo FOR ZEROING ONLY. // Optional property: VerticalOffset (Measurement?, + is up) shifts the zero impact point. new Rifle(Sight sight, ZeroingParameters zero, Rifling rifling = null) // rifling optional ``` ### Atmosphere (immutable; derived values computed in the constructor) ```csharp new Atmosphere() // sea level standard new Atmosphere(Measurement altitude, Measurement pressure, // STATION pressure at that altitude Measurement temperature, double humidity) // humidity is a FRACTION 0..1, not % new Atmosphere(Measurement altitude, Measurement pressure, bool pressureAtSeaLevel, // true => pressure is sea-level-corrected Measurement temperature, double humidity) Atmosphere.CreateICAOAtmosphere(Measurement altitude, double humidity = 0) ``` Read-only properties: `Altitude`, `Pressure`, `Temperature`, `Humidity`, `SoundVelocity`, `Density`, `DensityAltitude` (1.1.12 — the standard-atmosphere altitude matching this air's density, humidity included). Static: `Atmosphere.StandardDensity`. `Density` is computed from the resolved station `Pressure`, so it is consistent with what the engine uses (this was wrong before 1.1.12 — up to 21% high at 5000 ft with `pressureAtSeaLevel: true`). `DensityAltitude` is baselined on the ICAO sea-level density, **not** `Atmosphere.StandardDensity` — they differ by ~0.005% (~1.9 ft) and are not interchangeable. ### Wind ```csharp new Wind(Measurement velocity, Measurement direction, Measurement? maximumRange = null) ``` - **Direction:** 0° blows toward the target, 90° blows from the right (right-to-left across the path), 180° toward the shooter, 270°/−90° from the left. - `Calculate` takes a `Wind[]`. Each wind applies out to its `MaximumRange`; the last one (or one with a null range) applies to the end. **Sort the array by ascending `MaximumRange`.** ### ShotParameters (output granularity + geometry) ```csharp var shot = new ShotParameters { Step = new Measurement(100, DistanceUnit.Yard), // row spacing MaximumDistance = new Measurement(1000, DistanceUnit.Yard), // extent ShotAngle = null, // Measurement? line-of-sight incline, + up / - down CantAngle = null, // Measurement? BarrelAzimuth = null, // Measurement? Latitude = null, // Measurement? shooter latitude (Coriolis); optional }; // The zero (sight) correction is REQUIRED but not set by hand — compute it and copy it in // (see §3). Apply fills ZeroDropAdjustment / ZeroWindageAdjustment on the shot: shot.Apply(calc.CalculateZeroParameters(ammo, atmosphere, rifle, rifle.Zero)); ``` `Apply` sets the `ZeroDropAdjustment` / `ZeroWindageAdjustment` properties; the incline-adjusted `ShotDropAdjustment` / `ShotWindageAdjustment` are also exposed. There is no longer a `SightAngle` property. --- ## 3. Running the calculation ```csharp public class TrajectoryCalculator { // Compute the zero (sight) correction for the rifle's zero distance. `zero` is usually // rifle.Zero. Pass dragTable only when the BC uses table GC. NOTE the argument order: // atmosphere comes BEFORE rifle here (the opposite of Calculate). ZeroCalculatedParameters CalculateZeroParameters( Ammunition ammunition, Atmosphere atmosphere, Rifle rifle, ZeroingParameters zero, ShotParameters shot = null, Wind[] wind = null, DragTable dragTable = null, Measurement? accuracy = null); // accuracy default 0.1 mm TrajectoryPoint[] Calculate(Ammunition ammunition, Rifle rifle, Atmosphere atmosphere, ShotParameters shot, Wind[] wind = null, DragTable dragTable = null); Measurement MaximumCalculationStepSize { get; set; } // default 10 cm IntegrationMethod Integrator { get; set; } // Euler | MidpointRK2 (default) static Measurement MaximumDrop { get; } // 10000 ft — stop condition static Measurement MinimumVelocity { get; } // 50 ft/s — stop condition } // Returned by CalculateZeroParameters; copy it into the shot with ShotParameters.Apply. public class ZeroCalculatedParameters { Measurement ZeroDropAdjustment { get; } // vertical sight correction Measurement? ZeroWindageAdjustment { get; } // horizontal, when computed } ``` Compute the zero correction first, `Apply` it to the `ShotParameters`, then call `Calculate`: ```csharp var zero = calc.CalculateZeroParameters(ammo, atmosphere, rifle, rifle.Zero); shot.Apply(zero); // sets shot.ZeroDropAdjustment (+ windage) — REQUIRED before Calculate var trajectory = calc.Calculate(ammo, rifle, atmosphere, shot); ``` `ShotAngle`, if set, is added to the barrel elevation inside `Calculate`. The result array can be **shorter** than `MaximumDistance/Step + 1`: the run stops early if velocity drops below 50 ft/s or drop exceeds 10000 ft. Iterate the returned array; don't assume its length. ### Failures the engine names Both calls throw rather than returning nonsense, and the two conditions a *user* can fix have their own exception types: ```csharp // namespace BallisticCalculator; both : InvalidOperationException public class ZeroRangeCantBeReachedException : InvalidOperationException { } // CalculateZeroParameters public class TrajectoryCannotBeCalculatedException : InvalidOperationException { } // Calculate ``` | Type | Raised when | What the user changes | |---|---|---| | `ZeroRangeCantBeReachedException` | the load cannot carry to the zero distance — a subsonic pistol load asked for a 1,000 yd zero | zero closer, more muzzle velocity, better BC | | `TrajectoryCannotBeCalculatedException` | the numbers leave nothing to integrate — a zero or absurd BC, weight or muzzle velocity | fix the offending ammunition field | Two rules follow: - **Catch them before any broader handler.** They derive from `InvalidOperationException`, so a `catch (InvalidOperationException)` earlier in the chain swallows them. - **Treat them as input errors, not crashes.** Show a plain message saying what to change; keep the stack trace for exceptions the engine has *not* named, which are bugs worth reporting. The other throws are ordinary argument faults and stay in that second category: `ArgumentException` for a form factor with no bullet diameter (or a non-positive form factor/weight), and `ArgumentNullException` when the BC table is `GC` and no `dragTable` was supplied. Where a field can be checked up front — a non-positive BC, weight or muzzle velocity — validate instead of catching. `TrajectoryCannotBeCalculatedException` is the net under that, not a substitute for it. --- ## 4. Reading the output (`TrajectoryPoint`, read-only) | Property | Type | Meaning | |----------|------|---------| | `Time` | `TimeSpan` | Time of flight to this point. | | `Distance` | `Measurement` | Distance along the line of sight. | | `DistanceFlat` | `Measurement` | Horizontal distance from the muzzle. | | `Velocity` | `Measurement` | Projectile speed. | | `Mach` | `double` | Speed relative to the local speed of sound. | | `Drop` | `Measurement` | Vertical position vs the line of sight. At the muzzle = −sight height. | | `DropFlat` | `Measurement` | Vertical position vs the muzzle (bore line). | | `Windage` | `Measurement` | Horizontal deflection. **Left +, right −.** Includes spin drift when modelled. | | `Energy` | `Measurement` | Kinetic energy. | | `DropAdjustment` | `Measurement` | Angular scope correction for the drop at this distance. | | `WindageAdjustment` | `Measurement` | Angular correction for the windage at this distance. | | `LineOfSightElevation` | `Measurement` | Height of the sight line at this distance. | | `LineOfDepartureElevation` | `Measurement` | Height of the bore line at this distance. | | `OptimalGameWeight` | `Measurement` | Litz optimal game weight estimate. | ```csharp foreach (var p in trajectory) Console.WriteLine($"{p.Distance.In(DistanceUnit.Yard):N0} yd " + $"{p.Velocity.In(VelocityUnit.FeetPerSecond):N0} fps " + $"drop {p.Drop.In(DistanceUnit.Inch):N1} in " + $"wind {p.Windage.In(DistanceUnit.Inch):N1} in"); ``` --- ## 5. Complete examples ### Minimal ```csharp var ammo = new Ammunition( weight: new Measurement(168, WeightUnit.Grain), ballisticCoefficient: new BallisticCoefficient(0.223, DragTableId.G7), muzzleVelocity: new Measurement(2700, VelocityUnit.FeetPerSecond)); var rifle = new Rifle( sight: new Sight(new Measurement(1.5, DistanceUnit.Inch), Measurement.ZERO, Measurement.ZERO), zero: new ZeroingParameters(new Measurement(100, DistanceUnit.Yard), null, null)); var atmosphere = new Atmosphere(); var calc = new TrajectoryCalculator(); var shot = new ShotParameters { MaximumDistance = new Measurement(1000, DistanceUnit.Yard), Step = new Measurement(100, DistanceUnit.Yard), }; shot.Apply(calc.CalculateZeroParameters(ammo, atmosphere, rifle, rifle.Zero)); TrajectoryPoint[] trajectory = calc.Calculate(ammo, rifle, atmosphere, shot); ``` ### Non-standard atmosphere + wind + spin drift Spin drift is modelled only when the rifle has `Rifling` **and** the ammunition has both a bullet diameter and length; it is folded into `Windage` (there is no separate output). ```csharp var ammo = new Ammunition( weight: new Measurement(168, WeightUnit.Grain), ballisticCoefficient: new BallisticCoefficient(0.223, DragTableId.G7), muzzleVelocity: new Measurement(2700, VelocityUnit.FeetPerSecond), bulletDiameter: new Measurement(0.308, DistanceUnit.Inch), bulletLength: new Measurement(1.2, DistanceUnit.Inch)); var rifle = new Rifle( sight: new Sight(new Measurement(2.0, DistanceUnit.Inch), Measurement.ZERO, Measurement.ZERO), zero: new ZeroingParameters(new Measurement(100, DistanceUnit.Yard), null, null), rifling: new Rifling(new Measurement(11.25, DistanceUnit.Inch), TwistDirection.Right)); var atmosphere = new Atmosphere( altitude: new Measurement(5000, DistanceUnit.Foot), pressure: new Measurement(24.9, PressureUnit.InchesOfMercury), temperature: new Measurement(40, TemperatureUnit.Fahrenheit), humidity: 0.30); var wind = new[] { new Wind(new Measurement(10, VelocityUnit.MilesPerHour), new Measurement(90, AngularUnit.Degree), new Measurement(500, DistanceUnit.Yard)), // out to 500 yd new Wind(new Measurement(5, VelocityUnit.MilesPerHour), new Measurement(45, AngularUnit.Degree)), // beyond 500 yd }; var calc = new TrajectoryCalculator(); var shot = new ShotParameters { MaximumDistance = new Measurement(1000, DistanceUnit.Yard), Step = new Measurement(100, DistanceUnit.Yard), }; shot.Apply(calc.CalculateZeroParameters(ammo, atmosphere, rifle, rifle.Zero)); var trajectory = calc.Calculate(ammo, rifle, atmosphere, shot, wind); ``` --- ## 6. Custom drag curves Standard `G1..RA4` curves are applied automatically when the BC names a standard table — nothing extra to do. **If, and only if, the task involves a *non-standard* drag curve — a custom/measured drag table, a radar `.drg` file, or a multi-BC (BC-vs-Mach) profile — read [`references/custom-drag.md`](references/custom-drag.md) and follow it.** That file has the full, copy-pasteable recipes for all three (`DragTable` subclass, `DrgDragTable.Open`, and `DrgDragTableFactory.Build` with `BcAtMach`), including the exact signatures. Do not reconstruct this API from memory or hand-roll a drag table — the helpers exist and the reference has them. All three techniques use table id **`GC`** and require passing the `DragTable` instance to **both** `CalculateZeroParameters` and `Calculate` (`DragTable.Get(GC)` throws — you supply the instance). --- ## 7. Conventions & gotchas - **Humidity is a fraction 0..1**, not a percentage (0.5 = 50 %). - **Pressure** in the 4-argument `Atmosphere` constructor is the station pressure *at that altitude*; use the 5-argument overload with `pressureAtSeaLevel: true` to pass a sea-level value. - **The zero correction must be applied before `Calculate`:** compute it with `CalculateZeroParameters` and copy it into the shot via `ShotParameters.Apply(...)`. There is no `SightAngle` property anymore. - **Argument order differs between the two calls:** `CalculateZeroParameters(ammunition, atmosphere, rifle, zero)` puts atmosphere before rifle, whereas `Calculate(ammunition, rifle, atmosphere, shot)` puts rifle before atmosphere. Easy to transpose. - **Windage sign:** left is positive, right is negative. **`Drop` at the muzzle = −sight height.** - **Spin drift** needs `Rifling` **and** `BulletDiameter` **and** `BulletLength`; otherwise windage is wind-only. It is folded into `Windage` (no separate value). Right twist drifts right, left drifts left. - **`GC` (custom) drag** requires passing the `DragTable` to **both** `CalculateZeroParameters` and `Calculate`; `DragTable.Get(DragTableId.GC)` throws — you must supply the instance. - The returned array may contain **fewer rows** than requested (subsonic/steep runs stop early). - **`ZeroRangeCantBeReachedException` / `TrajectoryCannotBeCalculatedException`** both derive from `InvalidOperationException` — catch them *before* any broader handler, and treat them as input errors the user can fix rather than crashes. See §3. - **`AngularUnit.Mil` is the military mil (1/6400), not the milliradian** (`MRad`, 1/6283.19) — ~1.9 % apart. A mil-dot reticle is a milliradian instrument, and `MilDotReticle` is built in `MRad`. - **Crosswind aerodynamic jump IS modelled** (Litz, Applied Ballistics Eq 5.4), so a pure crosswind moves the point of impact **vertically** as well as horizontally. Like spin drift it needs `Rifling` **and** the bullet diameter **and** length; without them the term is absent. Right twist + wind from the right lifts the impact. --- ## 8. Specialized topics (reference files) These live in `references/` and load only when the task needs them — read the matching file and follow it rather than reconstructing the API from memory: - **Custom / non-standard drag curves** (custom `DragTable`, radar `.drg`, multi-BC synthesis) → [`references/custom-drag.md`](references/custom-drag.md) (see §6). - **Serialization & persistence** — saving/loading `Ammunition`/`Rifle`/`Atmosphere`/libraries via BXml or `System.Text.Json`, embedding library objects in your own file format, and decorating your own classes for the BXml serializer → [`references/serialization.md`](references/serialization.md). - **Reticles** — building a reticle definition in code and rendering it (e.g. to SVG), including bullet-drop-compensator markers → [`references/reticle.md`](references/reticle.md).