module Trainhorn
Overview
Small, dependency-free calculators for train horn setups on trucks, cars and boats.
Trainhorn is a Crystal port of the trainhorn_calc Python package (and
its Go port). It uses the same formulas and constants, so all three give
the same numbers. It covers three areas:
- Acoustics: sound pressure level (SPL) versus distance from the
inverse-square law (
.spl_at_distance,.distance_for_spl), the loss per doubling of distance (.doubling_loss), adding the levels of several horns (.combine_levels) and optional atmospheric absorption (AIR_ABSORPTION_DB_PER_KM). - Air system: free air in a tank from Boyle's law
(
.free_air_volume_cu_ft), continuous horn time (.tank_runtime_seconds,.blast_count) and compressor refill time (.compressor_recovery_seconds,.compressor_recovery_linear_seconds). - Electrical: copper AWG resistance computed from the AWG definition
(
.awg_resistance_ohm_per_1000ft), round-trip voltage drop (.voltage_drop) and the smallest gauge that meets a voltage-drop budget (.suggest_awg).
require "trainhorn"
Trainhorn.spl_at_distance(150.0, 100.0, 10.0) # => 130.0
Trainhorn.tank_runtime_seconds(5.0, 150.0, 110.0, 10.0) # => 10.915668...
Trainhorn.suggest_awg(30.0, 10.0, 12.0).awg # => "6"
Every function validates its input and raises Trainhorn::InvalidInputError
(a subclass of ArgumentError) instead of returning a meaningless number.
Results are engineering estimates from simple models (free field,
isothermal expansion, voltage drop only). They are not measurements and not
a legal noise assessment, and .suggest_awg does not check ampacity or fuse
sizing. Browser versions of these formulas are available as
interactive calculators.
Defined in:
trainhorn.crtrainhorn/acoustics.cr
trainhorn/air_system.cr
trainhorn/electrical.cr
trainhorn/validate.cr
Constant Summary
-
AIR_ABSORPTION_DB_PER_KM =
{63 => 0.1, 125 => 0.4, 250 => 1.0, 500 => 1.9, 1000 => 3.7, 2000 => 9.7, 4000 => 32.8, 8000 => 117.0} -
Approximate atmospheric absorption in dB/km at 10 degC and 70 % relative humidity (an ISO 9613-2 Table 2 condition, computed from the ISO 9613-1 equations). Keys are octave-band centre frequencies in Hz. Train horn chords sit mostly between about 250 Hz and 600 Hz, where absorption is only 1-2 dB/km, so it matters only at long range. Treat the values as a rough guide.
-
ATMOSPHERIC_PSI =
14.696 -
The standard atmosphere at sea level in psi. Pass a lower value for altitude to the air-system methods.
-
AWG_SIZES =
{"18", "16", "14", "12", "10", "8", "6", "4", "2", "1", "1/0", "2/0", "3/0", "4/0"} -
The gauges
.suggest_awgconsiders, thinnest to thickest: the sizes commonly sold as automotive primary wire and battery cable. Odd sizes still work in the other methods. -
COPPER_RESISTIVITY_OHM_M =
1.7241e-8 -
The resistivity of annealed copper (100 % IACS) at 20 degC in ohm-metres.
-
COPPER_TEMP_COEFF_PER_C =
0.00393 -
The temperature coefficient of resistance of annealed copper near 20 degC.
-
CUBIC_FEET_PER_GALLON =
231.0 / 1728.0 -
The volume of one US liquid gallon in cubic feet (231 in^3 / 1728 in^3).
-
FEET =
"ft" -
Length unit: feet.
-
METERS =
"m" -
Length unit: metres.
-
METERS_PER_FOOT =
0.3048 -
The exact length of one international foot in metres.
-
VERSION =
"1.0.0" -
The shard version.
Class Method Summary
-
.awg_area_mm2(awg : String) : Float64
Returns the conductor cross-section area in mm^2 of a solid AWG size.
-
.awg_diameter_mm(awg : String) : Float64
Returns the bare conductor diameter in millimetres of a solid AWG size, from the ASTM B258 definition
d(n) = 0.005 in * 92^((36-n)/39). -
.awg_resistance_ohm_per_1000ft(awg : String, temperature_c : Float64 = 20.0) : Float64
Returns the copper resistance in ohms per 1000 ft at temperature_c (-60 to 200 degC; 20 gives the table value).
-
.blast_count(runtime_seconds : Float64, blast_seconds : Float64) : Int32
Returns how many whole blasts of blast_seconds fit in runtime_seconds.
-
.combine_levels(levels_db : Enumerable(Float64)) : Float64
Adds the levels of incoherent sources (for example two horns sounding together) into one level:
-
.combine_levels(*levels_db : Float64) : Float64
Same as
.combine_levels(Enumerable), taking the levels as arguments. -
.compressor_recovery_linear_seconds(tank_gallons : Float64, cut_in_psi : Float64, cut_out_psi : Float64, compressor_cfm : Float64, cfm_at_zero_psi : Float64, rated_psi : Float64, atmospheric_psi : Float64 = ATMOSPHERIC_PSI) : Float64
.compressor_recovery_secondswith a linear flow curve: delivery falls linearly from cfm_at_zero_psi at 0 psi to compressor_cfm at rated_psi,q(p) = a + b*p. -
.compressor_recovery_seconds(tank_gallons : Float64, cut_in_psi : Float64, cut_out_psi : Float64, compressor_cfm : Float64, atmospheric_psi : Float64 = ATMOSPHERIC_PSI) : Float64
Returns the seconds a compressor needs to refill a tank from cut_in_psi to cut_out_psi, assuming it delivers a constant compressor_cfm of free air over the whole range:
-
.distance_for_spl(source_db : Float64, target_db : Float64, ref_distance : Float64, unit : String = FEET, absorption_db_per_km : Float64 = 0.0) : Float64
Returns the distance at which the level falls to target_db; the inverse of
.spl_at_distance. -
.distance_ratio_loss(ratio : Float64) : Float64
Returns the free-field level change in dB when the distance is multiplied by ratio:
20*log10(ratio). -
.doubling_loss : Float64
Returns the free-field loss for each doubling of distance,
20*log10(2), about 6.02 dB. -
.free_air_volume_cu_ft(tank_gallons : Float64, start_psi : Float64, end_psi : Float64, atmospheric_psi : Float64 = ATMOSPHERIC_PSI) : Float64
Returns the free air (cubic feet at atmospheric pressure) released while a tank drops from start_psi to end_psi, from Boyle's law:
-
.spl_at_distance(source_db : Float64, distance : Float64, ref_distance : Float64, unit : String = FEET, absorption_db_per_km : Float64 = 0.0) : Float64
Estimates the sound pressure level at distance from a level source_db known at ref_distance, using the free-field inverse-square law plus an optional atmospheric absorption term on the path beyond ref_distance:
-
.suggest_awg(amps : Float64, one_way_length : Float64, system_voltage : Float64, max_drop_pct : Float64 = 3.0, unit : String = FEET, temperature_c : Float64 = 20.0) : WireSuggestion
Returns the smallest copper gauge from
AWG_SIZESwhose round-trip voltage drop stays within max_drop_pct (0 < x <= 50; 3 is a common budget) of system_voltage (typically 12 or 24). -
.tank_runtime_seconds(tank_gallons : Float64, start_psi : Float64, cutoff_psi : Float64, horn_cfm : Float64, atmospheric_psi : Float64 = ATMOSPHERIC_PSI) : Float64
Returns the seconds of continuous horn time from a tank at start_psi down to cutoff_psi (the lowest gauge pressure at which the horn still sounds acceptably) for a horn consuming horn_cfm of free air:
-
.voltage_drop(amps : Float64, one_way_length : Float64, awg : String, unit : String = FEET, temperature_c : Float64 = 20.0) : Float64
Returns the voltage lost in a two-conductor copper run of one_way_length (in unit) carrying amps:
Class Method Detail
Returns the conductor cross-section area in mm^2 of a solid AWG size.
Returns the bare conductor diameter in millimetres of a solid AWG size,
from the ASTM B258 definition d(n) = 0.005 in * 92^((36-n)/39). awg is
a label such as "10", "10 AWG", "1/0" or "0000".
Returns the copper resistance in ohms per 1000 ft at temperature_c
(-60 to 200 degC; 20 gives the table value). It is computed as
R = rho*L/A with a linear temperature correction
R_T = R_20 * (1 + 0.00393*(T - 20)), and agrees with published solid
copper AWG tables to within about 1 %.
Returns how many whole blasts of blast_seconds fit in runtime_seconds. A tiny epsilon keeps exact divisions such as 10/2 from being lost to floating-point rounding.
Adds the levels of incoherent sources (for example two horns sounding together) into one level:
L = 10*log10(sum(10^(Li/10)))
Two equal sources add about 3.01 dB; they do not double the decibels. At least one level is required.
Trainhorn.combine_levels([100.0, 100.0]) # => 103.01029995663981
Same as .combine_levels(Enumerable), taking the levels as arguments.
.compressor_recovery_seconds with a linear flow curve: delivery falls
linearly from cfm_at_zero_psi at 0 psi to compressor_cfm at
rated_psi, q(p) = a + b*p. Integrating dt = (V_tank / P_atm) dp / q(p)
gives
t = V_tank / P_atm * ln(q(cut_out) / q(cut_in)) / b * 60 (b != 0)
cfm_at_zero_psi must be at least compressor_cfm, rated_psi must be
0, and the curve must still deliver air at cut_out_psi. A flat curve (cfm_at_zero_psi == compressor_cfm) gives the constant-flow result.
Returns the seconds a compressor needs to refill a tank from cut_in_psi to cut_out_psi, assuming it delivers a constant compressor_cfm of free air over the whole range:
t = V_free / compressor_cfm * 60
Use the CFM the manufacturer rates at (or near) your cut-out pressure; output falls as pressure rises, so a 0 psi rating gives an optimistic time.
Returns the distance at which the level falls to target_db; the inverse
of .spl_at_distance. Without absorption it is the closed form
d = ref_distance * 10^((source_db - target_db)/20)
With absorption there is no elementary closed form, so it is solved by bisection between the free-field answer and ref_distance. target_db may be higher than source_db, giving a distance closer than ref_distance. The result is in unit.
Returns the free-field level change in dB when the distance is multiplied
by ratio: 20*log10(ratio). A ratio of 10 gives 20 dB. ratio must be
greater than 0.
Returns the free-field loss for each doubling of distance,
20*log10(2), about 6.02 dB.
Returns the free air (cubic feet at atmospheric pressure) released while a tank drops from start_psi to end_psi, from Boyle's law:
V_free = tank_gallons * 0.13368 * (start_psi - end_psi) / atmospheric_psi
Pressures are gauge psi (as read on a dial); start_psi must be greater than end_psi and end_psi >= 0.
Estimates the sound pressure level at distance from a level source_db known at ref_distance, using the free-field inverse-square law plus an optional atmospheric absorption term on the path beyond ref_distance:
L = source_db - 20*log10(d/d_ref) - absorption_db_per_km*(d_m - d_ref_m)/1000
Both distances are in unit ("ft" or "m") and must be greater than 0.
Horn ratings are commonly quoted "at 10 ft" or "at 1 m"; pass that as
ref_distance. absorption_db_per_km must be >= 0; see
AIR_ABSORPTION_DB_PER_KM. The model assumes a point source in open air
with no reflections, wind or barriers, so real outdoor levels can differ
by several dB.
Trainhorn.spl_at_distance(150.0, 100.0, 10.0) # => 130.0
Returns the smallest copper gauge from AWG_SIZES whose round-trip
voltage drop stays within max_drop_pct (0 < x <= 50; 3 is a common
budget) of system_voltage (typically 12 or 24).
It checks voltage drop only, not ampacity or fuse sizing; always size the
fuse to protect the wire you choose. Raises InvalidInputError if the
input is invalid or even 4/0 cannot meet the budget.
Trainhorn.suggest_awg(30.0, 10.0, 12.0).awg # => "6"
Returns the seconds of continuous horn time from a tank at start_psi down to cutoff_psi (the lowest gauge pressure at which the horn still sounds acceptably) for a horn consuming horn_cfm of free air:
t = free_air_volume_cu_ft(...) / horn_cfm * 60
The model assumes isothermal expansion, a constant horn consumption and the compressor off while the horn sounds, so treat the result as an upper estimate.
Trainhorn.tank_runtime_seconds(5.0, 150.0, 110.0, 10.0) # => 10.91566866267465
Returns the voltage lost in a two-conductor copper run of one_way_length (in unit) carrying amps:
V_drop = amps * R_per_length * 2 * one_way_length
Current flows out and back, so the conductor length is twice the one-way run.