Module

TrainHorn.Calc

Package
purescript-train-horn
Repository
train-horn/purescript-train-horn

Small, dependency-light calculators for train horn setups on trucks and other vehicles: how loud a horn is at a distance, how long an air tank lasts and refills, and which copper wire gauge keeps the voltage drop in budget.

This module re-exports everything from:

  • TrainHorn.Calc.Acoustics: SPL at a distance (inverse-square law with optional air absorption), its inverse, the per-doubling loss and the addition of incoherent levels;
  • TrainHorn.Calc.AirSystem: free-air volume (Boyle's law), tank runtime, blast count and compressor recovery time;
  • TrainHorn.Calc.Electrical: AWG diameter, area, resistance, voltage drop and the smallest gauge for a drop budget;
  • TrainHorn.Calc.Validate: length units and input checks.

Every function that takes user input returns Either String Number (or Either String of a record or Int): Left carries a readable message for invalid input such as a zero distance, a non-finite number or a start pressure below the cut-off.

It is a faithful port of the Python package trainhorn-calc and is tested against the same reference values to within 1e-9. Browser versions of these calculators: interactive calculators.

Results are physics-based estimates, not measurements, and not legal advice on horn use.

import TrainHorn.Calc

splAtDistance 150.0 100.0 10.0                 -- Right 130.0
tankRuntimeSeconds 5.0 150.0 110.0 10.0 atmosphericPsi  -- Right 10.91...
map _.awg (suggestAwg 30.0 10.0 12.0 3.0 Feet 20.0)    -- Right "6"

Re-exports from TrainHorn.Calc.Acoustics

#splAtDistanceWithAbsorption Source

splAtDistanceWithAbsorption :: Number -> Number -> Number -> LengthUnit -> Number -> Either String Number

SPL at distance with optional air absorption in dB/km (>= 0, see airAbsorptionDbPerKm). The unit applies to both distances and is used to convert them to metres for the absorption term.

#splAtDistance Source

splAtDistance :: Number -> Number -> Number -> Either String Number

Free-field SPL at distance from a level sourceDb known at refDistance (same unit for both distances): sourceDb - 20 * log10(distance / refDistance).

splAtDistance 150.0 100.0 10.0 == Right 130.0  -- 150 dB at 10 ft -> 130 dB at 100 ft

#doublingLoss Source

doublingLoss :: Number

Free-field loss for each doubling of distance: 20 * log10(2), about 6.02 dB.

#distanceRatioLoss Source

distanceRatioLoss :: Number -> Either String Number

Free-field level change in dB when the distance is multiplied by ratio (> 0): 20 * log10(ratio). A ratio of 10 gives 20 dB.

#distanceForSplWithAbsorption Source

distanceForSplWithAbsorption :: Number -> Number -> Number -> LengthUnit -> Number -> Either String Number

Distance at which the level falls to targetDb with air absorption. With absorption there is no elementary closed form, so the root is found by bisection between the free-field answer and refDistance (the level is strictly decreasing with distance), to a relative width of 1e-12.

#distanceForSpl Source

distanceForSpl :: Number -> Number -> Number -> Either String Number

Free-field distance at which the level falls to targetDb; the inverse of splAtDistance: refDistance * 10 ^ ((sourceDb - targetDb) / 20). The result is in the same unit as refDistance.

#combineLevels Source

combineLevels :: Array Number -> Either String Number

Combines incoherent sources (for example two horns) into one level: 10 * log10(sum(10 ^ (L_i / 10))). Two equal sources add about 3.01 dB, not double the decibels. An empty array is a Left.

#airAbsorptionDbPerKm Source

airAbsorptionDbPerKm :: Array (Tuple Int Number)

Approximate atmospheric absorption in dB/km at 10 degC and 70 % relative humidity (an ISO 9613-2 table condition, from the ISO 9613-1 equations), keyed by octave-band centre frequency in Hz. Train horn chords sit mostly between about 250 Hz and 600 Hz, where absorption is only 1-2 dB/km. Rounded, typical values: use them as a rough guide only.

Re-exports from TrainHorn.Calc.AirSystem

#tankRuntimeSeconds Source

tankRuntimeSeconds :: Number -> Number -> Number -> Number -> Number -> Either String Number

Seconds of continuous horn time from startPsi down to cutoffPsi for a horn drawing hornCfm of free air: freeAirVolumeCuFt / hornCfm * 60.

tankRuntimeSeconds 5.0 150.0 110.0 10.0 atmosphericPsi  -- Right 10.9156...

#freeAirVolumeCuFt Source

freeAirVolumeCuFt :: Number -> Number -> Number -> Number -> Either String Number

Free air in cubic feet (at atmospheric pressure) released while a tank of tankGallons US gallons drops from startPsi to endPsi gauge: tankGallons * 0.13368 * (startPsi - endPsi) / atmPsi.

Arguments: tank gallons (> 0), start psi, end psi (>= 0, below start), atmospheric psi (> 0, usually atmosphericPsi).

#cubicFeetPerGallon Source

cubicFeetPerGallon :: Number

Cubic feet in one US liquid gallon: 231 in^3 / 1728 in^3.

#compressorRecoverySeconds Source

compressorRecoverySeconds :: Number -> Number -> Number -> Number -> Number -> Either String Number

Seconds for a compressor delivering a constant compressorCfm of free air to refill the tank from cutInPsi to cutOutPsi: V_free / compressorCfm * 60. Use the CFM rated at (or near) your cut-out pressure; a 0 psi rating gives an optimistic time.

Arguments: tank gallons, cut-in psi, cut-out psi (> cut-in), compressor CFM, atmospheric psi.

#compressorRecoveryLinearSeconds Source

compressorRecoveryLinearSeconds :: Number -> Number -> Number -> Number -> Number -> Number -> Number -> Either String Number

Recovery time when compressor output falls linearly with pressure, from cfmAtZeroPsi at 0 psi to compressorCfm at ratedPsi: q(p) = q0 + b * p. Integrating dt = (V_tank / P_atm) dp / q(p) gives

t = V_tank / P_atm * ln(q(p_out) / q(p_in)) / b * 60     (b /= 0)

Arguments: tank gallons, cut-in psi, cut-out psi, compressor CFM at the rated pressure, CFM at 0 psi (>= compressor CFM), rated psi (> 0), atmospheric psi.

#blastCount Source

blastCount :: Number -> Number -> Either String Int

Whole blasts of blastSeconds that fit in runtimeSeconds. A 1e-9 epsilon keeps exact divisions such as 0.9 / 0.3 from rounding down.

#atmosphericPsi Source

atmosphericPsi :: Number

Standard atmosphere at sea level in psi (14.696). Pass a lower value for altitude.

Re-exports from TrainHorn.Calc.Electrical

#WireSuggestion Source

type WireSuggestion = { allowedDropPct :: Number, amps :: Number, awg :: String, oneWayLength :: Number, systemVoltage :: Number, unit :: LengthUnit, voltageDropPct :: Number, voltageDropV :: Number }

Result of suggestAwg: the chosen gauge, its drop in volts and percent, and the inputs it was computed for.

#voltageDrop Source

voltageDrop :: Number -> Number -> String -> LengthUnit -> Number -> Either String Number

Volts lost in a two-conductor copper run: amps * R_per_ft * 2 * oneWayLength.

Arguments: amps (> 0), one-way length (> 0), AWG label, length unit, conductor temperature in degC.

#suggestAwg Source

suggestAwg :: Number -> Number -> Number -> Number -> LengthUnit -> Number -> Either String WireSuggestion

Smallest copper AWG from awgSizes whose round-trip voltage drop stays within maxDropPct percent of systemVoltage.

Arguments: amps, one-way length, system volts (> 0, typically 12 or 24), allowed drop in percent (0 < x <= 50, 3 is common), length unit, conductor temperature in degC. A Left also results if even 4/0 cannot meet the budget.

map _.awg (suggestAwg 30.0 10.0 12.0 3.0 Feet 20.0) == Right "6"

#copperTempCoeffPerC Source

copperTempCoeffPerC :: Number

Temperature coefficient of resistance of annealed copper near 20 degC.

#copperResistivityOhmM Source

copperResistivityOhmM :: Number

Annealed copper resistivity, 100 % IACS, at 20 degC, in ohm*m.

#awgSizes Source

awgSizes :: Array String

Gauges considered by suggestAwg, thinnest to thickest: the sizes commonly sold as automotive primary wire and battery cable. Odd sizes still work in the other functions.

#awgResistanceOhmPer1000ft Source

awgResistanceOhmPer1000ft :: String -> Number -> Either String Number

Copper resistance in ohms per 1000 ft at the given conductor temperature in degC (-60 to 200; use 20.0 for the table value).

#awgDiameterMM Source

awgDiameterMM :: String -> Either String Number

Bare conductor diameter in millimetres of a solid AWG size. The label may be "10", "10 AWG", "6awg", "1/0", "00", "0000", etc.

#awgAreaMM2 Source

awgAreaMM2 :: String -> Either String Number

Conductor cross-section area in mm^2: pi * d^2 / 4.

Re-exports from TrainHorn.Calc.Validate

#LengthUnit Source

data LengthUnit

A length unit for distances and cable runs: international feet or metres.

Constructors

Instances

#toMeters Source

toMeters :: LengthUnit -> Number -> Number

Converts a length in the given unit to metres.

#positive Source

positive :: String -> Number -> Either String Number

Right x when x is finite and greater than 0.

#parseUnit Source

parseUnit :: String -> Either String LengthUnit

Parses a unit label. Surrounding spaces and letter case are ignored, so "ft", " FT " and "m" are accepted; anything else is a Left.

#nonNegative Source

nonNegative :: String -> Number -> Either String Number

Right x when x is finite and 0 or greater.

#metersPerFoot Source

metersPerFoot :: Number

The exact length of one international foot in metres (0.3048).

#log10 Source

log10 :: Number -> Number

Base-10 logarithm.

#fromMeters Source

fromMeters :: LengthUnit -> Number -> Number

Converts a length in metres to the given unit.

#finite Source

finite :: String -> Number -> Either String Number

Right x when x is finite (not NaN or infinite); the first argument names the parameter in the error message.