physu 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.
- physu/__init__.py +22 -0
- physu/constants.py +56 -0
- physu/exceptions.py +18 -0
- physu/kinematics/__init__.py +92 -0
- physu/kinematics/accelerated.py +312 -0
- physu/kinematics/circular.py +238 -0
- physu/kinematics/projectile.py +250 -0
- physu/kinematics/uniform.py +111 -0
- physu/kinematics/vertical.py +225 -0
- physu/units.py +133 -0
- physu/validation.py +193 -0
- physu-0.1.0.dist-info/METADATA +128 -0
- physu-0.1.0.dist-info/RECORD +15 -0
- physu-0.1.0.dist-info/WHEEL +4 -0
- physu-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
"""Uniform Circular Motion (UCM) formulas with Pint unit validation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
|
|
7
|
+
import pint
|
|
8
|
+
|
|
9
|
+
from ..exceptions import PhysicalDomainError
|
|
10
|
+
from ..units import Quantity, QuantityLike, to_unit
|
|
11
|
+
from ..validation import validate_quantity
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _validate_positive_radius(radius: QuantityLike) -> pint.Quantity:
|
|
15
|
+
"""Validate circular radius as a strictly positive length."""
|
|
16
|
+
return validate_quantity(
|
|
17
|
+
radius,
|
|
18
|
+
"[length]",
|
|
19
|
+
name="radius",
|
|
20
|
+
allow_negative=False,
|
|
21
|
+
allow_zero=False,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def tangential_speed(
|
|
26
|
+
angular_velocity: QuantityLike,
|
|
27
|
+
radius: QuantityLike,
|
|
28
|
+
) -> pint.Quantity:
|
|
29
|
+
"""Compute tangential speed magnitude: ``v = |omega| * r``.
|
|
30
|
+
|
|
31
|
+
Args:
|
|
32
|
+
angular_velocity: Angular velocity (unit compatible with ``"rad / s"``, e.g. ``"rpm"``).
|
|
33
|
+
radius: Circular path radius (dimension ``[length]``, must be ``> 0``).
|
|
34
|
+
|
|
35
|
+
Returns:
|
|
36
|
+
Non-negative tangential speed as an SI base ``pint.Quantity`` (``meter / second``).
|
|
37
|
+
"""
|
|
38
|
+
omega_rad_s = abs(
|
|
39
|
+
float(
|
|
40
|
+
validate_quantity(angular_velocity, "rad / s", name="angular_velocity")
|
|
41
|
+
.to("rad / s")
|
|
42
|
+
.magnitude
|
|
43
|
+
)
|
|
44
|
+
)
|
|
45
|
+
r_m = float(_validate_positive_radius(radius).to("m").magnitude)
|
|
46
|
+
return Quantity(omega_rad_s * r_m, "m / s")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def angular_velocity_from_speed(
|
|
50
|
+
tangential_speed: QuantityLike,
|
|
51
|
+
radius: QuantityLike,
|
|
52
|
+
) -> pint.Quantity:
|
|
53
|
+
"""Compute angular speed magnitude from tangential speed: ``omega = v / r``.
|
|
54
|
+
|
|
55
|
+
Args:
|
|
56
|
+
tangential_speed: Tangential speed (dimension ``[velocity]``, must be ``>= 0``).
|
|
57
|
+
radius: Circular path radius (dimension ``[length]``, must be ``> 0``).
|
|
58
|
+
|
|
59
|
+
Returns:
|
|
60
|
+
Angular velocity as a ``pint.Quantity`` (``radian / second``).
|
|
61
|
+
"""
|
|
62
|
+
v_m_s = float(
|
|
63
|
+
validate_quantity(
|
|
64
|
+
tangential_speed,
|
|
65
|
+
"[velocity]",
|
|
66
|
+
name="tangential_speed",
|
|
67
|
+
allow_negative=False,
|
|
68
|
+
)
|
|
69
|
+
.to("m / s")
|
|
70
|
+
.magnitude
|
|
71
|
+
)
|
|
72
|
+
r_m = float(_validate_positive_radius(radius).to("m").magnitude)
|
|
73
|
+
return Quantity(v_m_s / r_m, "rad / s")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def centripetal_acceleration(
|
|
77
|
+
radius: QuantityLike,
|
|
78
|
+
*,
|
|
79
|
+
tangential_speed: QuantityLike | None = None,
|
|
80
|
+
angular_velocity: QuantityLike | None = None,
|
|
81
|
+
) -> pint.Quantity:
|
|
82
|
+
"""Compute centripetal acceleration: ``a_c = v^2 / r`` or ``a_c = omega^2 * r``.
|
|
83
|
+
|
|
84
|
+
Provide exactly one of ``tangential_speed`` or ``angular_velocity``.
|
|
85
|
+
|
|
86
|
+
Args:
|
|
87
|
+
radius: Circular path radius (dimension ``[length]``, must be ``> 0``).
|
|
88
|
+
tangential_speed: Tangential speed (dimension ``[velocity]``).
|
|
89
|
+
angular_velocity: Angular velocity (compatible with ``"rad / s"``).
|
|
90
|
+
|
|
91
|
+
Returns:
|
|
92
|
+
Centripetal acceleration as an SI base ``pint.Quantity`` (``meter / second ** 2``).
|
|
93
|
+
|
|
94
|
+
Raises:
|
|
95
|
+
ValueError: If neither or both of ``tangential_speed`` and
|
|
96
|
+
``angular_velocity`` are provided.
|
|
97
|
+
pint.DimensionalityError: If any argument has invalid dimensions.
|
|
98
|
+
PhysicalDomainError: If ``radius <= 0`` or any input is non-finite.
|
|
99
|
+
"""
|
|
100
|
+
if (tangential_speed is None) == (angular_velocity is None):
|
|
101
|
+
raise ValueError(
|
|
102
|
+
"Provide exactly one of 'tangential_speed' or 'angular_velocity'."
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
r = _validate_positive_radius(radius)
|
|
106
|
+
if tangential_speed is not None:
|
|
107
|
+
v = validate_quantity(tangential_speed, "[velocity]", name="tangential_speed")
|
|
108
|
+
return to_unit(v**2 / r, "m / s^2")
|
|
109
|
+
|
|
110
|
+
assert angular_velocity is not None
|
|
111
|
+
omega = validate_quantity(angular_velocity, "rad / s", name="angular_velocity")
|
|
112
|
+
return to_unit(omega**2 * r, "m / s^2")
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def period_from_frequency(frequency: QuantityLike) -> pint.Quantity:
|
|
116
|
+
"""Compute orbital period from cycle frequency: ``T = 1 / f``."""
|
|
117
|
+
freq_hz = float(
|
|
118
|
+
validate_quantity(
|
|
119
|
+
frequency,
|
|
120
|
+
"[frequency]",
|
|
121
|
+
name="frequency",
|
|
122
|
+
allow_negative=False,
|
|
123
|
+
allow_zero=False,
|
|
124
|
+
)
|
|
125
|
+
.to("Hz")
|
|
126
|
+
.magnitude
|
|
127
|
+
)
|
|
128
|
+
return Quantity(1.0 / freq_hz, "s")
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def frequency_from_period(period: QuantityLike) -> pint.Quantity:
|
|
132
|
+
"""Compute cycle frequency from period: ``f = 1 / T``."""
|
|
133
|
+
period_s = float(
|
|
134
|
+
validate_quantity(
|
|
135
|
+
period,
|
|
136
|
+
"[time]",
|
|
137
|
+
name="period",
|
|
138
|
+
allow_negative=False,
|
|
139
|
+
allow_zero=False,
|
|
140
|
+
)
|
|
141
|
+
.to("s")
|
|
142
|
+
.magnitude
|
|
143
|
+
)
|
|
144
|
+
return Quantity(1.0 / period_s, "Hz")
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def angular_velocity_from_period(period: QuantityLike) -> pint.Quantity:
|
|
148
|
+
"""Compute angular velocity from period: ``omega = 2 * pi / T``."""
|
|
149
|
+
period_s = float(
|
|
150
|
+
validate_quantity(
|
|
151
|
+
period,
|
|
152
|
+
"[time]",
|
|
153
|
+
name="period",
|
|
154
|
+
allow_negative=False,
|
|
155
|
+
allow_zero=False,
|
|
156
|
+
)
|
|
157
|
+
.to("s")
|
|
158
|
+
.magnitude
|
|
159
|
+
)
|
|
160
|
+
return Quantity(2.0 * math.pi / period_s, "rad / s")
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def angular_velocity_from_frequency(frequency: QuantityLike) -> pint.Quantity:
|
|
164
|
+
"""Compute angular velocity from cycle frequency: ``omega = 2 * pi * f``."""
|
|
165
|
+
freq_hz = float(
|
|
166
|
+
validate_quantity(
|
|
167
|
+
frequency,
|
|
168
|
+
"[frequency]",
|
|
169
|
+
name="frequency",
|
|
170
|
+
allow_negative=False,
|
|
171
|
+
)
|
|
172
|
+
.to("Hz")
|
|
173
|
+
.magnitude
|
|
174
|
+
)
|
|
175
|
+
return Quantity(2.0 * math.pi * freq_hz, "rad / s")
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def period_from_angular_velocity(angular_velocity: QuantityLike) -> pint.Quantity:
|
|
179
|
+
"""Compute period from angular velocity: ``T = 2 * pi / |omega|``."""
|
|
180
|
+
omega_rad_s = abs(
|
|
181
|
+
float(
|
|
182
|
+
validate_quantity(
|
|
183
|
+
angular_velocity,
|
|
184
|
+
"rad / s",
|
|
185
|
+
name="angular_velocity",
|
|
186
|
+
allow_zero=False,
|
|
187
|
+
)
|
|
188
|
+
.to("rad / s")
|
|
189
|
+
.magnitude
|
|
190
|
+
)
|
|
191
|
+
)
|
|
192
|
+
if omega_rad_s == 0.0:
|
|
193
|
+
raise PhysicalDomainError("Parameter 'angular_velocity' cannot be zero.")
|
|
194
|
+
return Quantity(2.0 * math.pi / omega_rad_s, "s")
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def frequency_from_angular_velocity(angular_velocity: QuantityLike) -> pint.Quantity:
|
|
198
|
+
"""Compute cycle frequency from angular velocity: ``f = |omega| / (2 * pi)``."""
|
|
199
|
+
omega_rad_s = abs(
|
|
200
|
+
float(
|
|
201
|
+
validate_quantity(angular_velocity, "rad / s", name="angular_velocity")
|
|
202
|
+
.to("rad / s")
|
|
203
|
+
.magnitude
|
|
204
|
+
)
|
|
205
|
+
)
|
|
206
|
+
return Quantity(omega_rad_s / (2.0 * math.pi), "Hz")
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def angular_displacement(
|
|
210
|
+
angular_velocity: QuantityLike,
|
|
211
|
+
time: QuantityLike,
|
|
212
|
+
) -> pint.Quantity:
|
|
213
|
+
"""Compute angular displacement in UCM: ``dtheta = omega * t``."""
|
|
214
|
+
omega = validate_quantity(angular_velocity, "rad / s", name="angular_velocity")
|
|
215
|
+
elapsed = validate_quantity(time, "[time]", name="time", allow_negative=False)
|
|
216
|
+
return to_unit(omega * elapsed, "rad")
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def arc_length(radius: QuantityLike, angle: QuantityLike) -> pint.Quantity:
|
|
220
|
+
"""Compute circular arc length: ``s = r * theta``."""
|
|
221
|
+
r = validate_quantity(radius, "[length]", name="radius", allow_negative=False)
|
|
222
|
+
theta = validate_quantity(angle, "rad", name="angle")
|
|
223
|
+
return to_unit(r * theta, "m")
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
__all__ = [
|
|
227
|
+
"angular_displacement",
|
|
228
|
+
"angular_velocity_from_frequency",
|
|
229
|
+
"angular_velocity_from_period",
|
|
230
|
+
"angular_velocity_from_speed",
|
|
231
|
+
"arc_length",
|
|
232
|
+
"centripetal_acceleration",
|
|
233
|
+
"frequency_from_angular_velocity",
|
|
234
|
+
"frequency_from_period",
|
|
235
|
+
"period_from_angular_velocity",
|
|
236
|
+
"period_from_frequency",
|
|
237
|
+
"tangential_speed",
|
|
238
|
+
]
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
"""2D projectile motion formulas under uniform gravity (positive y-axis upward)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
|
|
7
|
+
import pint
|
|
8
|
+
|
|
9
|
+
from ..constants import STANDARD_GRAVITY
|
|
10
|
+
from ..exceptions import PhysicalDomainError
|
|
11
|
+
from ..units import Quantity, QuantityLike, to_si
|
|
12
|
+
from ..validation import validate_quantity
|
|
13
|
+
from . import uniform, vertical
|
|
14
|
+
|
|
15
|
+
_TRIG_ZERO_TOL = 1e-15
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _snap_trig(value: float) -> float:
|
|
19
|
+
"""Snap near-zero trigonometric artifacts (e.g. cos(90 deg)) to exact zero."""
|
|
20
|
+
return 0.0 if abs(value) < _TRIG_ZERO_TOL else value
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _validate_gravity(gravity: QuantityLike) -> pint.Quantity:
|
|
24
|
+
"""Validate gravitational acceleration magnitude (strictly positive)."""
|
|
25
|
+
return validate_quantity(
|
|
26
|
+
gravity,
|
|
27
|
+
"[acceleration]",
|
|
28
|
+
name="gravity",
|
|
29
|
+
allow_negative=False,
|
|
30
|
+
allow_zero=False,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def velocity_components(
|
|
35
|
+
initial_speed: QuantityLike,
|
|
36
|
+
angle: QuantityLike,
|
|
37
|
+
) -> tuple[pint.Quantity, pint.Quantity]:
|
|
38
|
+
"""Decompose launch speed and angle into horizontal and vertical components.
|
|
39
|
+
|
|
40
|
+
Args:
|
|
41
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
42
|
+
angle: Launch angle relative to the horizontal (unit compatible with ``"rad"``).
|
|
43
|
+
|
|
44
|
+
Returns:
|
|
45
|
+
Tuple ``(vx0, vy0)`` as SI base ``pint.Quantity`` values (``meter / second``).
|
|
46
|
+
|
|
47
|
+
Raises:
|
|
48
|
+
pint.DimensionalityError: If ``initial_speed`` or ``angle`` has invalid dimensions.
|
|
49
|
+
PhysicalDomainError: If ``initial_speed < 0`` or any input is non-finite.
|
|
50
|
+
"""
|
|
51
|
+
speed_m = float(
|
|
52
|
+
validate_quantity(
|
|
53
|
+
initial_speed,
|
|
54
|
+
"[velocity]",
|
|
55
|
+
name="initial_speed",
|
|
56
|
+
allow_negative=False,
|
|
57
|
+
)
|
|
58
|
+
.to("m / s")
|
|
59
|
+
.magnitude
|
|
60
|
+
)
|
|
61
|
+
angle_rad = float(validate_quantity(angle, "rad", name="angle").to("rad").magnitude)
|
|
62
|
+
|
|
63
|
+
vx0 = speed_m * _snap_trig(math.cos(angle_rad))
|
|
64
|
+
vy0 = speed_m * _snap_trig(math.sin(angle_rad))
|
|
65
|
+
return Quantity(vx0, "m / s"), Quantity(vy0, "m / s")
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def projectile_flight_time(
|
|
69
|
+
initial_speed: QuantityLike,
|
|
70
|
+
angle: QuantityLike,
|
|
71
|
+
*,
|
|
72
|
+
initial_height: QuantityLike = "0 m",
|
|
73
|
+
gravity: QuantityLike = STANDARD_GRAVITY,
|
|
74
|
+
) -> pint.Quantity:
|
|
75
|
+
"""Compute total flight time until reaching ground level (``y = 0``).
|
|
76
|
+
|
|
77
|
+
Solves ``y0 + vy0 * t - 0.5 * g * t^2 = 0`` for ``t >= 0``.
|
|
78
|
+
|
|
79
|
+
Args:
|
|
80
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
81
|
+
angle: Launch angle relative to the horizontal (compatible with ``"rad"``).
|
|
82
|
+
initial_height: Launch height above ground (``[length]``, must be ``>= 0``).
|
|
83
|
+
gravity: Gravitational acceleration magnitude (``> 0``, defaults to
|
|
84
|
+
``STANDARD_GRAVITY``).
|
|
85
|
+
|
|
86
|
+
Returns:
|
|
87
|
+
Flight time as an SI base ``pint.Quantity`` (``second``).
|
|
88
|
+
|
|
89
|
+
Raises:
|
|
90
|
+
pint.DimensionalityError: If any argument has invalid dimensions.
|
|
91
|
+
PhysicalDomainError: If launching downward from ground level (``y0 == 0`` and
|
|
92
|
+
``vy0 < 0``), ``initial_speed < 0``, ``initial_height < 0``, or ``gravity <= 0``.
|
|
93
|
+
"""
|
|
94
|
+
_, vy0_q = velocity_components(initial_speed, angle)
|
|
95
|
+
y0_m = float(
|
|
96
|
+
validate_quantity(
|
|
97
|
+
initial_height,
|
|
98
|
+
"[length]",
|
|
99
|
+
name="initial_height",
|
|
100
|
+
allow_negative=False,
|
|
101
|
+
)
|
|
102
|
+
.to("m")
|
|
103
|
+
.magnitude
|
|
104
|
+
)
|
|
105
|
+
g_m = float(_validate_gravity(gravity).to("m / s^2").magnitude)
|
|
106
|
+
vy0_m = float(vy0_q.magnitude)
|
|
107
|
+
|
|
108
|
+
if y0_m == 0.0 and vy0_m < 0.0:
|
|
109
|
+
raise PhysicalDomainError(
|
|
110
|
+
"Cannot launch downward (vy0 < 0) from ground level (initial_height == 0)."
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
discriminant = vy0_m**2 + 2.0 * g_m * y0_m
|
|
114
|
+
t_flight = (vy0_m + math.sqrt(discriminant)) / g_m
|
|
115
|
+
return Quantity(max(0.0, t_flight), "s")
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def projectile_max_height(
|
|
119
|
+
initial_speed: QuantityLike,
|
|
120
|
+
angle: QuantityLike,
|
|
121
|
+
*,
|
|
122
|
+
initial_height: QuantityLike = "0 m",
|
|
123
|
+
gravity: QuantityLike = STANDARD_GRAVITY,
|
|
124
|
+
) -> pint.Quantity:
|
|
125
|
+
"""Compute maximum height reached during projectile motion.
|
|
126
|
+
|
|
127
|
+
Args:
|
|
128
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
129
|
+
angle: Launch angle relative to the horizontal (compatible with ``"rad"``).
|
|
130
|
+
initial_height: Launch height above ground (``[length]``, must be ``>= 0``).
|
|
131
|
+
gravity: Gravitational acceleration magnitude (``> 0``, defaults to
|
|
132
|
+
``STANDARD_GRAVITY``).
|
|
133
|
+
|
|
134
|
+
Returns:
|
|
135
|
+
Maximum height as an SI base ``pint.Quantity`` (``meter``).
|
|
136
|
+
|
|
137
|
+
Raises:
|
|
138
|
+
pint.DimensionalityError: If any argument has invalid dimensions.
|
|
139
|
+
PhysicalDomainError: If launching downward from ground level (``y0 == 0`` and
|
|
140
|
+
``vy0 < 0``) or inputs violate domain rules.
|
|
141
|
+
"""
|
|
142
|
+
_, vy0 = velocity_components(initial_speed, angle)
|
|
143
|
+
y0 = validate_quantity(
|
|
144
|
+
initial_height,
|
|
145
|
+
"[length]",
|
|
146
|
+
name="initial_height",
|
|
147
|
+
allow_negative=False,
|
|
148
|
+
)
|
|
149
|
+
g = _validate_gravity(gravity)
|
|
150
|
+
|
|
151
|
+
if vy0.magnitude < 0:
|
|
152
|
+
if y0.magnitude == 0:
|
|
153
|
+
raise PhysicalDomainError(
|
|
154
|
+
"Cannot launch downward (vy0 < 0) from ground level (initial_height == 0)."
|
|
155
|
+
)
|
|
156
|
+
return to_si(y0)
|
|
157
|
+
|
|
158
|
+
return vertical.max_height(vy0, initial_height=y0, gravity=g)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def projectile_range(
|
|
162
|
+
initial_speed: QuantityLike,
|
|
163
|
+
angle: QuantityLike,
|
|
164
|
+
*,
|
|
165
|
+
initial_height: QuantityLike = "0 m",
|
|
166
|
+
gravity: QuantityLike = STANDARD_GRAVITY,
|
|
167
|
+
) -> pint.Quantity:
|
|
168
|
+
"""Compute horizontal range upon reaching ground level (``y = 0``).
|
|
169
|
+
|
|
170
|
+
Args:
|
|
171
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
172
|
+
angle: Launch angle relative to the horizontal (compatible with ``"rad"``).
|
|
173
|
+
initial_height: Launch height above ground (``[length]``, must be ``>= 0``).
|
|
174
|
+
gravity: Gravitational acceleration magnitude (``> 0``, defaults to
|
|
175
|
+
``STANDARD_GRAVITY``).
|
|
176
|
+
|
|
177
|
+
Returns:
|
|
178
|
+
Horizontal range as an SI base ``pint.Quantity`` (``meter``).
|
|
179
|
+
"""
|
|
180
|
+
vx0, _ = velocity_components(initial_speed, angle)
|
|
181
|
+
t_flight = projectile_flight_time(
|
|
182
|
+
initial_speed,
|
|
183
|
+
angle,
|
|
184
|
+
initial_height=initial_height,
|
|
185
|
+
gravity=gravity,
|
|
186
|
+
)
|
|
187
|
+
return uniform.displacement(vx0, t_flight)
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def projectile_position(
|
|
191
|
+
initial_speed: QuantityLike,
|
|
192
|
+
angle: QuantityLike,
|
|
193
|
+
time: QuantityLike,
|
|
194
|
+
*,
|
|
195
|
+
initial_height: QuantityLike = "0 m",
|
|
196
|
+
gravity: QuantityLike = STANDARD_GRAVITY,
|
|
197
|
+
) -> tuple[pint.Quantity, pint.Quantity]:
|
|
198
|
+
"""Compute 2D position ``(x(t), y(t))`` at elapsed ``time >= 0``.
|
|
199
|
+
|
|
200
|
+
Args:
|
|
201
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
202
|
+
angle: Launch angle relative to the horizontal (compatible with ``"rad"``).
|
|
203
|
+
time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
|
|
204
|
+
initial_height: Initial vertical position (``[length]``, defaults to ``"0 m"``).
|
|
205
|
+
gravity: Gravitational acceleration magnitude (``> 0``, defaults to
|
|
206
|
+
``STANDARD_GRAVITY``).
|
|
207
|
+
|
|
208
|
+
Returns:
|
|
209
|
+
Tuple ``(x, y)`` as SI base ``pint.Quantity`` values (``meter``).
|
|
210
|
+
"""
|
|
211
|
+
vx0, vy0 = velocity_components(initial_speed, angle)
|
|
212
|
+
x = uniform.displacement(vx0, time)
|
|
213
|
+
y = vertical.vertical_position(initial_height, vy0, time, gravity=gravity)
|
|
214
|
+
return x, y
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def projectile_velocity(
|
|
218
|
+
initial_speed: QuantityLike,
|
|
219
|
+
angle: QuantityLike,
|
|
220
|
+
time: QuantityLike,
|
|
221
|
+
*,
|
|
222
|
+
gravity: QuantityLike = STANDARD_GRAVITY,
|
|
223
|
+
) -> tuple[pint.Quantity, pint.Quantity]:
|
|
224
|
+
"""Compute 2D velocity ``(vx(t), vy(t))`` at elapsed ``time >= 0``.
|
|
225
|
+
|
|
226
|
+
Args:
|
|
227
|
+
initial_speed: Launch speed magnitude (``[velocity]``, must be ``>= 0``).
|
|
228
|
+
angle: Launch angle relative to the horizontal (compatible with ``"rad"``).
|
|
229
|
+
time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
|
|
230
|
+
gravity: Gravitational acceleration magnitude (``> 0``, defaults to
|
|
231
|
+
``STANDARD_GRAVITY``).
|
|
232
|
+
|
|
233
|
+
Returns:
|
|
234
|
+
Tuple ``(vx, vy)`` as SI base ``pint.Quantity`` values (``meter / second``).
|
|
235
|
+
"""
|
|
236
|
+
vx0, vy0 = velocity_components(initial_speed, angle)
|
|
237
|
+
# Validate time even though vx stays constant.
|
|
238
|
+
validate_quantity(time, "[time]", name="time", allow_negative=False)
|
|
239
|
+
vy = vertical.vertical_velocity(vy0, time, gravity=gravity)
|
|
240
|
+
return vx0, vy
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
__all__ = [
|
|
244
|
+
"projectile_flight_time",
|
|
245
|
+
"projectile_max_height",
|
|
246
|
+
"projectile_position",
|
|
247
|
+
"projectile_range",
|
|
248
|
+
"projectile_velocity",
|
|
249
|
+
"velocity_components",
|
|
250
|
+
]
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
"""Uniform Rectilinear Motion (MRU) formulas with Pint unit validation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import pint
|
|
6
|
+
|
|
7
|
+
from ..exceptions import PhysicalDomainError
|
|
8
|
+
from ..units import QuantityLike, to_si
|
|
9
|
+
from ..validation import validate_quantity
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def displacement(velocity: QuantityLike, time: QuantityLike) -> pint.Quantity:
|
|
13
|
+
"""Compute displacement for constant-velocity 1D motion: ``dx = v * t``.
|
|
14
|
+
|
|
15
|
+
Args:
|
|
16
|
+
velocity: Constant velocity (dimension ``[velocity]``).
|
|
17
|
+
time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
|
|
18
|
+
|
|
19
|
+
Returns:
|
|
20
|
+
Displacement as an SI base ``pint.Quantity`` (``meter``).
|
|
21
|
+
|
|
22
|
+
Raises:
|
|
23
|
+
pint.DimensionalityError: If ``velocity`` or ``time`` has invalid dimensions.
|
|
24
|
+
PhysicalDomainError: If ``time`` is negative or any input is non-finite.
|
|
25
|
+
"""
|
|
26
|
+
vel = validate_quantity(velocity, "[velocity]", name="velocity")
|
|
27
|
+
elapsed = validate_quantity(time, "[time]", name="time", allow_negative=False)
|
|
28
|
+
return to_si(vel * elapsed)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def position(
|
|
32
|
+
initial_position: QuantityLike,
|
|
33
|
+
velocity: QuantityLike,
|
|
34
|
+
time: QuantityLike,
|
|
35
|
+
) -> pint.Quantity:
|
|
36
|
+
"""Compute position at ``time`` for constant-velocity 1D motion: ``x = x0 + v * t``.
|
|
37
|
+
|
|
38
|
+
Args:
|
|
39
|
+
initial_position: Initial position (dimension ``[length]``).
|
|
40
|
+
velocity: Constant velocity (dimension ``[velocity]``).
|
|
41
|
+
time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
|
|
42
|
+
|
|
43
|
+
Returns:
|
|
44
|
+
Position as an SI base ``pint.Quantity`` (``meter``).
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
pint.DimensionalityError: If any argument has invalid dimensions.
|
|
48
|
+
PhysicalDomainError: If ``time`` is negative or any input is non-finite.
|
|
49
|
+
"""
|
|
50
|
+
x0 = validate_quantity(initial_position, "[length]", name="initial_position")
|
|
51
|
+
delta_x = displacement(velocity, time)
|
|
52
|
+
return to_si(x0 + delta_x)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def average_velocity(displacement: QuantityLike, time: QuantityLike) -> pint.Quantity:
|
|
56
|
+
"""Compute constant or average velocity: ``v = dx / t``.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
displacement: Displacement (dimension ``[length]``).
|
|
60
|
+
time: Elapsed time (dimension ``[time]``, must be ``> 0``).
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
Velocity as an SI base ``pint.Quantity`` (``meter / second``).
|
|
64
|
+
|
|
65
|
+
Raises:
|
|
66
|
+
pint.DimensionalityError: If arguments have invalid dimensions.
|
|
67
|
+
PhysicalDomainError: If ``time <= 0`` or any input is non-finite.
|
|
68
|
+
"""
|
|
69
|
+
delta_x = validate_quantity(displacement, "[length]", name="displacement")
|
|
70
|
+
elapsed = validate_quantity(
|
|
71
|
+
time,
|
|
72
|
+
"[time]",
|
|
73
|
+
name="time",
|
|
74
|
+
allow_negative=False,
|
|
75
|
+
allow_zero=False,
|
|
76
|
+
)
|
|
77
|
+
return to_si(delta_x / elapsed)
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def travel_time(displacement: QuantityLike, velocity: QuantityLike) -> pint.Quantity:
|
|
81
|
+
"""Compute elapsed time for constant-velocity 1D motion: ``t = dx / v``.
|
|
82
|
+
|
|
83
|
+
Args:
|
|
84
|
+
displacement: Target displacement (dimension ``[length]``).
|
|
85
|
+
velocity: Constant velocity (dimension ``[velocity]``, must be ``!= 0``).
|
|
86
|
+
|
|
87
|
+
Returns:
|
|
88
|
+
Elapsed time as an SI base ``pint.Quantity`` (``second``).
|
|
89
|
+
|
|
90
|
+
Raises:
|
|
91
|
+
pint.DimensionalityError: If arguments have invalid dimensions.
|
|
92
|
+
PhysicalDomainError: If ``velocity == 0``, resulting time is negative
|
|
93
|
+
(displacement and velocity have opposite signs), or any input is non-finite.
|
|
94
|
+
"""
|
|
95
|
+
delta_x = validate_quantity(displacement, "[length]", name="displacement")
|
|
96
|
+
vel = validate_quantity(velocity, "[velocity]", name="velocity", allow_zero=False)
|
|
97
|
+
elapsed = to_si(delta_x / vel)
|
|
98
|
+
if elapsed.magnitude < 0:
|
|
99
|
+
raise PhysicalDomainError(
|
|
100
|
+
"Displacement and velocity have opposite signs, yielding a non-physical "
|
|
101
|
+
f"negative time ({elapsed})."
|
|
102
|
+
)
|
|
103
|
+
return elapsed
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
__all__ = [
|
|
107
|
+
"average_velocity",
|
|
108
|
+
"displacement",
|
|
109
|
+
"position",
|
|
110
|
+
"travel_time",
|
|
111
|
+
]
|