trainhorn-calc 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Train Horn (train-horn.com)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: trainhorn-calc
3
+ Version: 1.0.0
4
+ Summary: Dependency-free calculators for train horn setups: SPL vs distance, air tank runtime, compressor recovery and copper wire gauge.
5
+ Author-email: Train Horn <editorial@train-horn.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://train-horn.com/
8
+ Project-URL: Documentation, https://train-horn.com/tools/
9
+ Project-URL: Source, https://github.com/train-horn/trainhorn-calc
10
+ Keywords: train horn,decibel,inverse square law,air tank,compressor,AWG,voltage drop
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: Topic :: Scientific/Engineering :: Physics
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.8
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Dynamic: license-file
22
+
23
+ # trainhorn-calc
24
+
25
+ Small, dependency-free Python calculators for planning a vehicle train horn setup:
26
+
27
+ - **acoustics**: sound pressure level (SPL) at a distance with the inverse-square law, the inverse (distance for a target dB), optional air absorption, dB lost per doubling of distance, and combining several horns.
28
+ - **airsystem**: air tank horn runtime and compressor refill time from Boyle's law (free-air volume).
29
+ - **electrical**: the smallest copper AWG size that keeps a 12 V / 24 V run within a voltage-drop budget (3 % by default).
30
+ - **cli**: a `trainhorn-calc` command with one subcommand per calculator.
31
+
32
+ Pure Python 3.8+, no dependencies, type hints included (`py.typed`). MIT licensed.
33
+
34
+ Results are engineering estimates from simple physical models. They are not measurements, and they are not legal advice about horn use.
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ conda install -c trainhorn trainhorn-calc # from the anaconda.org user channel
40
+ # or, from a source checkout:
41
+ pip install .
42
+ ```
43
+
44
+ ## Command line
45
+
46
+ ```console
47
+ $ trainhorn-calc spl 150 100
48
+ 130.0 dB at 100 ft
49
+
50
+ $ trainhorn-calc distance 150 90 --absorption 1.9
51
+ 90 dB is reached at about 6,491.3 ft
52
+
53
+ $ trainhorn-calc runtime 5 150 110 10 --blast 2
54
+ 10.9 s of horn time (1.82 cu ft of free air); 5 blasts of 2 s
55
+
56
+ $ trainhorn-calc recovery 2 110 150 1.0
57
+ 43.7 s to refill from 110 to 150 psi
58
+
59
+ $ trainhorn-calc wire 30 10
60
+ 6 AWG copper: 0.24 V drop (1.98% of 12 V, limit 3%)
61
+
62
+ $ trainhorn-calc combine 150 150
63
+ 153.0 dB combined
64
+
65
+ $ trainhorn-calc wire 30 10 --volts 24 --json
66
+ { "awg": "10", "voltage_drop_pct": 2.497..., ... }
67
+ ```
68
+
69
+ Subcommands: `spl`, `distance`, `doubling`, `combine`, `runtime`, `recovery`, `wire`. Run `trainhorn-calc <subcommand> --help` for every option (`--unit ft|m`, `--ref-distance`, `--absorption`, `--atm-psi`, `--cfm-at-zero`, `--rated-psi`, `--volts`, `--max-drop`, `--temp-c`). Every subcommand accepts `--json`. Invalid input prints `error: ...` and exits with status 2. `python -m trainhorn_calc` works too.
70
+
71
+ ## Python API
72
+
73
+ ```python
74
+ from trainhorn_calc import (
75
+ spl_at_distance, distance_for_spl, db_doubling_loss, combine_levels,
76
+ tank_runtime_seconds, compressor_recovery_seconds, blast_count,
77
+ suggest_awg, voltage_drop, InputError,
78
+ )
79
+
80
+ spl_at_distance(150, 100) # 130.0 (150 dB at 10 ft -> 100 ft)
81
+ spl_at_distance(120, 50, ref_distance=1, unit="m", absorption_db_per_km=1.9)
82
+ distance_for_spl(150, 130) # 100.0 ft
83
+ db_doubling_loss() # 6.0206 dB
84
+ combine_levels([150, 150]) # 153.01 dB
85
+
86
+ secs = tank_runtime_seconds(tank_gallons=5, start_psi=150, cutoff_psi=110, horn_cfm=10) # 10.92
87
+ blast_count(secs, 2) # 5
88
+ compressor_recovery_seconds(2, cut_in_psi=110, cut_out_psi=150, compressor_cfm=1.0) # 43.7
89
+ compressor_recovery_seconds(2, 110, 150, 1.0, cfm_at_zero_psi=2.0, rated_psi=150) # 38.7
90
+
91
+ s = suggest_awg(amps=30, one_way_length=10, system_voltage=12) # WireSuggestion(awg='6', ...)
92
+ s.voltage_drop_pct, s.as_dict()
93
+ ```
94
+
95
+ All functions raise `trainhorn_calc.InputError` (a `ValueError`) with a clear message for bad input: non-numbers, NaN/inf, zero or negative distances, a start pressure below the cut-off, unknown units or gauges, or a load no gauge up to 4/0 can carry within the budget.
96
+
97
+ ### Formulas and assumptions
98
+
99
+ | Calculator | Formula | Main assumptions |
100
+ |---|---|---|
101
+ | SPL at distance | `L = L_ref - 20*log10(d/d_ref) - a*(d - d_ref)/1000` (a in dB/km, distances in m for that term) | Point source, free field, no ground reflection or wind |
102
+ | Distance for SPL | `d = d_ref * 10**((L_ref - L)/20)`; bisection when `a > 0` | Same as above |
103
+ | Free air | `V_free = V_tank * (P_start - P_end) / P_atm` (gauge psi, P_atm = 14.696) | Isothermal (Boyle's law); slight overestimate for fast blasts |
104
+ | Horn runtime | `t = V_free / horn_CFM * 60` | Constant consumption above the cut-off; compressor off |
105
+ | Compressor recovery | `t = V_free / CFM * 60`; optional linear CFM-vs-pressure model, integrated in closed form | Rated CFM is free-air delivery |
106
+ | Wire gauge | `V_drop = I * R(AWG) * 2 * L_one_way`; R from the AWG diameter formula and copper at 1.7241e-8 ohm*m | Voltage drop only: check ampacity and fuse size separately |
107
+
108
+ `AIR_ABSORPTION_DB_PER_KM` in `trainhorn_calc.acoustics` gives rounded octave-band absorption values (ISO 9613-2 reference condition, 10 degC / 70 % RH). Train horn chords sit around 250 to 600 Hz, where absorption is roughly 1 to 2 dB/km.
109
+
110
+ ## Tests
111
+
112
+ ```bash
113
+ python -m unittest discover -s tests -v
114
+ ```
115
+
116
+ 49 tests (unittest plus the docstring examples): known values, inverse round-trips, CLI output and edge cases. No pytest required.
117
+
118
+ ## Conda package
119
+
120
+ The package on the anaconda.org `trainhorn` channel is a standard `noarch: python` build of this source. Its build script and recipe are not part of this repository; to use the library from a checkout, run `pip install .`.
121
+
122
+ ## Documentation
123
+
124
+ Full documentation with derivations and worked examples: https://docs.page/train-horn/trainhorn-calc
125
+
126
+ ## Related
127
+
128
+ - [Train Horn calculators](https://train-horn.com/tools/): web versions of these calculators (decibel distance, air tank runtime, compressor recovery, wire gauge and more) that run in the browser.
129
+ - [train-horn.com](https://train-horn.com/): an independent reference on train horns, including state laws and install guides.
130
+
131
+ ## License
132
+
133
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,111 @@
1
+ # trainhorn-calc
2
+
3
+ Small, dependency-free Python calculators for planning a vehicle train horn setup:
4
+
5
+ - **acoustics**: sound pressure level (SPL) at a distance with the inverse-square law, the inverse (distance for a target dB), optional air absorption, dB lost per doubling of distance, and combining several horns.
6
+ - **airsystem**: air tank horn runtime and compressor refill time from Boyle's law (free-air volume).
7
+ - **electrical**: the smallest copper AWG size that keeps a 12 V / 24 V run within a voltage-drop budget (3 % by default).
8
+ - **cli**: a `trainhorn-calc` command with one subcommand per calculator.
9
+
10
+ Pure Python 3.8+, no dependencies, type hints included (`py.typed`). MIT licensed.
11
+
12
+ Results are engineering estimates from simple physical models. They are not measurements, and they are not legal advice about horn use.
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ conda install -c trainhorn trainhorn-calc # from the anaconda.org user channel
18
+ # or, from a source checkout:
19
+ pip install .
20
+ ```
21
+
22
+ ## Command line
23
+
24
+ ```console
25
+ $ trainhorn-calc spl 150 100
26
+ 130.0 dB at 100 ft
27
+
28
+ $ trainhorn-calc distance 150 90 --absorption 1.9
29
+ 90 dB is reached at about 6,491.3 ft
30
+
31
+ $ trainhorn-calc runtime 5 150 110 10 --blast 2
32
+ 10.9 s of horn time (1.82 cu ft of free air); 5 blasts of 2 s
33
+
34
+ $ trainhorn-calc recovery 2 110 150 1.0
35
+ 43.7 s to refill from 110 to 150 psi
36
+
37
+ $ trainhorn-calc wire 30 10
38
+ 6 AWG copper: 0.24 V drop (1.98% of 12 V, limit 3%)
39
+
40
+ $ trainhorn-calc combine 150 150
41
+ 153.0 dB combined
42
+
43
+ $ trainhorn-calc wire 30 10 --volts 24 --json
44
+ { "awg": "10", "voltage_drop_pct": 2.497..., ... }
45
+ ```
46
+
47
+ Subcommands: `spl`, `distance`, `doubling`, `combine`, `runtime`, `recovery`, `wire`. Run `trainhorn-calc <subcommand> --help` for every option (`--unit ft|m`, `--ref-distance`, `--absorption`, `--atm-psi`, `--cfm-at-zero`, `--rated-psi`, `--volts`, `--max-drop`, `--temp-c`). Every subcommand accepts `--json`. Invalid input prints `error: ...` and exits with status 2. `python -m trainhorn_calc` works too.
48
+
49
+ ## Python API
50
+
51
+ ```python
52
+ from trainhorn_calc import (
53
+ spl_at_distance, distance_for_spl, db_doubling_loss, combine_levels,
54
+ tank_runtime_seconds, compressor_recovery_seconds, blast_count,
55
+ suggest_awg, voltage_drop, InputError,
56
+ )
57
+
58
+ spl_at_distance(150, 100) # 130.0 (150 dB at 10 ft -> 100 ft)
59
+ spl_at_distance(120, 50, ref_distance=1, unit="m", absorption_db_per_km=1.9)
60
+ distance_for_spl(150, 130) # 100.0 ft
61
+ db_doubling_loss() # 6.0206 dB
62
+ combine_levels([150, 150]) # 153.01 dB
63
+
64
+ secs = tank_runtime_seconds(tank_gallons=5, start_psi=150, cutoff_psi=110, horn_cfm=10) # 10.92
65
+ blast_count(secs, 2) # 5
66
+ compressor_recovery_seconds(2, cut_in_psi=110, cut_out_psi=150, compressor_cfm=1.0) # 43.7
67
+ compressor_recovery_seconds(2, 110, 150, 1.0, cfm_at_zero_psi=2.0, rated_psi=150) # 38.7
68
+
69
+ s = suggest_awg(amps=30, one_way_length=10, system_voltage=12) # WireSuggestion(awg='6', ...)
70
+ s.voltage_drop_pct, s.as_dict()
71
+ ```
72
+
73
+ All functions raise `trainhorn_calc.InputError` (a `ValueError`) with a clear message for bad input: non-numbers, NaN/inf, zero or negative distances, a start pressure below the cut-off, unknown units or gauges, or a load no gauge up to 4/0 can carry within the budget.
74
+
75
+ ### Formulas and assumptions
76
+
77
+ | Calculator | Formula | Main assumptions |
78
+ |---|---|---|
79
+ | SPL at distance | `L = L_ref - 20*log10(d/d_ref) - a*(d - d_ref)/1000` (a in dB/km, distances in m for that term) | Point source, free field, no ground reflection or wind |
80
+ | Distance for SPL | `d = d_ref * 10**((L_ref - L)/20)`; bisection when `a > 0` | Same as above |
81
+ | Free air | `V_free = V_tank * (P_start - P_end) / P_atm` (gauge psi, P_atm = 14.696) | Isothermal (Boyle's law); slight overestimate for fast blasts |
82
+ | Horn runtime | `t = V_free / horn_CFM * 60` | Constant consumption above the cut-off; compressor off |
83
+ | Compressor recovery | `t = V_free / CFM * 60`; optional linear CFM-vs-pressure model, integrated in closed form | Rated CFM is free-air delivery |
84
+ | Wire gauge | `V_drop = I * R(AWG) * 2 * L_one_way`; R from the AWG diameter formula and copper at 1.7241e-8 ohm*m | Voltage drop only: check ampacity and fuse size separately |
85
+
86
+ `AIR_ABSORPTION_DB_PER_KM` in `trainhorn_calc.acoustics` gives rounded octave-band absorption values (ISO 9613-2 reference condition, 10 degC / 70 % RH). Train horn chords sit around 250 to 600 Hz, where absorption is roughly 1 to 2 dB/km.
87
+
88
+ ## Tests
89
+
90
+ ```bash
91
+ python -m unittest discover -s tests -v
92
+ ```
93
+
94
+ 49 tests (unittest plus the docstring examples): known values, inverse round-trips, CLI output and edge cases. No pytest required.
95
+
96
+ ## Conda package
97
+
98
+ The package on the anaconda.org `trainhorn` channel is a standard `noarch: python` build of this source. Its build script and recipe are not part of this repository; to use the library from a checkout, run `pip install .`.
99
+
100
+ ## Documentation
101
+
102
+ Full documentation with derivations and worked examples: https://docs.page/train-horn/trainhorn-calc
103
+
104
+ ## Related
105
+
106
+ - [Train Horn calculators](https://train-horn.com/tools/): web versions of these calculators (decibel distance, air tank runtime, compressor recovery, wire gauge and more) that run in the browser.
107
+ - [train-horn.com](https://train-horn.com/): an independent reference on train horns, including state laws and install guides.
108
+
109
+ ## License
110
+
111
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,36 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "trainhorn-calc"
7
+ version = "1.0.0"
8
+ description = "Dependency-free calculators for train horn setups: SPL vs distance, air tank runtime, compressor recovery and copper wire gauge."
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ authors = [{name = "Train Horn", email = "editorial@train-horn.com"}]
12
+ requires-python = ">=3.8"
13
+ keywords = ["train horn", "decibel", "inverse square law", "air tank", "compressor", "AWG", "voltage drop"]
14
+ classifiers = [
15
+ "License :: OSI Approved :: MIT License",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3 :: Only",
18
+ "Operating System :: OS Independent",
19
+ "Intended Audience :: End Users/Desktop",
20
+ "Topic :: Scientific/Engineering :: Physics",
21
+ "Typing :: Typed",
22
+ ]
23
+
24
+ [project.urls]
25
+ Homepage = "https://train-horn.com/"
26
+ Documentation = "https://train-horn.com/tools/"
27
+ Source = "https://github.com/train-horn/trainhorn-calc"
28
+
29
+ [project.scripts]
30
+ trainhorn-calc = "trainhorn_calc.cli:main"
31
+
32
+ [tool.setuptools.packages.find]
33
+ where = ["src"]
34
+
35
+ [tool.setuptools.package-data]
36
+ trainhorn_calc = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,38 @@
1
+ """trainhorn_calc: small, dependency-free calculators for train horn setups.
2
+
3
+ Modules:
4
+
5
+ * :mod:`trainhorn_calc.acoustics` - SPL versus distance (inverse-square law)
6
+ * :mod:`trainhorn_calc.airsystem` - air tank runtime and compressor recovery
7
+ * :mod:`trainhorn_calc.electrical` - copper AWG choice by voltage drop
8
+ * :mod:`trainhorn_calc.cli` - the ``trainhorn-calc`` command
9
+
10
+ Browser versions of these calculators: https://train-horn.com/tools/
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ __version__ = "1.0.0"
16
+
17
+ from ._validate import InputError
18
+ from .acoustics import combine_levels, db_doubling_loss, distance_for_spl, distance_ratio_loss, spl_at_distance
19
+ from .airsystem import blast_count, compressor_recovery_seconds, free_air_volume_cuft, tank_runtime_seconds
20
+ from .electrical import WireSuggestion, awg_resistance_ohm_per_1000ft, suggest_awg, voltage_drop
21
+
22
+ __all__ = [
23
+ "__version__",
24
+ "InputError",
25
+ "spl_at_distance",
26
+ "distance_for_spl",
27
+ "distance_ratio_loss",
28
+ "db_doubling_loss",
29
+ "combine_levels",
30
+ "free_air_volume_cuft",
31
+ "tank_runtime_seconds",
32
+ "blast_count",
33
+ "compressor_recovery_seconds",
34
+ "awg_resistance_ohm_per_1000ft",
35
+ "voltage_drop",
36
+ "suggest_awg",
37
+ "WireSuggestion",
38
+ ]
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,59 @@
1
+ """Shared input validation and unit helpers (internal)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from typing import Any
7
+
8
+ FEET_PER_METER = 3.280839895013123 # exact: 1 ft = 0.3048 m
9
+ METERS_PER_FOOT = 0.3048
10
+
11
+ LENGTH_UNITS = ("ft", "m")
12
+
13
+
14
+ class InputError(ValueError):
15
+ """Raised when a calculator receives an invalid argument.
16
+
17
+ Subclasses :class:`ValueError`, so ``except ValueError`` also catches it.
18
+ """
19
+
20
+
21
+ def number(name: str, value: Any) -> float:
22
+ """Return ``value`` as a finite float or raise :class:`InputError`."""
23
+ if isinstance(value, bool):
24
+ raise InputError(f"{name} must be a number, got a bool")
25
+ try:
26
+ result = float(value)
27
+ except (TypeError, ValueError):
28
+ raise InputError(f"{name} must be a number, got {value!r}") from None
29
+ if not math.isfinite(result):
30
+ raise InputError(f"{name} must be finite, got {value!r}")
31
+ return result
32
+
33
+
34
+ def positive(name: str, value: Any) -> float:
35
+ result = number(name, value)
36
+ if result <= 0:
37
+ raise InputError(f"{name} must be greater than 0, got {result:g}")
38
+ return result
39
+
40
+
41
+ def non_negative(name: str, value: Any) -> float:
42
+ result = number(name, value)
43
+ if result < 0:
44
+ raise InputError(f"{name} must be 0 or greater, got {result:g}")
45
+ return result
46
+
47
+
48
+ def length_unit(unit: Any) -> str:
49
+ if not isinstance(unit, str) or unit.strip().lower() not in LENGTH_UNITS:
50
+ raise InputError(f"unit must be one of {', '.join(LENGTH_UNITS)}; got {unit!r}")
51
+ return unit.strip().lower()
52
+
53
+
54
+ def to_meters(value: float, unit: str) -> float:
55
+ return value * METERS_PER_FOOT if unit == "ft" else value
56
+
57
+
58
+ def from_meters(value: float, unit: str) -> float:
59
+ return value / METERS_PER_FOOT if unit == "ft" else value
@@ -0,0 +1,195 @@
1
+ """Sound pressure level (SPL) versus distance for a horn in open air.
2
+
3
+ Model
4
+ -----
5
+ A horn is treated as a point source radiating into a free field. Sound
6
+ intensity falls with the square of distance (inverse-square law), so the
7
+ sound pressure level falls by ``20 * log10(d2 / d1)`` decibels::
8
+
9
+ L(d) = L_ref - 20 * log10(d / d_ref) - alpha * (d - d_ref)
10
+
11
+ where
12
+
13
+ * ``L_ref`` is the level measured (or rated) at the reference distance
14
+ ``d_ref`` (horn ratings are commonly quoted "at 10 ft" or "at 1 m"),
15
+ * ``alpha`` is an optional atmospheric absorption coefficient in dB per
16
+ kilometre, applied to the extra path beyond ``d_ref`` (default 0).
17
+
18
+ Assumptions and limits
19
+ ----------------------
20
+ * Free field: no ground reflection, walls, wind, temperature gradients or
21
+ barriers. Real outdoor levels can be several dB higher or lower.
22
+ * The source is small compared with the distances involved. Very close to
23
+ the horn (inside roughly one or two horn lengths) the law does not hold.
24
+ * Absorption depends strongly on frequency, temperature and humidity. The
25
+ values in :data:`AIR_ABSORPTION_DB_PER_KM` are rounded, typical figures
26
+ for 10 degC and 70 % relative humidity (one of the conditions tabulated
27
+ in ISO 9613-2, computed from ISO 9613-1). Use them as a rough guide only.
28
+ * Results are estimates, not measurements, and are not a legal noise
29
+ assessment.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import math
35
+ from typing import Dict, Iterable
36
+
37
+ from ._validate import InputError, length_unit, non_negative, number, positive, to_meters
38
+
39
+ __all__ = [
40
+ "AIR_ABSORPTION_DB_PER_KM",
41
+ "spl_at_distance",
42
+ "distance_for_spl",
43
+ "distance_ratio_loss",
44
+ "db_doubling_loss",
45
+ "combine_levels",
46
+ ]
47
+
48
+ #: Approximate atmospheric absorption in dB/km at 10 degC and 70 % RH
49
+ #: (ISO 9613-2 Table 2 condition, from the ISO 9613-1 equations). Keys are octave
50
+ #: band centre frequencies in Hz. Train horn chords sit mostly between about
51
+ #: 250 Hz and 600 Hz, where absorption is only 1-2 dB/km, so it matters only
52
+ #: at long range.
53
+ AIR_ABSORPTION_DB_PER_KM: Dict[int, float] = {
54
+ 63: 0.1,
55
+ 125: 0.4,
56
+ 250: 1.0,
57
+ 500: 1.9,
58
+ 1000: 3.7,
59
+ 2000: 9.7,
60
+ 4000: 32.8,
61
+ 8000: 117.0,
62
+ }
63
+
64
+
65
+ def _absorption_term(distance_m: float, ref_m: float, absorption_db_per_km: float) -> float:
66
+ return absorption_db_per_km * (distance_m - ref_m) / 1000.0
67
+
68
+
69
+ def spl_at_distance(
70
+ source_db: float,
71
+ distance: float,
72
+ ref_distance: float = 10,
73
+ unit: str = "ft",
74
+ absorption_db_per_km: float = 0.0,
75
+ ) -> float:
76
+ """Estimate the SPL at ``distance`` from a level known at ``ref_distance``.
77
+
78
+ Formula: ``L = source_db - 20*log10(distance/ref_distance)
79
+ - absorption_db_per_km * (distance - ref_distance) / 1000`` with the
80
+ distances converted to metres for the absorption term.
81
+
82
+ Args:
83
+ source_db: Level in dB at ``ref_distance`` (e.g. 150 for "150 dB at 10 ft").
84
+ distance: Distance at which to estimate the level (> 0).
85
+ ref_distance: Distance at which ``source_db`` applies (> 0). Default 10.
86
+ unit: ``"ft"`` (default) or ``"m"``; applies to both distances.
87
+ absorption_db_per_km: Optional air absorption in dB/km (>= 0). See
88
+ :data:`AIR_ABSORPTION_DB_PER_KM`. Default 0 (pure inverse-square).
89
+
90
+ Returns:
91
+ Estimated level in dB.
92
+
93
+ Example:
94
+ >>> round(spl_at_distance(150, 100), 1)
95
+ 130.0
96
+ """
97
+ source_db = number("source_db", source_db)
98
+ distance = positive("distance", distance)
99
+ ref_distance = positive("ref_distance", ref_distance)
100
+ unit = length_unit(unit)
101
+ absorption_db_per_km = non_negative("absorption_db_per_km", absorption_db_per_km)
102
+
103
+ level = source_db - 20.0 * math.log10(distance / ref_distance)
104
+ if absorption_db_per_km:
105
+ level -= _absorption_term(
106
+ to_meters(distance, unit), to_meters(ref_distance, unit), absorption_db_per_km
107
+ )
108
+ return level
109
+
110
+
111
+ def distance_for_spl(
112
+ source_db: float,
113
+ target_db: float,
114
+ ref_distance: float = 10,
115
+ unit: str = "ft",
116
+ absorption_db_per_km: float = 0.0,
117
+ ) -> float:
118
+ """Distance at which the level falls to ``target_db``; inverse of :func:`spl_at_distance`.
119
+
120
+ Without absorption the closed form is
121
+ ``d = ref_distance * 10 ** ((source_db - target_db) / 20)``.
122
+ With absorption the equation has no elementary closed form, so it is
123
+ solved by bisection (the level is strictly decreasing with distance).
124
+
125
+ Args:
126
+ source_db: Level in dB at ``ref_distance``.
127
+ target_db: Level you want to find the distance for. May be higher
128
+ than ``source_db`` (the answer is then closer than ``ref_distance``).
129
+ ref_distance: Distance at which ``source_db`` applies (> 0).
130
+ unit: ``"ft"`` or ``"m"``; the result is in the same unit.
131
+ absorption_db_per_km: Optional air absorption in dB/km (>= 0).
132
+
133
+ Returns:
134
+ Distance in ``unit``.
135
+
136
+ Example:
137
+ >>> round(distance_for_spl(150, 130), 6)
138
+ 100.0
139
+ """
140
+ source_db = number("source_db", source_db)
141
+ target_db = number("target_db", target_db)
142
+ ref_distance = positive("ref_distance", ref_distance)
143
+ unit = length_unit(unit)
144
+ absorption_db_per_km = non_negative("absorption_db_per_km", absorption_db_per_km)
145
+
146
+ free_field = ref_distance * 10.0 ** ((source_db - target_db) / 20.0)
147
+ if free_field == 0.0 or math.isinf(free_field):
148
+ raise InputError("source_db and target_db are too far apart to give a usable distance")
149
+ if not absorption_db_per_km or free_field == ref_distance:
150
+ return free_field
151
+
152
+ # The root lies between the free-field answer and the reference distance:
153
+ # absorption lowers the level beyond d_ref and raises it inside d_ref.
154
+ lo, hi = sorted((free_field, ref_distance))
155
+
156
+ def excess(d: float) -> float:
157
+ return spl_at_distance(source_db, d, ref_distance, unit, absorption_db_per_km) - target_db
158
+
159
+ for _ in range(200):
160
+ mid = 0.5 * (lo + hi)
161
+ if excess(mid) > 0:
162
+ lo = mid
163
+ else:
164
+ hi = mid
165
+ if hi - lo <= 1e-12 * hi:
166
+ break
167
+ return 0.5 * (lo + hi)
168
+
169
+
170
+ def distance_ratio_loss(ratio: float) -> float:
171
+ """Level change in dB when the distance is multiplied by ``ratio`` (free field).
172
+
173
+ Formula: ``20 * log10(ratio)``. A ratio of 10 gives 20 dB.
174
+ """
175
+ ratio = positive("ratio", ratio)
176
+ return 20.0 * math.log10(ratio)
177
+
178
+
179
+ def db_doubling_loss() -> float:
180
+ """Free-field loss for each doubling of distance: ``20*log10(2)`` = about 6.02 dB."""
181
+ return distance_ratio_loss(2.0)
182
+
183
+
184
+ def combine_levels(levels_db: Iterable[float]) -> float:
185
+ """Combine incoherent sources (e.g. two horns) into one level.
186
+
187
+ Formula: ``L = 10 * log10(sum(10 ** (L_i / 10)))``. Two equal sources add
188
+ about 3.01 dB, not double the decibels.
189
+ """
190
+ values = [number("level", v) for v in levels_db]
191
+ if not values:
192
+ raise InputError("combine_levels needs at least one level")
193
+ peak = max(values)
194
+ # Factor out the peak to avoid overflow with very large dB values.
195
+ return peak + 10.0 * math.log10(sum(10.0 ** ((v - peak) / 10.0) for v in values))