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 ADDED
@@ -0,0 +1,22 @@
1
+ """physu: A modular Python physics library powered by Pint."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from . import constants, exceptions, kinematics, units, validation
6
+ from .exceptions import PhysicalDomainError, PhysuError
7
+ from .units import Quantity, ureg
8
+
9
+ __version__ = "0.1.0"
10
+
11
+ __all__ = [
12
+ "PhysicalDomainError",
13
+ "PhysuError",
14
+ "Quantity",
15
+ "__version__",
16
+ "constants",
17
+ "exceptions",
18
+ "kinematics",
19
+ "units",
20
+ "ureg",
21
+ "validation",
22
+ ]
physu/constants.py ADDED
@@ -0,0 +1,56 @@
1
+ """Fundamental physical constants as Pint quantities bound to ``physu.ureg``.
2
+
3
+ Values follow the 2019 SI redefinition and CODATA 2022 recommended values.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import math
9
+
10
+ import pint
11
+
12
+ from .units import Quantity
13
+
14
+ # Mechanics & gravitation
15
+ STANDARD_GRAVITY: pint.Quantity = Quantity(9.80665, "m / s^2")
16
+ GRAVITATIONAL_CONSTANT: pint.Quantity = Quantity(6.67430e-11, "m^3 / (kg * s^2)")
17
+
18
+ # Relativity & quantum mechanics
19
+ SPEED_OF_LIGHT: pint.Quantity = Quantity(299_792_458, "m / s")
20
+ PLANCK_CONSTANT: pint.Quantity = Quantity(6.62607015e-34, "J * s")
21
+ REDUCED_PLANCK_CONSTANT: pint.Quantity = Quantity(
22
+ 6.62607015e-34 / (2.0 * math.pi),
23
+ "J * s",
24
+ )
25
+
26
+ # Electromagnetism
27
+ ELEMENTARY_CHARGE: pint.Quantity = Quantity(1.602176634e-19, "C")
28
+ VACUUM_PERMITTIVITY: pint.Quantity = Quantity(8.8541878188e-12, "F / m")
29
+ VACUUM_PERMEABILITY: pint.Quantity = Quantity(1.25663706127e-6, "N / A^2")
30
+
31
+ # Thermodynamics & chemistry
32
+ BOLTZMANN_CONSTANT: pint.Quantity = Quantity(1.380649e-23, "J / K")
33
+ AVOGADRO_CONSTANT: pint.Quantity = Quantity(6.02214076e23, "1 / mol")
34
+ MOLAR_GAS_CONSTANT: pint.Quantity = AVOGADRO_CONSTANT * BOLTZMANN_CONSTANT
35
+ STANDARD_ATMOSPHERE: pint.Quantity = Quantity(101_325, "Pa")
36
+
37
+ # Atomic & particle masses
38
+ ELECTRON_MASS: pint.Quantity = Quantity(9.1093837139e-31, "kg")
39
+ PROTON_MASS: pint.Quantity = Quantity(1.67262192595e-27, "kg")
40
+
41
+ __all__ = [
42
+ "AVOGADRO_CONSTANT",
43
+ "BOLTZMANN_CONSTANT",
44
+ "ELECTRON_MASS",
45
+ "ELEMENTARY_CHARGE",
46
+ "GRAVITATIONAL_CONSTANT",
47
+ "MOLAR_GAS_CONSTANT",
48
+ "PLANCK_CONSTANT",
49
+ "PROTON_MASS",
50
+ "REDUCED_PLANCK_CONSTANT",
51
+ "SPEED_OF_LIGHT",
52
+ "STANDARD_ATMOSPHERE",
53
+ "STANDARD_GRAVITY",
54
+ "VACUUM_PERMEABILITY",
55
+ "VACUUM_PERMITTIVITY",
56
+ ]
physu/exceptions.py ADDED
@@ -0,0 +1,18 @@
1
+ """Custom exception hierarchy for physical domain and library errors in physu."""
2
+
3
+ from __future__ import annotations
4
+
5
+
6
+ class PhysuError(Exception):
7
+ """Base exception for all physu-specific errors."""
8
+
9
+
10
+ class PhysicalDomainError(PhysuError, ValueError):
11
+ """Raised when an input violates a physical domain constraint.
12
+
13
+ Examples include negative time or mass where non-physical, zero radius or
14
+ denominator, or negative discriminants that yield non-real solutions.
15
+ """
16
+
17
+
18
+ __all__ = ["PhysicalDomainError", "PhysuError"]
@@ -0,0 +1,92 @@
1
+ """Kinematics formulas and utilities for physu."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from . import accelerated, circular, projectile, uniform, vertical
6
+ from .accelerated import (
7
+ acceleration,
8
+ displacement_from_velocities,
9
+ final_velocity,
10
+ time_to_displacement,
11
+ time_to_velocity,
12
+ torricelli_velocity,
13
+ )
14
+ from .accelerated import displacement as accelerated_displacement
15
+ from .accelerated import position as accelerated_position
16
+ from .circular import (
17
+ angular_displacement,
18
+ angular_velocity_from_frequency,
19
+ angular_velocity_from_period,
20
+ angular_velocity_from_speed,
21
+ arc_length,
22
+ centripetal_acceleration,
23
+ frequency_from_angular_velocity,
24
+ frequency_from_period,
25
+ period_from_angular_velocity,
26
+ period_from_frequency,
27
+ tangential_speed,
28
+ )
29
+ from .projectile import (
30
+ projectile_flight_time,
31
+ projectile_max_height,
32
+ projectile_position,
33
+ projectile_range,
34
+ projectile_velocity,
35
+ velocity_components,
36
+ )
37
+ from .uniform import average_velocity, displacement, position, travel_time
38
+ from .vertical import (
39
+ free_fall_distance,
40
+ free_fall_speed,
41
+ free_fall_time,
42
+ max_height,
43
+ time_to_height,
44
+ time_to_peak,
45
+ vertical_position,
46
+ vertical_velocity,
47
+ )
48
+
49
+ __all__ = [
50
+ "accelerated",
51
+ "accelerated_displacement",
52
+ "accelerated_position",
53
+ "acceleration",
54
+ "angular_displacement",
55
+ "angular_velocity_from_frequency",
56
+ "angular_velocity_from_period",
57
+ "angular_velocity_from_speed",
58
+ "arc_length",
59
+ "average_velocity",
60
+ "centripetal_acceleration",
61
+ "circular",
62
+ "displacement",
63
+ "displacement_from_velocities",
64
+ "final_velocity",
65
+ "free_fall_distance",
66
+ "free_fall_speed",
67
+ "free_fall_time",
68
+ "frequency_from_angular_velocity",
69
+ "frequency_from_period",
70
+ "max_height",
71
+ "period_from_angular_velocity",
72
+ "period_from_frequency",
73
+ "position",
74
+ "projectile",
75
+ "projectile_flight_time",
76
+ "projectile_max_height",
77
+ "projectile_position",
78
+ "projectile_range",
79
+ "projectile_velocity",
80
+ "tangential_speed",
81
+ "time_to_displacement",
82
+ "time_to_height",
83
+ "time_to_peak",
84
+ "time_to_velocity",
85
+ "torricelli_velocity",
86
+ "travel_time",
87
+ "uniform",
88
+ "velocity_components",
89
+ "vertical",
90
+ "vertical_position",
91
+ "vertical_velocity",
92
+ ]
@@ -0,0 +1,312 @@
1
+ """Uniformly Accelerated Rectilinear Motion (MRUA / SUVAT) formulas."""
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_si
11
+ from ..validation import validate_quantity
12
+
13
+ _ZERO_TOLERANCE = 1e-12
14
+
15
+
16
+ def final_velocity(
17
+ initial_velocity: QuantityLike,
18
+ acceleration: QuantityLike,
19
+ time: QuantityLike,
20
+ ) -> pint.Quantity:
21
+ """Compute final velocity: ``v = v0 + a * t``.
22
+
23
+ Args:
24
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
25
+ acceleration: Constant acceleration (dimension ``[acceleration]``).
26
+ time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
27
+
28
+ Returns:
29
+ Final velocity as an SI base ``pint.Quantity`` (``meter / second``).
30
+
31
+ Raises:
32
+ pint.DimensionalityError: If any argument has invalid dimensions.
33
+ PhysicalDomainError: If ``time < 0`` or any input is non-finite.
34
+ """
35
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
36
+ acc = validate_quantity(acceleration, "[acceleration]", name="acceleration")
37
+ elapsed = validate_quantity(time, "[time]", name="time", allow_negative=False)
38
+ return to_si(v0 + acc * elapsed)
39
+
40
+
41
+ def displacement(
42
+ initial_velocity: QuantityLike,
43
+ acceleration: QuantityLike,
44
+ time: QuantityLike,
45
+ ) -> pint.Quantity:
46
+ """Compute displacement under constant acceleration: ``dx = v0 * t + 0.5 * a * t^2``.
47
+
48
+ Args:
49
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
50
+ acceleration: Constant acceleration (dimension ``[acceleration]``).
51
+ time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
52
+
53
+ Returns:
54
+ Displacement as an SI base ``pint.Quantity`` (``meter``).
55
+
56
+ Raises:
57
+ pint.DimensionalityError: If any argument has invalid dimensions.
58
+ PhysicalDomainError: If ``time < 0`` or any input is non-finite.
59
+ """
60
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
61
+ acc = validate_quantity(acceleration, "[acceleration]", name="acceleration")
62
+ elapsed = validate_quantity(time, "[time]", name="time", allow_negative=False)
63
+ return to_si(v0 * elapsed + 0.5 * acc * elapsed**2)
64
+
65
+
66
+ def position(
67
+ initial_position: QuantityLike,
68
+ initial_velocity: QuantityLike,
69
+ acceleration: QuantityLike,
70
+ time: QuantityLike,
71
+ ) -> pint.Quantity:
72
+ """Compute position under constant acceleration: ``x = x0 + v0 * t + 0.5 * a * t^2``.
73
+
74
+ Args:
75
+ initial_position: Initial position (dimension ``[length]``).
76
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
77
+ acceleration: Constant acceleration (dimension ``[acceleration]``).
78
+ time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
79
+
80
+ Returns:
81
+ Position as an SI base ``pint.Quantity`` (``meter``).
82
+
83
+ Raises:
84
+ pint.DimensionalityError: If any argument has invalid dimensions.
85
+ PhysicalDomainError: If ``time < 0`` or any input is non-finite.
86
+ """
87
+ x0 = validate_quantity(initial_position, "[length]", name="initial_position")
88
+ delta_x = displacement(initial_velocity, acceleration, time)
89
+ return to_si(x0 + delta_x)
90
+
91
+
92
+ def displacement_from_velocities(
93
+ initial_velocity: QuantityLike,
94
+ final_velocity: QuantityLike,
95
+ time: QuantityLike,
96
+ ) -> pint.Quantity:
97
+ """Compute displacement from average velocity: ``dx = 0.5 * (v0 + v) * t``.
98
+
99
+ Args:
100
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
101
+ final_velocity: Final velocity (dimension ``[velocity]``).
102
+ time: Elapsed time (dimension ``[time]``, must be ``>= 0``).
103
+
104
+ Returns:
105
+ Displacement as an SI base ``pint.Quantity`` (``meter``).
106
+
107
+ Raises:
108
+ pint.DimensionalityError: If any argument has invalid dimensions.
109
+ PhysicalDomainError: If ``time < 0`` or any input is non-finite.
110
+ """
111
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
112
+ vf = validate_quantity(final_velocity, "[velocity]", name="final_velocity")
113
+ elapsed = validate_quantity(time, "[time]", name="time", allow_negative=False)
114
+ return to_si(0.5 * (v0 + vf) * elapsed)
115
+
116
+
117
+ def acceleration(
118
+ initial_velocity: QuantityLike,
119
+ final_velocity: QuantityLike,
120
+ time: QuantityLike,
121
+ ) -> pint.Quantity:
122
+ """Compute constant acceleration: ``a = (v - v0) / t``.
123
+
124
+ Args:
125
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
126
+ final_velocity: Final velocity (dimension ``[velocity]``).
127
+ time: Elapsed time (dimension ``[time]``, must be ``> 0``).
128
+
129
+ Returns:
130
+ Acceleration as an SI base ``pint.Quantity`` (``meter / second ** 2``).
131
+
132
+ Raises:
133
+ pint.DimensionalityError: If any argument has invalid dimensions.
134
+ PhysicalDomainError: If ``time <= 0`` or any input is non-finite.
135
+ """
136
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
137
+ vf = validate_quantity(final_velocity, "[velocity]", name="final_velocity")
138
+ elapsed = validate_quantity(
139
+ time,
140
+ "[time]",
141
+ name="time",
142
+ allow_negative=False,
143
+ allow_zero=False,
144
+ )
145
+ return to_si((vf - v0) / elapsed)
146
+
147
+
148
+ def torricelli_velocity(
149
+ initial_velocity: QuantityLike,
150
+ acceleration: QuantityLike,
151
+ displacement: QuantityLike,
152
+ ) -> pint.Quantity:
153
+ """Compute speed magnitude via Torricelli's equation: ``|v| = sqrt(v0^2 + 2 * a * dx)``.
154
+
155
+ Args:
156
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
157
+ acceleration: Constant acceleration (dimension ``[acceleration]``).
158
+ displacement: Displacement (dimension ``[length]``).
159
+
160
+ Returns:
161
+ Non-negative speed magnitude as an SI base ``pint.Quantity`` (``meter / second``).
162
+
163
+ Raises:
164
+ pint.DimensionalityError: If any argument has invalid dimensions.
165
+ PhysicalDomainError: If ``v0^2 + 2 * a * dx < 0`` or any input is non-finite.
166
+ """
167
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
168
+ acc = validate_quantity(acceleration, "[acceleration]", name="acceleration")
169
+ dx = validate_quantity(displacement, "[length]", name="displacement")
170
+
171
+ v_squared = (v0**2 + 2.0 * acc * dx).to_base_units()
172
+ mag = float(v_squared.magnitude)
173
+ if mag < 0.0:
174
+ if math.isclose(mag, 0.0, abs_tol=_ZERO_TOLERANCE):
175
+ mag = 0.0
176
+ else:
177
+ raise PhysicalDomainError(
178
+ "Target displacement is unreachable under the given acceleration: "
179
+ f"v^2 = {v_squared} < 0."
180
+ )
181
+ return Quantity(math.sqrt(mag), "m / s")
182
+
183
+
184
+ def time_to_velocity(
185
+ initial_velocity: QuantityLike,
186
+ final_velocity: QuantityLike,
187
+ acceleration: QuantityLike,
188
+ ) -> pint.Quantity:
189
+ """Compute elapsed time to reach ``final_velocity``: ``t = (v - v0) / a``.
190
+
191
+ Args:
192
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
193
+ final_velocity: Target velocity (dimension ``[velocity]``).
194
+ acceleration: Constant acceleration (dimension ``[acceleration]``, must be ``!= 0``).
195
+
196
+ Returns:
197
+ Elapsed time as an SI base ``pint.Quantity`` (``second``).
198
+
199
+ Raises:
200
+ pint.DimensionalityError: If any argument has invalid dimensions.
201
+ PhysicalDomainError: If ``acceleration == 0``, resulting time is negative,
202
+ or any input is non-finite.
203
+ """
204
+ v0 = validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
205
+ vf = validate_quantity(final_velocity, "[velocity]", name="final_velocity")
206
+ acc = validate_quantity(
207
+ acceleration,
208
+ "[acceleration]",
209
+ name="acceleration",
210
+ allow_zero=False,
211
+ )
212
+ elapsed = to_si((vf - v0) / acc)
213
+ if elapsed.magnitude < 0:
214
+ raise PhysicalDomainError(
215
+ "Target velocity cannot be reached at non-negative time with the given "
216
+ f"acceleration ({elapsed})."
217
+ )
218
+ return elapsed
219
+
220
+
221
+ def time_to_displacement(
222
+ initial_velocity: QuantityLike,
223
+ acceleration: QuantityLike,
224
+ displacement: QuantityLike,
225
+ ) -> tuple[pint.Quantity, ...]:
226
+ """Solve ``0.5 * a * t^2 + v0 * t = dx`` for non-negative elapsed time(s) ``t >= 0``.
227
+
228
+ Args:
229
+ initial_velocity: Initial velocity (dimension ``[velocity]``).
230
+ acceleration: Constant acceleration (dimension ``[acceleration]``).
231
+ displacement: Target displacement (dimension ``[length]``).
232
+
233
+ Returns:
234
+ A tuple of 1 or 2 sorted non-negative ``pint.Quantity`` times (``second``).
235
+
236
+ Raises:
237
+ pint.DimensionalityError: If any argument has invalid dimensions.
238
+ PhysicalDomainError: If the displacement is unreachable, indeterminate
239
+ (``v0 == 0``, ``a == 0``, ``dx == 0``), or only occurs for ``t < 0``.
240
+ """
241
+ v0 = float(
242
+ validate_quantity(initial_velocity, "[velocity]", name="initial_velocity")
243
+ .to("m / s")
244
+ .magnitude
245
+ )
246
+ acc = float(
247
+ validate_quantity(acceleration, "[acceleration]", name="acceleration")
248
+ .to("m / s^2")
249
+ .magnitude
250
+ )
251
+ dx = float(
252
+ validate_quantity(displacement, "[length]", name="displacement")
253
+ .to("m")
254
+ .magnitude
255
+ )
256
+
257
+ if math.isclose(acc, 0.0, abs_tol=_ZERO_TOLERANCE):
258
+ if math.isclose(v0, 0.0, abs_tol=_ZERO_TOLERANCE):
259
+ if math.isclose(dx, 0.0, abs_tol=_ZERO_TOLERANCE):
260
+ raise PhysicalDomainError(
261
+ "Time is indeterminate when initial_velocity, acceleration, "
262
+ "and displacement are all zero."
263
+ )
264
+ raise PhysicalDomainError(
265
+ "Target non-zero displacement is unreachable when initial_velocity "
266
+ "and acceleration are both zero."
267
+ )
268
+ t_linear = dx / v0
269
+ if t_linear < -_ZERO_TOLERANCE:
270
+ raise PhysicalDomainError(
271
+ f"Target displacement is only reached at negative time ({t_linear} s)."
272
+ )
273
+ return (Quantity(max(0.0, t_linear), "s"),)
274
+
275
+ discriminant = v0**2 + 2.0 * acc * dx
276
+ if discriminant < -_ZERO_TOLERANCE:
277
+ raise PhysicalDomainError(
278
+ "Target displacement is unreachable: quadratic discriminant is negative "
279
+ f"({discriminant} m^2 / s^2)."
280
+ )
281
+
282
+ sqrt_disc = math.sqrt(max(0.0, discriminant))
283
+ raw_roots = [(-v0 - sqrt_disc) / acc, (-v0 + sqrt_disc) / acc]
284
+
285
+ valid_roots: list[float] = []
286
+ for root in sorted(raw_roots):
287
+ if root >= -_ZERO_TOLERANCE:
288
+ snapped = 0.0 if root < 0.0 else root
289
+ if not any(
290
+ math.isclose(snapped, existing, abs_tol=_ZERO_TOLERANCE)
291
+ for existing in valid_roots
292
+ ):
293
+ valid_roots.append(snapped)
294
+
295
+ if not valid_roots:
296
+ raise PhysicalDomainError(
297
+ "Target displacement is only reached at negative (non-physical) times."
298
+ )
299
+
300
+ return tuple(Quantity(t_val, "s") for t_val in valid_roots)
301
+
302
+
303
+ __all__ = [
304
+ "acceleration",
305
+ "displacement",
306
+ "displacement_from_velocities",
307
+ "final_velocity",
308
+ "position",
309
+ "time_to_displacement",
310
+ "time_to_velocity",
311
+ "torricelli_velocity",
312
+ ]