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:

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.cr
trainhorn/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_awg considers, 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

Class Method Detail

def self.awg_area_mm2(awg : String) : Float64 #

Returns the conductor cross-section area in mm^2 of a solid AWG size.


[View source]
def self.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 is a label such as "10", "10 AWG", "1/0" or "0000".


[View source]
def self.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). 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 %.


[View source]
def self.blast_count(runtime_seconds : Float64, blast_seconds : Float64) : Int32 #

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.


[View source]
def self.combine_levels(levels_db : Enumerable(Float64)) : Float64 #

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

[View source]
def self.combine_levels(*levels_db : Float64) : Float64 #

Same as .combine_levels(Enumerable), taking the levels as arguments.


[View source]
def self.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_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.


[View source]
def self.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:

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.


[View source]
def self.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. 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.


[View source]
def self.distance_ratio_loss(ratio : Float64) : Float64 #

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.


[View source]
def self.doubling_loss : Float64 #

Returns the free-field loss for each doubling of distance, 20*log10(2), about 6.02 dB.


[View source]
def self.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:

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.


[View source]
def self.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:

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

[View source]
def self.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_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"

[View source]
def self.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:

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

[View source]
def self.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:

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.


[View source]