physu 0.2.0__tar.gz → 0.3.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.
Files changed (50) hide show
  1. {physu-0.2.0 → physu-0.3.0}/PKG-INFO +14 -7
  2. {physu-0.2.0 → physu-0.3.0}/README.md +12 -5
  3. physu-0.3.0/changelogs/0.3.md +19 -0
  4. physu-0.3.0/examples/dynamics_elasticity_momentum_gravitation.py +59 -0
  5. physu-0.3.0/examples/dynamics_forces_and_friction.py +41 -0
  6. physu-0.3.0/examples/energy_work_and_power.py +60 -0
  7. physu-0.3.0/examples/kinematics_1d.py +46 -0
  8. physu-0.3.0/examples/kinematics_2d_and_circular.py +52 -0
  9. physu-0.3.0/examples/units_and_validation.py +71 -0
  10. {physu-0.2.0 → physu-0.3.0}/pyproject.toml +2 -1
  11. {physu-0.2.0 → physu-0.3.0}/src/physu/__init__.py +3 -2
  12. physu-0.3.0/src/physu/energy/__init__.py +67 -0
  13. physu-0.3.0/src/physu/energy/conservation.py +208 -0
  14. physu-0.3.0/src/physu/energy/kinetic.py +120 -0
  15. physu-0.3.0/src/physu/energy/potential.py +99 -0
  16. physu-0.3.0/src/physu/energy/power.py +150 -0
  17. physu-0.3.0/src/physu/energy/work.py +129 -0
  18. physu-0.3.0/tests/test_energy.py +279 -0
  19. physu-0.2.0/examples/dynamics_elasticity_momentum_gravitation.py +0 -59
  20. physu-0.2.0/examples/dynamics_forces_and_friction.py +0 -47
  21. physu-0.2.0/examples/kinematics_1d.py +0 -57
  22. physu-0.2.0/examples/kinematics_2d_and_circular.py +0 -52
  23. physu-0.2.0/examples/units_and_validation.py +0 -53
  24. {physu-0.2.0 → physu-0.3.0}/.gitignore +0 -0
  25. {physu-0.2.0 → physu-0.3.0}/AGENTS.md +0 -0
  26. {physu-0.2.0 → physu-0.3.0}/LICENSE +0 -0
  27. {physu-0.2.0 → physu-0.3.0}/changelogs/0.1.md +0 -0
  28. {physu-0.2.0 → physu-0.3.0}/changelogs/0.2.md +0 -0
  29. {physu-0.2.0 → physu-0.3.0}/src/physu/constants.py +0 -0
  30. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/__init__.py +0 -0
  31. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/elasticity.py +0 -0
  32. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/friction.py +0 -0
  33. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/gravitation.py +0 -0
  34. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/momentum.py +0 -0
  35. {physu-0.2.0 → physu-0.3.0}/src/physu/dynamics/newton.py +0 -0
  36. {physu-0.2.0 → physu-0.3.0}/src/physu/exceptions.py +0 -0
  37. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/__init__.py +0 -0
  38. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/accelerated.py +0 -0
  39. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/circular.py +0 -0
  40. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/projectile.py +0 -0
  41. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/uniform.py +0 -0
  42. {physu-0.2.0 → physu-0.3.0}/src/physu/kinematics/vertical.py +0 -0
  43. {physu-0.2.0 → physu-0.3.0}/src/physu/py.typed +0 -0
  44. {physu-0.2.0 → physu-0.3.0}/src/physu/units.py +0 -0
  45. {physu-0.2.0 → physu-0.3.0}/src/physu/validation.py +0 -0
  46. {physu-0.2.0 → physu-0.3.0}/tests/test_constants.py +0 -0
  47. {physu-0.2.0 → physu-0.3.0}/tests/test_dynamics.py +0 -0
  48. {physu-0.2.0 → physu-0.3.0}/tests/test_kinematics.py +0 -0
  49. {physu-0.2.0 → physu-0.3.0}/tests/test_units.py +0 -0
  50. {physu-0.2.0 → physu-0.3.0}/tests/test_validation.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: physu
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: A modular Python physics library with strict unit and dimensional validation powered by Pint.
5
5
  Project-URL: Homepage, https://github.com/taxnam23
6
6
  Project-URL: Repository, https://github.com/taxnam23/physu
@@ -8,7 +8,7 @@ Project-URL: Issues, https://github.com/taxnam23/physu/issues
8
8
  Author-email: taxnam23 <tarfanam342@gmail.com>
9
9
  License-Expression: MIT
10
10
  License-File: LICENSE
11
- Keywords: dimensional-analysis,dynamics,kinematics,physics,pint,scientific-computing,units
11
+ Keywords: dimensional-analysis,dynamics,energy,kinematics,physics,pint,scientific-computing,units
12
12
  Classifier: Development Status :: 3 - Alpha
13
13
  Classifier: Intended Audience :: Developers
14
14
  Classifier: Intended Audience :: Education
@@ -59,11 +59,12 @@ Requires Python `>= 3.10`.
59
59
 
60
60
  Runnable scripts covering every module and submodule live in [examples/](examples/):
61
61
 
62
- - [units_and_validation.py](examples/units_and_validation.py) — units, constants, validation helpers, and error handling
63
- - [kinematics_1d.py](examples/kinematics_1d.py) — uniform, accelerated (MRUA/SUVAT), and vertical motion
64
- - [kinematics_2d_and_circular.py](examples/kinematics_2d_and_circular.py) — 2D projectile and uniform circular motion
65
- - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — Newton's laws, inclined planes, and friction
66
- - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — Hooke's law, momentum/collisions, and gravitation
62
+ - [units_and_validation.py](examples/units_and_validation.py) — drone telemetry normalization and sensor error handling
63
+ - [kinematics_1d.py](examples/kinematics_1d.py) — highway emergency braking and bridge drop check
64
+ - [kinematics_2d_and_circular.py](examples/kinematics_2d_and_circular.py) — firefighter hose targeting and washing machine spin G-load
65
+ - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — inclined ramp winch sizing and crate slip threshold
66
+ - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — vehicle suspension sag, rear-end impact force, and CubeSat LEO orbit
67
+ - [energy_work_and_power.py](examples/energy_work_and_power.py) — crane hoist motor sizing, spring coaster launch, and LEO escape speed
67
68
 
68
69
  ## Modules
69
70
 
@@ -83,6 +84,12 @@ Runnable scripts covering every module and submodule live in [examples/](example
83
84
  - `elasticity`: Hooke's law and springs (`spring_force`, `spring_force_magnitude`, `spring_constant`, `spring_displacement`, `series_spring_constant`, `parallel_spring_constant`)
84
85
  - `momentum`: Linear momentum, impulse, and 1D collisions (`linear_momentum`, `impulse`, `momentum_change`, `average_force`, `collision_velocities`, `elastic_collision_velocities`, `inelastic_collision_velocity`)
85
86
  - `gravitation`: Universal gravitation and circular dynamics (`gravitational_force`, `gravitational_field_strength`, `orbital_speed`, `centripetal_force`)
87
+ - **`physu.energy`**:
88
+ - `work`: Mechanical work and work-energy theorem (`mechanical_work`, `net_work`, `gravitational_work`, `elastic_work`)
89
+ - `kinetic`: Translational kinetic energy (`kinetic_energy`, `kinetic_energy_from_momentum`, `speed_from_kinetic_energy`, `momentum_from_kinetic_energy`)
90
+ - `potential`: Gravitational and elastic potential energy (`gravitational_potential_energy`, `universal_gravitational_potential_energy`, `elastic_potential_energy`)
91
+ - `conservation`: Mechanical energy conservation and efficiency (`mechanical_energy`, `non_conservative_work`, `final_speed_conservation`, `final_height_conservation`, `escape_speed`, `mechanical_efficiency`)
92
+ - `power`: Mechanical power (`average_power`, `instantaneous_power`, `work_from_power`, `force_from_power`, `velocity_from_power`)
86
93
 
87
94
  ## Development
88
95
 
@@ -27,11 +27,12 @@ Requires Python `>= 3.10`.
27
27
 
28
28
  Runnable scripts covering every module and submodule live in [examples/](examples/):
29
29
 
30
- - [units_and_validation.py](examples/units_and_validation.py) — units, constants, validation helpers, and error handling
31
- - [kinematics_1d.py](examples/kinematics_1d.py) — uniform, accelerated (MRUA/SUVAT), and vertical motion
32
- - [kinematics_2d_and_circular.py](examples/kinematics_2d_and_circular.py) — 2D projectile and uniform circular motion
33
- - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — Newton's laws, inclined planes, and friction
34
- - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — Hooke's law, momentum/collisions, and gravitation
30
+ - [units_and_validation.py](examples/units_and_validation.py) — drone telemetry normalization and sensor error handling
31
+ - [kinematics_1d.py](examples/kinematics_1d.py) — highway emergency braking and bridge drop check
32
+ - [kinematics_2d_and_circular.py](examples/kinematics_2d_and_circular.py) — firefighter hose targeting and washing machine spin G-load
33
+ - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — inclined ramp winch sizing and crate slip threshold
34
+ - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — vehicle suspension sag, rear-end impact force, and CubeSat LEO orbit
35
+ - [energy_work_and_power.py](examples/energy_work_and_power.py) — crane hoist motor sizing, spring coaster launch, and LEO escape speed
35
36
 
36
37
  ## Modules
37
38
 
@@ -51,6 +52,12 @@ Runnable scripts covering every module and submodule live in [examples/](example
51
52
  - `elasticity`: Hooke's law and springs (`spring_force`, `spring_force_magnitude`, `spring_constant`, `spring_displacement`, `series_spring_constant`, `parallel_spring_constant`)
52
53
  - `momentum`: Linear momentum, impulse, and 1D collisions (`linear_momentum`, `impulse`, `momentum_change`, `average_force`, `collision_velocities`, `elastic_collision_velocities`, `inelastic_collision_velocity`)
53
54
  - `gravitation`: Universal gravitation and circular dynamics (`gravitational_force`, `gravitational_field_strength`, `orbital_speed`, `centripetal_force`)
55
+ - **`physu.energy`**:
56
+ - `work`: Mechanical work and work-energy theorem (`mechanical_work`, `net_work`, `gravitational_work`, `elastic_work`)
57
+ - `kinetic`: Translational kinetic energy (`kinetic_energy`, `kinetic_energy_from_momentum`, `speed_from_kinetic_energy`, `momentum_from_kinetic_energy`)
58
+ - `potential`: Gravitational and elastic potential energy (`gravitational_potential_energy`, `universal_gravitational_potential_energy`, `elastic_potential_energy`)
59
+ - `conservation`: Mechanical energy conservation and efficiency (`mechanical_energy`, `non_conservative_work`, `final_speed_conservation`, `final_height_conservation`, `escape_speed`, `mechanical_efficiency`)
60
+ - `power`: Mechanical power (`average_power`, `instantaneous_power`, `work_from_power`, `force_from_power`, `velocity_from_power`)
54
61
 
55
62
  ## Development
56
63
 
@@ -0,0 +1,19 @@
1
+ # `physu` 0.3.0 (2026-11-17)
2
+
3
+ Adds mechanical work, energy, conservation, and power (`physu.energy`), plus real-world runnable examples across every domain.
4
+
5
+ ## Added
6
+
7
+ ### Energy (`physu.energy`)
8
+ - **`work`**: Constant-force work (`mechanical_work`), work-energy theorem (`net_work`), `gravitational_work`, and `elastic_work`.
9
+ - **`kinetic`**: Translational kinetic energy (`kinetic_energy`, `kinetic_energy_from_momentum`, `speed_from_kinetic_energy`, `momentum_from_kinetic_energy`).
10
+ - **`potential`**: Near-surface and universal gravitational potential energy (`gravitational_potential_energy`, `universal_gravitational_potential_energy`) and `elastic_potential_energy`.
11
+ - **`conservation`**: Total mechanical energy (`mechanical_energy`), `non_conservative_work`, conservation solvers (`final_speed_conservation`, `final_height_conservation`), `escape_speed`, and `mechanical_efficiency`.
12
+ - **`power`**: Mechanical power (`average_power`, `instantaneous_power`, `work_from_power`, `force_from_power`, `velocity_from_power`).
13
+
14
+ ### Examples & Tests
15
+ - Added real-world energy/power sizing script [energy_work_and_power.py](../examples/energy_work_and_power.py).
16
+ - Added unit tests in `tests/test_energy.py` (50 tests total across the suite), verified with `ruff` and strict `mypy`.
17
+
18
+ ## Changed
19
+ - Replaced dry per-function prints across `examples/` with realistic real-world engineering and everyday physics scenarios, and updated `README.md`.
@@ -0,0 +1,59 @@
1
+ """Real-world examples: vehicle suspension sag, rear-end impact, and CubeSat orbit."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.dynamics import (
6
+ average_force,
7
+ centripetal_force,
8
+ gravitational_field_strength,
9
+ inelastic_collision_velocity,
10
+ momentum_change,
11
+ newton,
12
+ orbital_speed,
13
+ parallel_spring_constant,
14
+ spring_displacement,
15
+ )
16
+
17
+
18
+ def main() -> None:
19
+ """Run three practical dynamics calculations."""
20
+ # 1. Rear suspension sag on a loaded utility van (two parallel coil springs)
21
+ rear_axle_load = newton.weight("650 kg")
22
+ k_eq = parallel_spring_constant(["28 kN/m", "28 kN/m"])
23
+ # Upward spring restoring force balances downward axle weight (+rear_axle_load)
24
+ sag = spring_displacement(rear_axle_load, k_eq)
25
+
26
+ print("=== Rear Suspension Compression ===")
27
+ print(f"Combined stiffness: {k_eq.to('kN/m'):.1f} | Sag under 650 kg: {sag.to('cm'):.2f}")
28
+
29
+ # 2. Low-speed rear-end collision force estimate (inelastic bumper lock)
30
+ car1_mass = "1500 kg"
31
+ car1_speed = "36 km/h"
32
+ car2_mass = "1200 kg"
33
+ impact_duration = "120 ms"
34
+
35
+ v_after = inelastic_collision_velocity(car1_mass, car1_speed, car2_mass, "0 m/s")
36
+ impulse_car2 = momentum_change(car2_mass, "0 m/s", v_after)
37
+ avg_impact_force = average_force(impulse_car2, impact_duration)
38
+
39
+ print("\n=== Low-Speed Rear-End Collision ===")
40
+ print(f"Shared speed right after impact: {v_after.to('km/h'):.1f}")
41
+ print(f"Average force over {impact_duration}: {avg_impact_force.to('kN'):.2f}")
42
+
43
+ # 3. 12 kg CubeSat in a 550 km Low Earth Orbit (Earth radius 6371 km)
44
+ earth_mass = "5.9722e24 kg"
45
+ orbit_radius = "6921 km"
46
+ cubesat_mass = "12 kg"
47
+
48
+ local_g = gravitational_field_strength(earth_mass, orbit_radius)
49
+ v_orbit = orbital_speed(earth_mass, orbit_radius)
50
+ f_gravity_orbit = centripetal_force(cubesat_mass, orbit_radius, tangential_speed=v_orbit)
51
+
52
+ print("\n=== CubeSat Orbit Check (550 km altitude) ===")
53
+ print(f"Local gravity at 550 km: {local_g:.2f}")
54
+ print(f"Orbital velocity: {v_orbit.to('km/s'):.2f}")
55
+ print(f"Centripetal gravitational force on 12 kg CubeSat: {f_gravity_orbit:.2f}")
56
+
57
+
58
+ if __name__ == "__main__":
59
+ main()
@@ -0,0 +1,41 @@
1
+ """Real-world example: loading a heavy crate up an inclined steel ramp."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.dynamics import (
6
+ critical_incline_angle,
7
+ inclined_normal_force,
8
+ inclined_parallel_force,
9
+ kinetic_friction,
10
+ max_static_friction,
11
+ )
12
+
13
+
14
+ def main() -> None:
15
+ """Evaluate slip risk and winch pulling forces on a 18-degree loading ramp."""
16
+ crate_mass = "450 kg"
17
+ ramp_angle = "18 deg"
18
+ mu_static = 0.42
19
+ mu_kinetic = 0.30
20
+
21
+ repose_angle = critical_incline_angle(mu_static).to("deg")
22
+ gravity_pull = inclined_parallel_force(crate_mass, ramp_angle)
23
+ normal = inclined_normal_force(crate_mass, ramp_angle)
24
+ max_hold = max_static_friction(mu_static, normal)
25
+ sliding_friction = kinetic_friction(mu_kinetic, normal)
26
+
27
+ # Pulling force up the ramp must overcome gravity component + friction
28
+ breakaway_pull = gravity_pull + max_hold
29
+ steady_winch_pull = gravity_pull + sliding_friction
30
+
31
+ print("=== Inclined Ramp Winch Sizing (450 kg crate, 18 deg) ===")
32
+ print(f"Self-slip threshold (angle of repose): {repose_angle:.2f}")
33
+ holds_stationary = "YES" if repose_angle.magnitude > 18.0 else "NO"
34
+ print(f"Crate holds stationary without brakes? {holds_stationary}")
35
+ print(f"Gravity component down ramp: {gravity_pull:.1f} | Normal force: {normal:.1f}")
36
+ print(f"Breakaway winch force needed: {breakaway_pull:.1f}")
37
+ print(f"Steady winch pull while moving: {steady_winch_pull:.1f}")
38
+
39
+
40
+ if __name__ == "__main__":
41
+ main()
@@ -0,0 +1,60 @@
1
+ """Real-world examples: crane hoist motor sizing, spring coaster launch, and escape speed."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.energy import (
6
+ average_power,
7
+ elastic_potential_energy,
8
+ escape_speed,
9
+ final_speed_conservation,
10
+ gravitational_potential_energy,
11
+ speed_from_kinetic_energy,
12
+ )
13
+ from physu.units import to_unit
14
+
15
+
16
+ def main() -> None:
17
+ """Solve practical engineering energy and power sizing problems."""
18
+ # 1. Construction crane lifting a 1.2-tonne steel I-beam up 18 m in 25 s
19
+ beam_mass = "1200 kg"
20
+ lift_height = "18 m"
21
+ lift_duration = "25 s"
22
+ hoist_efficiency = 0.82
23
+
24
+ useful_energy = gravitational_potential_energy(beam_mass, lift_height)
25
+ useful_power = average_power(useful_energy, lift_duration)
26
+ required_motor_power = to_unit(useful_power / hoist_efficiency, "kW")
27
+ electrical_energy_per_lift = to_unit(useful_energy / hoist_efficiency, "kWh")
28
+
29
+ print("=== Construction Crane Hoist Sizing ===")
30
+ print(f"Useful lifting energy: {useful_energy.to('kJ'):.1f}")
31
+ print(f"Output shaft power: {useful_power.to('kW'):.2f}")
32
+ print(
33
+ f"Required motor input (@82% eff.): {required_motor_power:.2f} "
34
+ f"({required_motor_power.to('hp'):.2f})"
35
+ )
36
+ print(f"Grid energy per lift: {electrical_energy_per_lift:.4f}")
37
+
38
+ # 2. Spring-launched coaster cart climbing a 12 m hill
39
+ cart_mass = "250 kg"
40
+ launcher_k = "32 kN/m"
41
+ spring_compression = "1.6 m"
42
+ hill_height = "12 m"
43
+
44
+ stored_elastic = elastic_potential_energy(launcher_k, spring_compression)
45
+ launch_speed = speed_from_kinetic_energy(stored_elastic, cart_mass)
46
+ crest_speed = final_speed_conservation(launch_speed, "0 m", hill_height)
47
+
48
+ print("\n=== Spring-Launched Coaster Cart ===")
49
+ print(f"Stored launcher energy: {stored_elastic.to('kJ'):.2f}")
50
+ print(f"Launch speed: {launch_speed:.2f} ({launch_speed.to('km/h'):.1f})")
51
+ print(f"Speed clearing 12 m crest (frictionless): {crest_speed:.2f}")
52
+
53
+ # 3. Minimum Earth escape speed from a 500 km orbital parking altitude
54
+ v_esc = escape_speed("5.9722e24 kg", "6871 km")
55
+ print("\n=== Deep-Space Departure from 500 km LEO ===")
56
+ print(f"Escape speed needed: {v_esc.to('km/s'):.2f}")
57
+
58
+
59
+ if __name__ == "__main__":
60
+ main()
@@ -0,0 +1,46 @@
1
+ """Real-world example: highway emergency braking check and bridge clearance drop."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.kinematics import (
6
+ accelerated_displacement,
7
+ displacement,
8
+ free_fall_speed,
9
+ free_fall_time,
10
+ time_to_velocity,
11
+ )
12
+
13
+
14
+ def main() -> None:
15
+ """Analyze safe highway braking distance and a dropped inspection sensor."""
16
+ # Scenario 1: Emergency braking on a wet highway
17
+ cruise_speed = "110 km/h"
18
+ reaction_time = "1.2 s"
19
+ braking_decel = "-6.5 m/s^2"
20
+ hazard_distance = "95 m"
21
+
22
+ reaction_dist = displacement(cruise_speed, reaction_time)
23
+ braking_time = time_to_velocity(cruise_speed, "0 m/s", braking_decel)
24
+ braking_dist = accelerated_displacement(cruise_speed, braking_decel, braking_time)
25
+ total_stopping_dist = reaction_dist + braking_dist
26
+
27
+ print("=== Highway Emergency Braking ===")
28
+ print(f"Cruise speed: {cruise_speed} | Reaction distance (1.2 s): {reaction_dist:.2f}")
29
+ print(f"Braking time: {braking_time:.2f} | Braking distance: {braking_dist:.2f}")
30
+ print(f"Total stopping distance: {total_stopping_dist:.2f} (hazard at {hazard_distance})")
31
+ margin = total_stopping_dist.to("m").magnitude
32
+ print(f"Clears hazard before impact? {'YES' if margin < 95.0 else 'NO'}")
33
+
34
+ # Scenario 2: Dropping an acoustic depth probe from a 38 m bridge
35
+ bridge_height = "38 m"
36
+ t_splash = free_fall_time(bridge_height)
37
+ v_splash = free_fall_speed(bridge_height)
38
+
39
+ print("\n=== Bridge Drop Sensor Check ===")
40
+ print(f"Drop height: {bridge_height}")
41
+ print(f"Time to water impact: {t_splash:.2f}")
42
+ print(f"Water entry speed: {v_splash:.2f} ({v_splash.to('km/h'):.1f})")
43
+
44
+
45
+ if __name__ == "__main__":
46
+ main()
@@ -0,0 +1,52 @@
1
+ """Real-world example: firefighter hose targeting and washing machine spin G-force."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.constants import STANDARD_GRAVITY
6
+ from physu.kinematics import (
7
+ centripetal_acceleration,
8
+ projectile_position,
9
+ projectile_range,
10
+ tangential_speed,
11
+ travel_time,
12
+ velocity_components,
13
+ )
14
+
15
+
16
+ def main() -> None:
17
+ """Compute building-wall water stream height and drum spin G-load."""
18
+ # Scenario 1: Aiming a fire hose at a third-floor window 32 m away
19
+ nozzle_speed = "24 m/s"
20
+ aim_angle = "40 deg"
21
+ nozzle_height = "1.2 m"
22
+ building_distance = "32 m"
23
+
24
+ vx, _ = velocity_components(nozzle_speed, aim_angle)
25
+ t_reach_wall = travel_time(building_distance, vx)
26
+ x_wall, y_wall = projectile_position(
27
+ nozzle_speed,
28
+ aim_angle,
29
+ t_reach_wall,
30
+ initial_height=nozzle_height,
31
+ )
32
+ max_ground_range = projectile_range(nozzle_speed, aim_angle, initial_height=nozzle_height)
33
+
34
+ print("=== Firefighter Hose Targeting ===")
35
+ print(f"Jet reaches wall ({x_wall:.1f}) at t={t_reach_wall:.2f} and height={y_wall:.2f}")
36
+ print(f"Unobstructed ground range: {max_ground_range:.2f}")
37
+
38
+ # Scenario 2: Washing machine spin cycle G-force on wet laundry
39
+ drum_radius = "26 cm"
40
+ spin_rate = "1200 rpm"
41
+
42
+ rim_speed = tangential_speed(spin_rate, drum_radius)
43
+ a_c = centripetal_acceleration(drum_radius, angular_velocity=spin_rate)
44
+ g_force = (a_c / STANDARD_GRAVITY).to("dimensionless")
45
+
46
+ print("\n=== Washing Machine Spin Cycle (1200 rpm) ===")
47
+ print(f"Drum rim speed: {rim_speed:.2f} ({rim_speed.to('km/h'):.1f})")
48
+ print(f"Centripetal acceleration: {a_c:.1f} (~{g_force.magnitude:.0f} g)")
49
+
50
+
51
+ if __name__ == "__main__":
52
+ main()
@@ -0,0 +1,71 @@
1
+ """Real-world example: validating and normalizing mixed-unit drone telemetry payloads."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pint
6
+
7
+ from physu import PhysicalDomainError, Quantity, ureg
8
+ from physu.constants import STANDARD_GRAVITY
9
+ from physu.units import to_si, to_unit
10
+ from physu.validation import require_range, validate_quantity
11
+
12
+
13
+ def parse_telemetry_packet(
14
+ payload: dict[str, object],
15
+ ) -> tuple[pint.Quantity, pint.Quantity, pint.Quantity]:
16
+ """Validate incoming drone telemetry and normalize units for the flight controller."""
17
+ battery_mass = validate_quantity(
18
+ payload["battery_mass"], # type: ignore[arg-type]
19
+ "[mass]",
20
+ name="battery_mass",
21
+ allow_negative=False,
22
+ allow_zero=False,
23
+ )
24
+ airspeed = validate_quantity(
25
+ payload["airspeed"], # type: ignore[arg-type]
26
+ "[velocity]",
27
+ name="airspeed",
28
+ allow_negative=False,
29
+ )
30
+ pitch_angle = require_range(
31
+ validate_quantity(payload["pitch"], "rad", name="pitch"), # type: ignore[arg-type]
32
+ min_value=Quantity(-45, "deg"),
33
+ max_value=Quantity(45, "deg"),
34
+ name="pitch",
35
+ )
36
+ return to_unit(battery_mass, "kg"), to_si(airspeed), to_unit(pitch_angle, "deg")
37
+
38
+
39
+ def main() -> None:
40
+ """Validate valid and faulty telemetry packets from heterogeneous sensors."""
41
+ external_sensor_reg = pint.UnitRegistry()
42
+
43
+ valid_packet: dict[str, object] = {
44
+ "battery_mass": external_sensor_reg.Quantity(1450, "g"),
45
+ "airspeed": "65 km/h",
46
+ "pitch": 12 * ureg.deg,
47
+ }
48
+ mass, speed, pitch = parse_telemetry_packet(valid_packet)
49
+ hover_weight = to_unit(mass * STANDARD_GRAVITY, "N")
50
+ print(f"Valid telemetry -> mass={mass}, airspeed={speed:.2f}, pitch={pitch}")
51
+ print(f"Battery weight load on frame: {hover_weight:.2f}")
52
+
53
+ corrupted_packets: list[tuple[str, dict[str, object]]] = [
54
+ (
55
+ "unit mismatch (pressure sent instead of speed)",
56
+ {"battery_mass": "1.5 kg", "airspeed": "101 kPa", "pitch": "10 deg"},
57
+ ),
58
+ (
59
+ "out-of-bounds pitch (nose dive)",
60
+ {"battery_mass": "1.5 kg", "airspeed": "15 m/s", "pitch": "-70 deg"},
61
+ ),
62
+ ]
63
+ for label, packet in corrupted_packets:
64
+ try:
65
+ parse_telemetry_packet(packet)
66
+ except (pint.DimensionalityError, PhysicalDomainError) as exc:
67
+ print(f"Rejected {label}: {exc}")
68
+
69
+
70
+ if __name__ == "__main__":
71
+ main()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "physu"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "A modular Python physics library with strict unit and dimensional validation powered by Pint."
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -20,6 +20,7 @@ keywords = [
20
20
  "dimensional-analysis",
21
21
  "kinematics",
22
22
  "dynamics",
23
+ "energy",
23
24
  "scientific-computing",
24
25
  ]
25
26
  classifiers = [
@@ -2,11 +2,11 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from . import constants, dynamics, exceptions, kinematics, units, validation
5
+ from . import constants, dynamics, energy, exceptions, kinematics, units, validation
6
6
  from .exceptions import PhysicalDomainError, PhysuError
7
7
  from .units import Quantity, ureg
8
8
 
9
- __version__ = "0.2.0"
9
+ __version__ = "0.3.0"
10
10
 
11
11
  __all__ = [
12
12
  "PhysicalDomainError",
@@ -15,6 +15,7 @@ __all__ = [
15
15
  "__version__",
16
16
  "constants",
17
17
  "dynamics",
18
+ "energy",
18
19
  "exceptions",
19
20
  "kinematics",
20
21
  "units",
@@ -0,0 +1,67 @@
1
+ """Work, energy, and power formulas and utilities for physu."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from . import conservation, kinetic, potential, power, work
6
+ from .conservation import (
7
+ escape_speed,
8
+ final_height_conservation,
9
+ final_speed_conservation,
10
+ mechanical_efficiency,
11
+ mechanical_energy,
12
+ non_conservative_work,
13
+ )
14
+ from .kinetic import (
15
+ kinetic_energy,
16
+ kinetic_energy_from_momentum,
17
+ momentum_from_kinetic_energy,
18
+ speed_from_kinetic_energy,
19
+ )
20
+ from .potential import (
21
+ elastic_potential_energy,
22
+ gravitational_potential_energy,
23
+ universal_gravitational_potential_energy,
24
+ )
25
+ from .power import (
26
+ average_power,
27
+ force_from_power,
28
+ instantaneous_power,
29
+ velocity_from_power,
30
+ work_from_power,
31
+ )
32
+ from .work import (
33
+ elastic_work,
34
+ gravitational_work,
35
+ mechanical_work,
36
+ net_work,
37
+ )
38
+
39
+ __all__ = [
40
+ "average_power",
41
+ "conservation",
42
+ "elastic_potential_energy",
43
+ "elastic_work",
44
+ "escape_speed",
45
+ "final_height_conservation",
46
+ "final_speed_conservation",
47
+ "force_from_power",
48
+ "gravitational_potential_energy",
49
+ "gravitational_work",
50
+ "instantaneous_power",
51
+ "kinetic",
52
+ "kinetic_energy",
53
+ "kinetic_energy_from_momentum",
54
+ "mechanical_efficiency",
55
+ "mechanical_energy",
56
+ "mechanical_work",
57
+ "momentum_from_kinetic_energy",
58
+ "net_work",
59
+ "non_conservative_work",
60
+ "potential",
61
+ "power",
62
+ "speed_from_kinetic_energy",
63
+ "universal_gravitational_potential_energy",
64
+ "velocity_from_power",
65
+ "work",
66
+ "work_from_power",
67
+ ]