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
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
|
+
]
|