stringcalc 0.1.0__py3-none-any.whl

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,11 @@
1
+ id,gauge,uw,rho
2
+ Aa,0.02047,2.128e-05,1789
3
+ Ab,0.0185,1.783e-05,1835
4
+ E,0.02598,3.439e-05,1795
5
+ Ca,0.02913,4.504e-05,1870
6
+ Cb,0.03189,5.45e-05,1889
7
+ Ga,0.02244,2.585e-05,1809
8
+ Gb,0.02441,3.063e-05,1812
9
+ Gc,0.02598,3.439e-05,1795
10
+ Glo,0.03583,6.642e-05,1823
11
+ GloHD,0.03583,6.567e-05,1803
stringcalc/frets.py ADDED
@@ -0,0 +1,181 @@
1
+ """
2
+ Fret distance calculations.
3
+
4
+ For example:
5
+
6
+ - compute equal-temperament fret locations for a given scale length
7
+ - compute the scale length implied by a given fret-to-fret distance
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Final, Union
13
+
14
+ import numpy as np
15
+ import numpy.typing as npt # v1.21 needed
16
+ import pandas as pd
17
+ from pint import Quantity, UnitRegistry
18
+
19
+ ureg: Final[UnitRegistry] = UnitRegistry()
20
+ # Q_ = ureg.Quantity # mypy doesn't like this one
21
+
22
+ QLike = Union[Quantity, str]
23
+
24
+ # Note also `pint._typing.UnitLike`
25
+
26
+
27
+ def distance_et(n: int | npt.ArrayLike, *, L: float) -> np.float64 | npt.NDArray[np.float64]:
28
+ r"""Exact equal-temperament distance from nut for fret(s) `n` for scale length `L`.
29
+
30
+ Using the 12th-root-of-2 method.
31
+
32
+ .. math::
33
+
34
+ d_n = L \left( 1 - 2^{-n/12} \right)
35
+
36
+ Reference: https://www.liutaiomottola.com/formulae/fret.htm
37
+
38
+ Parameters
39
+ ----------
40
+ n
41
+ Fret number (or array-like of them).
42
+ If floats are passed, they will be floored before computing.
43
+ L
44
+ Scale length.
45
+ """
46
+ n = np.floor(n, dtype=np.float64)
47
+
48
+ if not np.all(n > 0):
49
+ raise ValueError("input fret numbers should be positive")
50
+
51
+ return (L * (1 - 2 ** (-n / 12))).astype(np.float64)
52
+
53
+
54
+ def distances(N: int, *, L: float, method: str = "et") -> pd.DataFrame:
55
+ """Fret distance DataFrame for `N` frets and scale length `L`.
56
+
57
+ Parameters
58
+ ----------
59
+ N
60
+ Number of frets (not including nut) to compute.
61
+ L
62
+ Scale length.
63
+ method
64
+ Method to use for computing fret distances.
65
+
66
+ - ``'et'``: equal temperament (:func:`distance_et`)
67
+
68
+
69
+ .. note::
70
+ Columns:
71
+
72
+ - ``n``: fret number (index)
73
+ - ``d``: distance from nut to fret
74
+ - ``dd``: distance from previous fret to current
75
+ - ``d_inv``: distance from fret to saddle
76
+ """
77
+ assert N >= 1 # guarantees `d` is array with at least one value
78
+ n = np.arange(1, N + 1)
79
+
80
+ if method in {"et"}:
81
+ d = distance_et(n, L=L)
82
+ else:
83
+ raise ValueError(f"invalid `method` {method!r}")
84
+
85
+ dd = np.append(d[0], np.diff(d)) # type: ignore[index]
86
+
87
+ # TODO: d to +5 or +7 frets?
88
+ # TODO: comparison to just intonation for specified root
89
+
90
+ df = pd.DataFrame({"n": n, "d": d, "dd": dd, "d_inv": L - d}).set_index("n")
91
+ df.attrs.update(
92
+ {
93
+ "col_desc": {
94
+ "n": "fret number",
95
+ "d": "distance from nut to fret",
96
+ "dd": "distance from previous fret to current",
97
+ "d_inv": "distance from fret to saddle",
98
+ },
99
+ "fancy_col": {
100
+ "n": "n",
101
+ "d": "d",
102
+ "dd": "Δd",
103
+ "d_inv": "L−d",
104
+ },
105
+ }
106
+ )
107
+
108
+ return df
109
+
110
+
111
+ def length_from_distance(ab: tuple[int | None, int | None], d: float | QLike) -> float | Quantity:
112
+ """Calculate the scale length implied by a->b distance `d`.
113
+
114
+ Parameters
115
+ ----------
116
+ ab
117
+ `ab` is a 2-tuple ``(a, b)`` specifying the bounds of the input distance `d` in terms of fret number.
118
+ Use ``None`` to indicate the bridge/saddle end of the fretboard
119
+ (and ``0`` to indicate the nut end).
120
+ d
121
+ Distance between ``a`` and ``b``.
122
+
123
+ .. note::
124
+ Can use a quantity string that Pint will recognize, e.g. ``'25.5 in'``.
125
+ Then, the output will be a :class:`pint.Quantity` with the same units.
126
+
127
+ Examples
128
+ --------
129
+
130
+ >>> from stringcalc.frets import length_from_distance
131
+ >>> round(length_from_distance((0, 1), 1.4), 2)
132
+ 24.94
133
+ >>> round(length_from_distance((0, 1), "3 cm").to("inch"), 2)
134
+ <Quantity(21.04, 'inch')>
135
+ """
136
+ if isinstance(d, str):
137
+ d = ureg(d)
138
+
139
+ if not d > 0:
140
+ raise ValueError("`d` must be positive")
141
+
142
+ a, b = ab
143
+
144
+ def c(n):
145
+ if n in {None, np.inf}:
146
+ return 1
147
+ elif n == 0:
148
+ return 0
149
+ else:
150
+ return 1 - 1 / (2 ** (n / 12))
151
+
152
+ c_a = c(a)
153
+ c_b = c(b)
154
+
155
+ if c_a == c_b:
156
+ raise ValueError("`a` and `b` must be different frets in order to compute L")
157
+
158
+ return d / abs(c_b - c_a)
159
+
160
+
161
+ if __name__ == "__main__":
162
+ L = 21
163
+ N = 19
164
+ units = "inches"
165
+ float_format = "%.3f"
166
+
167
+ df = distances(N, L=L)
168
+
169
+ if units.lower() in {"inches", "in", "in.", '"'}:
170
+ su_l = '"'
171
+ su_si = "in"
172
+ elif units.lower() in {"mm"}:
173
+ su_l = su_si = "mm"
174
+ else:
175
+ raise ValueError(f"invalid `units` {units!r}")
176
+
177
+ print(f'L = {L}" (scale length)')
178
+ print(df.to_string(float_format=float_format)) # type: ignore[call-overload]
179
+ l = max(len(s) for s in df.attrs["col_desc"]) # noqa: E741
180
+ for k, v in df.attrs["col_desc"].items():
181
+ print(f"{k:{l+2}}{v}{'' if k == 'n' else f' ({su_si})'}")
stringcalc/py.typed ADDED
File without changes