ballistics_engine/constants.rs
1//! Physical constants used in ballistics calculations.
2
3/// Gravitational acceleration in m/s²
4pub const G_ACCEL_MPS2: f64 = 9.80665;
5
6/// Conversion factor: meters per second to feet per second
7pub const MPS_TO_FPS: f64 = 3.28084;
8
9/// Conversion factor: feet per second to meters per second
10pub const FPS_TO_MPS: f64 = 0.3048;
11
12/// Default powder reference temperature in Fahrenheit.
13pub const DEFAULT_POWDER_REFERENCE_TEMP_F: f64 = 70.0;
14
15/// Default powder reference temperature in Celsius.
16pub const DEFAULT_POWDER_REFERENCE_TEMP_C: f64 =
17 (DEFAULT_POWDER_REFERENCE_TEMP_F - 32.0) * 5.0 / 9.0;
18
19/// Standard air density at sea level (kg/m³)
20pub const STANDARD_AIR_DENSITY: f64 = 1.225;
21
22/// Cd-to-retardation conversion for ICAO-referenced BCs.
23///
24/// Exact imperial retardation form for density normalized to ICAO sea-level air
25/// (1.225 kg/m^3 / 0.076474 lb/ft^3):
26///
27/// `a_ft/s^2 = Cd * v_fps^2 * (rho / 1.225) * CD_TO_RETARD / BC`
28///
29/// The older `0.000683 * 0.30` value is the Army Standard Metro constant and is
30/// only consistent with a 0.075126 lb/ft^3 density reference.
31pub const CD_TO_RETARD: f64 = 2.08551e-4;
32
33/// Conversion factor: grains to kilograms
34pub const GRAINS_TO_KG: f64 = 0.00006479891;
35
36/// Grams per grain — exact by definition.
37///
38/// The international avoirdupois pound is defined as exactly 0.45359237 kg
39/// (i.e. 453.59237 g), and one pound is exactly 7000 grains, so this value
40/// is exact (not a measured or rounded conversion):
41/// 453.59237 g / 7000 = 0.06479891 g/grain (equivalently,
42/// 0.45359237 kg / 7000 = 0.00006479891 kg/grain, then x1000 to get grams).
43///
44/// This is the single source of truth for the grain<->gram conversion; do
45/// not re-derive or re-round it elsewhere (see `tests/constants_guard.rs`).
46pub const GRAMS_PER_GRAIN: f64 = 0.06479891;
47
48/// Grains per gram — the exact reciprocal of [`GRAMS_PER_GRAIN`].
49pub const GRAINS_PER_GRAM: f64 = 1.0 / GRAMS_PER_GRAIN;
50
51/// Air density at sea level (kg/m³)
52pub const AIR_DENSITY_SEA_LEVEL: f64 = 1.225;
53
54/// Speed of sound at sea level, standard atmospheric conditions
55///
56/// Value: 340.29 m/s (1116.44 ft/s)
57/// Conditions: 15°C (59°F), 1013.25 hPa, dry air
58///
59/// Temperature dependence: c = 331.3 * sqrt(T_kelvin / 273.15)
60///
61/// Note: Some calculations use 343.0 m/s (20°C reference) - ensure consistency
62/// in Mach number calculations. This value follows ICAO Standard Atmosphere.
63///
64/// Source: International Standard Atmosphere (ISO 2533)
65pub const SPEED_OF_SOUND_MPS: f64 = 340.29;
66
67// Numerical stability constants
68/// General numerical tolerance for floating point comparisons
69pub const NUMERICAL_TOLERANCE: f64 = 1e-9;
70
71/// Minimum threshold for velocity magnitude to avoid division by zero
72pub const MIN_VELOCITY_THRESHOLD: f64 = 1e-6;
73
74/// Minimum threshold for preventing division by zero in general calculations
75pub const MIN_DIVISION_THRESHOLD: f64 = 1e-12;
76
77/// Tolerance for root finding algorithms
78pub const ROOT_FINDING_TOLERANCE: f64 = 1e-6;
79
80/// Minimum threshold for Mach number calculations near unity
81pub const MIN_MACH_THRESHOLD: f64 = 1e-3;
82
83// Ballistic Coefficient (BC) fallback constants
84//
85// These values are used when BC calculations fail or data is missing.
86// Derived from statistical analysis of 2,000+ projectile database.
87// Values represent conservative estimates (25th percentile) to avoid
88// over-predicting ballistic performance.
89
90/// Conservative overall BC fallback value
91///
92/// Value: 0.31 (25th percentile from comprehensive ballistics database)
93/// Usage: General fallback when no specific projectile data available
94/// Methodology: Statistical analysis of measured BC values across all categories
95pub const BC_FALLBACK_CONSERVATIVE: f64 = 0.31;
96
97// BC fallback values by projectile weight category (grains).
98// Values are based on statistical analysis of ballistic coefficient vs mass relationships.
99// Each constant represents the 25th-percentile BC for that weight category.
100
101/// Ultra-light projectiles (0-50 grains)
102/// Typical: .17 caliber varmint bullets, .22 caliber target bullets
103pub const BC_FALLBACK_ULTRA_LIGHT: f64 = 0.172;
104
105/// Light projectiles (50-100 grains)
106/// Typical: .223 Remington, .243 Winchester hunting bullets
107pub const BC_FALLBACK_LIGHT: f64 = 0.242;
108
109/// Medium projectiles (100-150 grains)
110/// Typical: .270 Winchester, .30-06 hunting bullets
111pub const BC_FALLBACK_MEDIUM: f64 = 0.310;
112
113/// Heavy projectiles (150-200 grains)
114/// Typical: .308 Winchester match bullets, .300 Winchester Magnum
115pub const BC_FALLBACK_HEAVY: f64 = 0.393;
116
117/// Very heavy projectiles (200+ grains)
118/// Typical: .338 Lapua Magnum, .50 BMG bullets
119pub const BC_FALLBACK_VERY_HEAVY: f64 = 0.441;
120
121// BC fallback values by caliber category (inches).
122// Values account for diameter limitations on achievable ballistic coefficient.
123// Larger calibers generally allow higher BC but with diminishing returns.
124
125/// Small calibers (.224" and smaller)
126/// Examples: .17 Remington, .22-250, .223 Remington
127pub const BC_FALLBACK_SMALL_CALIBER: f64 = 0.215;
128
129/// Medium calibers (.243")
130/// Examples: .243 Winchester, 6mm Creedmoor
131pub const BC_FALLBACK_MEDIUM_CALIBER: f64 = 0.300;
132
133/// Large calibers (.264" to .284")
134/// Examples: .270 Winchester, .280 Remington, 7mm Remington Magnum
135pub const BC_FALLBACK_LARGE_CALIBER: f64 = 0.404;
136
137/// Extra large calibers (.308" and larger)
138/// Examples: .308 Winchester, .30-06, .300 Winchester Magnum
139/// Note: Lower than expected due to inclusion of older, less aerodynamic designs
140pub const BC_FALLBACK_XLARGE_CALIBER: f64 = 0.291;
141
142#[cfg(test)]
143mod tests {
144 use super::*;
145
146 #[test]
147 fn powder_reference_temperature_defaults_are_equivalent() {
148 let converted = (DEFAULT_POWDER_REFERENCE_TEMP_F - 32.0) * 5.0 / 9.0;
149
150 assert_eq!(
151 DEFAULT_POWDER_REFERENCE_TEMP_C.to_bits(),
152 converted.to_bits()
153 );
154 }
155
156 /// Independent ground-truth check for the grain<->gram constants: this
157 /// test does *not* reference `GRAMS_PER_GRAIN`/`GRAINS_PER_GRAM` in its
158 /// expected values, so it fails if either constant is ever silently
159 /// corrupted (re-truncated, re-rounded, or swapped for a sibling value),
160 /// even if the corrupted value doesn't match one of the specific banned
161 /// literals `tests/constants_guard.rs` greps for.
162 #[test]
163 fn grams_per_grain_matches_independent_ground_truth() {
164 // 1 lb = exactly 0.45359237 kg = 453.59237 g (avoirdupois pound,
165 // international definition); 1 lb = exactly 7000 grains.
166 let independent_grams_per_grain: f64 = 453.59237 / 7000.0;
167 assert_eq!(
168 GRAMS_PER_GRAIN.to_bits(),
169 independent_grams_per_grain.to_bits()
170 );
171
172 // Cross-check against the pre-existing kilogram-scale constant:
173 // GRAMS_PER_GRAIN must equal GRAINS_TO_KG scaled from kg to g.
174 assert!((GRAMS_PER_GRAIN - GRAINS_TO_KG * 1000.0).abs() < 1e-15);
175
176 // GRAINS_PER_GRAM must be the exact reciprocal used in production.
177 assert_eq!(GRAINS_PER_GRAM.to_bits(), (1.0 / GRAMS_PER_GRAIN).to_bits());
178 }
179}