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.
- trainhorn_calc-1.0.0/LICENSE +21 -0
- trainhorn_calc-1.0.0/PKG-INFO +133 -0
- trainhorn_calc-1.0.0/README.md +111 -0
- trainhorn_calc-1.0.0/pyproject.toml +36 -0
- trainhorn_calc-1.0.0/setup.cfg +4 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/__init__.py +38 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/__main__.py +5 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/_validate.py +59 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/acoustics.py +195 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/airsystem.py +186 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/cli.py +173 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/electrical.py +192 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc/py.typed +0 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc.egg-info/PKG-INFO +133 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc.egg-info/SOURCES.txt +17 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc.egg-info/dependency_links.txt +1 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc.egg-info/entry_points.txt +2 -0
- trainhorn_calc-1.0.0/src/trainhorn_calc.egg-info/top_level.txt +1 -0
- trainhorn_calc-1.0.0/tests/test_trainhorn_calc.py +312 -0
|
@@ -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,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,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))
|