physu 0.1.0__tar.gz → 0.2.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 (37) hide show
  1. physu-0.2.0/AGENTS.md +13 -0
  2. {physu-0.1.0 → physu-0.2.0}/PKG-INFO +17 -48
  3. {physu-0.1.0 → physu-0.2.0}/README.md +15 -46
  4. physu-0.2.0/changelogs/0.1.md +22 -0
  5. physu-0.2.0/changelogs/0.2.md +20 -0
  6. physu-0.2.0/examples/dynamics_elasticity_momentum_gravitation.py +59 -0
  7. physu-0.2.0/examples/dynamics_forces_and_friction.py +47 -0
  8. physu-0.2.0/examples/kinematics_1d.py +57 -0
  9. physu-0.2.0/examples/kinematics_2d_and_circular.py +52 -0
  10. physu-0.2.0/examples/units_and_validation.py +53 -0
  11. {physu-0.1.0 → physu-0.2.0}/pyproject.toml +2 -1
  12. {physu-0.1.0 → physu-0.2.0}/src/physu/__init__.py +3 -2
  13. physu-0.2.0/src/physu/dynamics/__init__.py +79 -0
  14. physu-0.2.0/src/physu/dynamics/elasticity.py +174 -0
  15. physu-0.2.0/src/physu/dynamics/friction.py +154 -0
  16. physu-0.2.0/src/physu/dynamics/gravitation.py +159 -0
  17. physu-0.2.0/src/physu/dynamics/momentum.py +186 -0
  18. physu-0.2.0/src/physu/dynamics/newton.py +189 -0
  19. physu-0.2.0/src/physu/py.typed +0 -0
  20. physu-0.2.0/tests/test_dynamics.py +310 -0
  21. physu-0.1.0/AGENTS.md +0 -21
  22. {physu-0.1.0 → physu-0.2.0}/.gitignore +0 -0
  23. {physu-0.1.0 → physu-0.2.0}/LICENSE +0 -0
  24. {physu-0.1.0 → physu-0.2.0}/src/physu/constants.py +0 -0
  25. {physu-0.1.0 → physu-0.2.0}/src/physu/exceptions.py +0 -0
  26. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/__init__.py +0 -0
  27. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/accelerated.py +0 -0
  28. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/circular.py +0 -0
  29. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/projectile.py +0 -0
  30. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/uniform.py +0 -0
  31. {physu-0.1.0 → physu-0.2.0}/src/physu/kinematics/vertical.py +0 -0
  32. {physu-0.1.0 → physu-0.2.0}/src/physu/units.py +0 -0
  33. {physu-0.1.0 → physu-0.2.0}/src/physu/validation.py +0 -0
  34. {physu-0.1.0 → physu-0.2.0}/tests/test_constants.py +0 -0
  35. {physu-0.1.0 → physu-0.2.0}/tests/test_kinematics.py +0 -0
  36. {physu-0.1.0 → physu-0.2.0}/tests/test_units.py +0 -0
  37. {physu-0.1.0 → physu-0.2.0}/tests/test_validation.py +0 -0
physu-0.2.0/AGENTS.md ADDED
@@ -0,0 +1,13 @@
1
+ # AGENTS.md — Working Guidelines for `physu`
2
+
3
+ - **Language:** All code, identifiers, docstrings, comments, tests, changelogs, and docs must be in **English**.
4
+ - **Architecture:** Organize domains as subpackages under `src/physu/<domain>/` with focused submodules re-exported in `__init__.py` (see [README.md](README.md) for current modules and dev commands).
5
+ - **Pint & Validation:**
6
+ - Never create a second `UnitRegistry`. Use `ureg`, `Quantity`, `QuantityLike`, `to_si`, and `to_unit` from `physu.units`.
7
+ - Validate inputs with `validate_quantity` / `require_*` (`physu.validation`) and raise `PhysicalDomainError` (`physu.exceptions`) for non-physical inputs.
8
+ - Reuse constants (`physu.constants`) and existing formulas instead of duplicating equations.
9
+ - Pint gotchas: use `check()` (not `is_compatible_with("[...]")`); validate angles with `"rad"` / `"rad / s"`; use `to_unit` or `to_si` so `mypy --strict` passes cleanly.
10
+ - **Git & Ignored Files:**
11
+ - Work on `main`. Branch/tag `0.1` are frozen for `0.1.x` hotfixes only (use explicit refspecs like `git push origin refs/heads/main`).
12
+ - Never commit git-ignored local files (`ROADMAP.md`, `playground.py`, `.venv/`, `dist/`).
13
+ - **Done Criteria:** Run `pytest`, `ruff`, and `mypy` from `.venv\Scripts\` (separated with `;` in PowerShell) with zero errors, and update `README.md` plus `changelogs/<version>.md` for any new public feature.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: physu
3
- Version: 0.1.0
3
+ Version: 0.2.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,kinematics,physics,pint,scientific-computing,units
11
+ Keywords: dimensional-analysis,dynamics,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
@@ -55,52 +55,15 @@ pip install -e ".[dev]"
55
55
 
56
56
  Requires Python `>= 3.10`.
57
57
 
58
- ## Quickstart
59
-
60
- ```python
61
- import pint
62
- from physu import PhysicalDomainError, ureg
63
- from physu.constants import STANDARD_GRAVITY
64
- from physu.kinematics import (
65
- accelerated_displacement,
66
- centripetal_acceleration,
67
- displacement,
68
- projectile_range,
69
- time_to_height,
70
- )
71
-
72
- # 1D Uniform Motion (MRU)
73
- dx = displacement("72 km/h", "10 s")
74
- print(dx) # 200.0 meter
75
- print(dx.to("km")) # 0.2 kilometer
76
-
77
- # 1D Uniformly Accelerated Motion (MRUA)
78
- dx_acc = accelerated_displacement(10 * (ureg.m / ureg.s), "2 m/s^2", "5 s")
79
- print(dx_acc) # 75.0 meter
80
-
81
- # Vertical Motion (returns both times when reaching 15 m: going up & coming down)
82
- times = time_to_height("20 m/s", "15 m", gravity="10 m/s^2")
83
- print(times) # (Quantity(1.0, "second"), Quantity(3.0, "second"))
84
-
85
- # 2D Projectile Motion
86
- rng = projectile_range("20 m/s", "45 deg", gravity=STANDARD_GRAVITY)
87
- print(round(rng, 2)) # 40.79 meter
88
-
89
- # Uniform Circular Motion (UCM)
90
- ac = centripetal_acceleration("2 m", angular_velocity="60 rpm")
91
- print(round(ac, 2)) # 78.96 meter / second ** 2
92
-
93
- # Catching dimensional & physical errors
94
- try:
95
- displacement("10 kg", "2 s")
96
- except pint.DimensionalityError as exc:
97
- print("Dimension error:", exc)
98
-
99
- try:
100
- time_to_height("20 m/s", "25 m", gravity="10 m/s^2")
101
- except PhysicalDomainError as exc:
102
- print("Domain error:", exc)
103
- ```
58
+ ## Examples
59
+
60
+ Runnable scripts covering every module and submodule live in [examples/](examples/):
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
104
67
 
105
68
  ## Modules
106
69
 
@@ -114,6 +77,12 @@ except PhysicalDomainError as exc:
114
77
  - `vertical`: Free fall and vertical throw (`vertical_position`, `vertical_velocity`, `free_fall_distance`, `free_fall_speed`, `free_fall_time`, `time_to_peak`, `max_height`, `time_to_height`)
115
78
  - `projectile`: 2D projectile motion (`velocity_components`, `projectile_flight_time`, `projectile_max_height`, `projectile_range`, `projectile_position`, `projectile_velocity`)
116
79
  - `circular`: Uniform circular motion (`tangential_speed`, `angular_velocity_from_speed`, `centripetal_acceleration`, `period_from_frequency`, `frequency_from_period`, `angular_velocity_from_period`, `angular_velocity_from_frequency`, `period_from_angular_velocity`, `frequency_from_angular_velocity`, `angular_displacement`, `arc_length`)
80
+ - **`physu.dynamics`**:
81
+ - `newton`: Newton's laws, weight, and inclined planes (`force`, `acceleration`, `mass`, `weight`, `inclined_parallel_force`, `inclined_normal_force`)
82
+ - `friction`: Static and kinetic friction (`max_static_friction`, `kinetic_friction`, `friction_coefficient`, `normal_force`, `critical_incline_angle`)
83
+ - `elasticity`: Hooke's law and springs (`spring_force`, `spring_force_magnitude`, `spring_constant`, `spring_displacement`, `series_spring_constant`, `parallel_spring_constant`)
84
+ - `momentum`: Linear momentum, impulse, and 1D collisions (`linear_momentum`, `impulse`, `momentum_change`, `average_force`, `collision_velocities`, `elastic_collision_velocities`, `inelastic_collision_velocity`)
85
+ - `gravitation`: Universal gravitation and circular dynamics (`gravitational_force`, `gravitational_field_strength`, `orbital_speed`, `centripetal_force`)
117
86
 
118
87
  ## Development
119
88
 
@@ -23,52 +23,15 @@ pip install -e ".[dev]"
23
23
 
24
24
  Requires Python `>= 3.10`.
25
25
 
26
- ## Quickstart
27
-
28
- ```python
29
- import pint
30
- from physu import PhysicalDomainError, ureg
31
- from physu.constants import STANDARD_GRAVITY
32
- from physu.kinematics import (
33
- accelerated_displacement,
34
- centripetal_acceleration,
35
- displacement,
36
- projectile_range,
37
- time_to_height,
38
- )
39
-
40
- # 1D Uniform Motion (MRU)
41
- dx = displacement("72 km/h", "10 s")
42
- print(dx) # 200.0 meter
43
- print(dx.to("km")) # 0.2 kilometer
44
-
45
- # 1D Uniformly Accelerated Motion (MRUA)
46
- dx_acc = accelerated_displacement(10 * (ureg.m / ureg.s), "2 m/s^2", "5 s")
47
- print(dx_acc) # 75.0 meter
48
-
49
- # Vertical Motion (returns both times when reaching 15 m: going up & coming down)
50
- times = time_to_height("20 m/s", "15 m", gravity="10 m/s^2")
51
- print(times) # (Quantity(1.0, "second"), Quantity(3.0, "second"))
52
-
53
- # 2D Projectile Motion
54
- rng = projectile_range("20 m/s", "45 deg", gravity=STANDARD_GRAVITY)
55
- print(round(rng, 2)) # 40.79 meter
56
-
57
- # Uniform Circular Motion (UCM)
58
- ac = centripetal_acceleration("2 m", angular_velocity="60 rpm")
59
- print(round(ac, 2)) # 78.96 meter / second ** 2
60
-
61
- # Catching dimensional & physical errors
62
- try:
63
- displacement("10 kg", "2 s")
64
- except pint.DimensionalityError as exc:
65
- print("Dimension error:", exc)
66
-
67
- try:
68
- time_to_height("20 m/s", "25 m", gravity="10 m/s^2")
69
- except PhysicalDomainError as exc:
70
- print("Domain error:", exc)
71
- ```
26
+ ## Examples
27
+
28
+ Runnable scripts covering every module and submodule live in [examples/](examples/):
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
72
35
 
73
36
  ## Modules
74
37
 
@@ -82,6 +45,12 @@ except PhysicalDomainError as exc:
82
45
  - `vertical`: Free fall and vertical throw (`vertical_position`, `vertical_velocity`, `free_fall_distance`, `free_fall_speed`, `free_fall_time`, `time_to_peak`, `max_height`, `time_to_height`)
83
46
  - `projectile`: 2D projectile motion (`velocity_components`, `projectile_flight_time`, `projectile_max_height`, `projectile_range`, `projectile_position`, `projectile_velocity`)
84
47
  - `circular`: Uniform circular motion (`tangential_speed`, `angular_velocity_from_speed`, `centripetal_acceleration`, `period_from_frequency`, `frequency_from_period`, `angular_velocity_from_period`, `angular_velocity_from_frequency`, `period_from_angular_velocity`, `frequency_from_angular_velocity`, `angular_displacement`, `arc_length`)
48
+ - **`physu.dynamics`**:
49
+ - `newton`: Newton's laws, weight, and inclined planes (`force`, `acceleration`, `mass`, `weight`, `inclined_parallel_force`, `inclined_normal_force`)
50
+ - `friction`: Static and kinetic friction (`max_static_friction`, `kinetic_friction`, `friction_coefficient`, `normal_force`, `critical_incline_angle`)
51
+ - `elasticity`: Hooke's law and springs (`spring_force`, `spring_force_magnitude`, `spring_constant`, `spring_displacement`, `series_spring_constant`, `parallel_spring_constant`)
52
+ - `momentum`: Linear momentum, impulse, and 1D collisions (`linear_momentum`, `impulse`, `momentum_change`, `average_force`, `collision_velocities`, `elastic_collision_velocities`, `inelastic_collision_velocity`)
53
+ - `gravitation`: Universal gravitation and circular dynamics (`gravitational_force`, `gravitational_field_strength`, `orbital_speed`, `centripetal_force`)
85
54
 
86
55
  ## Development
87
56
 
@@ -0,0 +1,22 @@
1
+ # `physu` 0.1.0 (2026-11-16)
2
+
3
+ Initial public release of `physu` on PyPI (`https://pypi.org/project/physu/0.1.0/`).
4
+
5
+ ## Added
6
+
7
+ ### Core Infrastructure
8
+ - **`physu.units`**: Centralized `pint.UnitRegistry` (`ureg`), `Quantity`, `QuantityLike`, and normalization/conversion helpers (`to_quantity`, `check_dimension`, `convert_to`, `to_si`, `to_unit`) supporting `physu.ureg` quantities, external Pint registries, string expressions, and dimensionless scalars.
9
+ - **`physu.exceptions`**: Exception hierarchy with `PhysuError` and `PhysicalDomainError(PhysuError, ValueError)`.
10
+ - **`physu.validation`**: Dimensional and physical domain validators (`validate_quantity`, `require_non_negative`, `require_positive`, `require_non_zero`, `require_range`) checking `NaN`/finiteness, sign, zero constraints, and unit-aware bounds.
11
+ - **`physu.constants`**: Fundamental SI / CODATA 2022 constants bound to `physu.ureg` (`STANDARD_GRAVITY`, `GRAVITATIONAL_CONSTANT`, `SPEED_OF_LIGHT`, `PLANCK_CONSTANT`, `REDUCED_PLANCK_CONSTANT`, `ELEMENTARY_CHARGE`, `VACUUM_PERMITTIVITY`, `VACUUM_PERMEABILITY`, `BOLTZMANN_CONSTANT`, `AVOGADRO_CONSTANT`, `MOLAR_GAS_CONSTANT`, `STANDARD_ATMOSPHERE`, `ELECTRON_MASS`, `PROTON_MASS`).
12
+
13
+ ### Kinematics (`physu.kinematics`)
14
+ - **`uniform` (MRU)**: `displacement`, `position`, `average_velocity`, `travel_time`.
15
+ - **`accelerated` (MRUA / SUVAT)**: `final_velocity`, `displacement`, `position`, `displacement_from_velocities`, `acceleration`, `torricelli_velocity`, `time_to_velocity`, `time_to_displacement`.
16
+ - **`vertical` (Free Fall & Vertical Throw)**: `vertical_position`, `vertical_velocity`, `free_fall_distance`, `free_fall_speed`, `free_fall_time`, `time_to_peak`, `max_height`, `time_to_height`.
17
+ - **`projectile` (2D Projectile Motion)**: `velocity_components`, `projectile_flight_time`, `projectile_max_height`, `projectile_range`, `projectile_position`, `projectile_velocity`.
18
+ - **`circular` (Uniform Circular Motion)**: `tangential_speed`, `angular_velocity_from_speed`, `centripetal_acceleration`, `period_from_frequency`, `frequency_from_period`, `angular_velocity_from_period`, `angular_velocity_from_frequency`, `period_from_angular_velocity`, `frequency_from_angular_velocity`, `angular_displacement`, `arc_length`.
19
+
20
+ ### Packaging, Documentation & Tests
21
+ - Configured `pyproject.toml` (`hatchling` backend, Python `>= 3.10`, `pint>=0.23`), `LICENSE` (MIT), and `README.md`.
22
+ - Added 28 `pytest` unit tests across `tests/test_units.py`, `tests/test_validation.py`, `tests/test_constants.py`, and `tests/test_kinematics.py`, verified with `ruff` and strict `mypy`.
@@ -0,0 +1,20 @@
1
+ # `physu` 0.2.0 (2026-11-16)
2
+
3
+ Adds classical dynamics (`physu.dynamics`), PEP 561 typing support, and runnable usage examples.
4
+
5
+ ## Added
6
+
7
+ ### Dynamics (`physu.dynamics`)
8
+ - **`newton`**: Newton's second law (`force`, `acceleration`, `mass`), gravitational `weight`, and inclined-plane forces (`inclined_parallel_force`, `inclined_normal_force`).
9
+ - **`friction`**: Static and kinetic friction (`max_static_friction`, `kinetic_friction`, `friction_coefficient`, `normal_force`, `critical_incline_angle`).
10
+ - **`elasticity`**: Hooke's law and spring combinations (`spring_force`, `spring_force_magnitude`, `spring_constant`, `spring_displacement`, `series_spring_constant`, `parallel_spring_constant`).
11
+ - **`momentum`**: Linear momentum, impulse, and 1D collisions (`linear_momentum`, `impulse`, `momentum_change`, `average_force`, `collision_velocities`, `elastic_collision_velocities`, `inelastic_collision_velocity`).
12
+ - **`gravitation`**: Universal gravitation and circular dynamics (`gravitational_force`, `gravitational_field_strength`, `orbital_speed`, `centripetal_force`).
13
+
14
+ ### Typing, Examples & Tests
15
+ - Added PEP 561 `src/physu/py.typed` marker and exposed `physu.dynamics` at top level (`src/physu/__init__.py`).
16
+ - Added runnable scripts in `examples/` covering `units`, `constants`, `validation`, `kinematics`, and `dynamics`.
17
+ - Added unit tests in `tests/test_dynamics.py` (40 tests total across the suite), verified with `ruff` and strict `mypy`.
18
+
19
+ ## Changed
20
+ - Replaced the inline Quickstart block in `README.md` with an `Examples` section pointing to `examples/`, and updated module documentation for `physu.dynamics`.
@@ -0,0 +1,59 @@
1
+ """Examples covering elasticity (Hooke's law), linear momentum/collisions, and gravitation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.dynamics import (
6
+ average_force,
7
+ centripetal_force,
8
+ collision_velocities,
9
+ elastic_collision_velocities,
10
+ gravitational_field_strength,
11
+ gravitational_force,
12
+ impulse,
13
+ inelastic_collision_velocity,
14
+ linear_momentum,
15
+ momentum_change,
16
+ orbital_speed,
17
+ parallel_spring_constant,
18
+ series_spring_constant,
19
+ spring_constant,
20
+ spring_displacement,
21
+ spring_force,
22
+ spring_force_magnitude,
23
+ )
24
+
25
+
26
+ def main() -> None:
27
+ """Run elasticity, momentum, and gravitation/circular dynamics examples."""
28
+ # 1. Elasticity & Springs (Hooke's Law)
29
+ f_restoring = spring_force("200 N/m", "15 cm")
30
+ f_mag = spring_force_magnitude("200 N/m", "-15 cm")
31
+ k_calc = spring_constant("-30 N", "15 cm")
32
+ dx = spring_displacement("-30 N", "200 N/m")
33
+ k_ser = series_spring_constant(["100 N/m", "200 N/m"])
34
+ k_par = parallel_spring_constant(["100 N/m", "200 N/m"])
35
+ print(f"[Elasticity] F={f_restoring}, |F|={f_mag}, k={k_calc}, x={dx}")
36
+ print(f"[Elasticity] k_series={k_ser:.2f}, k_parallel={k_par:.2f}")
37
+
38
+ # 2. Linear Momentum, Impulse & 1D Collisions
39
+ p = linear_momentum("2 kg", "72 km/h")
40
+ j = impulse("50 N", "0.4 s")
41
+ dp = momentum_change("2 kg", "-3 m/s", "5 m/s")
42
+ f_avg = average_force(j, "0.4 s")
43
+ v1_el, v2_el = elastic_collision_velocities("1 kg", "4 m/s", "3 kg", "0 m/s")
44
+ v_inel = inelastic_collision_velocity("2 kg", "6 m/s", "4 kg", "-3 m/s")
45
+ v1_p, v2_p = collision_velocities("2 kg", "6 m/s", "2 kg", "0 m/s", restitution=0.5)
46
+ print(f"[Momentum] p={p}, J={j}, dp={dp}, F_avg={f_avg}")
47
+ print(f"[Collisions] elastic=({v1_el}, {v2_el}), inelastic={v_inel}, e=0.5=({v1_p}, {v2_p})")
48
+
49
+ # 3. Universal Gravitation & Circular Dynamics
50
+ g_earth = gravitational_field_strength("5.9722e24 kg", "6371 km")
51
+ f_grav = gravitational_force("5.9722e24 kg", "70 kg", "6371 km")
52
+ v_leo = orbital_speed("5.9722e24 kg", "6771 km")
53
+ f_cent = centripetal_force("1000 kg", "50 m", tangential_speed="72 km/h")
54
+ print(f"[Gravitation] g_earth={g_earth:.2f}, F_grav(70kg)={f_grav:.2f}")
55
+ print(f"[Circular Dynamics] v_LEO={v_leo.to('km/s'):.2f}, F_c={f_cent:.2f}")
56
+
57
+
58
+ if __name__ == "__main__":
59
+ main()
@@ -0,0 +1,47 @@
1
+ """Examples covering Newton's laws, inclined planes, and static/kinetic friction."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.dynamics import (
6
+ acceleration,
7
+ critical_incline_angle,
8
+ force,
9
+ friction_coefficient,
10
+ inclined_normal_force,
11
+ inclined_parallel_force,
12
+ kinetic_friction,
13
+ mass,
14
+ max_static_friction,
15
+ normal_force,
16
+ weight,
17
+ )
18
+
19
+
20
+ def main() -> None:
21
+ """Run Newton's laws and friction examples."""
22
+ # 1. Newton's Laws & Inclined Planes
23
+ f_net = force("2000 g", "3 m/s^2")
24
+ acc = acceleration("15 N", "3 kg")
25
+ m_obj = mass("20 N", "4 m/s^2")
26
+ w = weight("10 kg")
27
+ f_par = inclined_parallel_force("10 kg", "30 deg")
28
+ f_norm = inclined_normal_force("10 kg", "30 deg")
29
+ print(f"[Newton] F={f_net}, a={acc}, m={m_obj}, W={w:.2f}")
30
+ print(f"[Incline 30 deg] F_parallel={f_par:.2f}, N={f_norm:.2f}")
31
+
32
+ # 2. Static & Kinetic Friction
33
+ n_flat = normal_force("10 kg")
34
+ n_incline = normal_force("10 kg", angle="30 deg")
35
+ fs_max = max_static_friction(0.5, n_incline)
36
+ fk = kinetic_friction(0.3, n_incline)
37
+ mu = friction_coefficient("30 N", "150 N")
38
+ theta_c = critical_incline_angle(0.5)
39
+ print(f"[Friction] N_flat={n_flat:.2f}, N_incline={n_incline:.2f}")
40
+ print(
41
+ f"[Friction] fs_max={fs_max:.2f}, fk={fk:.2f}, "
42
+ f"mu={mu:.2f}, critical_angle={theta_c.to('deg'):.2f}"
43
+ )
44
+
45
+
46
+ if __name__ == "__main__":
47
+ main()
@@ -0,0 +1,57 @@
1
+ """Examples covering 1D kinematics: uniform, accelerated (MRUA/SUVAT), and vertical motion."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu import PhysicalDomainError, ureg
6
+ from physu.kinematics import (
7
+ accelerated_displacement,
8
+ acceleration,
9
+ average_velocity,
10
+ displacement,
11
+ final_velocity,
12
+ free_fall_speed,
13
+ free_fall_time,
14
+ max_height,
15
+ position,
16
+ time_to_height,
17
+ time_to_peak,
18
+ torricelli_velocity,
19
+ travel_time,
20
+ )
21
+
22
+
23
+ def main() -> None:
24
+ """Run 1D uniform, accelerated, and vertical motion examples."""
25
+ # 1. Uniform Motion (MRU)
26
+ dx = displacement("72 km/h", "10 s")
27
+ pos = position("10 m", "5 m/s", "4 s")
28
+ v_avg = average_velocity("150 m", "6 s")
29
+ t_trip = travel_time("300 km", "100 km/h")
30
+ print(f"[Uniform] dx={dx}, pos={pos}, v_avg={v_avg}, t_trip={t_trip.to('hour')}")
31
+
32
+ # 2. Uniformly Accelerated Motion (MRUA / SUVAT)
33
+ v_f = final_velocity(10 * (ureg.m / ureg.s), "2 m/s^2", "5 s")
34
+ dx_acc = accelerated_displacement("10 m/s", "2 m/s^2", "5 s")
35
+ acc = acceleration("0 m/s", "25 m/s", "5 s")
36
+ v_torr = torricelli_velocity("0 m/s", "2 m/s^2", "25 m")
37
+ print(f"[Accelerated] v_f={v_f}, dx={dx_acc}, a={acc}, |v_torr|={v_torr}")
38
+
39
+ # 3. Free Fall & Vertical Throw
40
+ t_fall = free_fall_time("45 m", gravity="10 m/s^2")
41
+ v_impact = free_fall_speed("45 m", gravity="10 m/s^2")
42
+ t_peak = time_to_peak("20 m/s", gravity="10 m/s^2")
43
+ h_max = max_height("20 m/s", initial_height="5 m", gravity="10 m/s^2")
44
+ up_down_times = time_to_height("20 m/s", "15 m", gravity="10 m/s^2")
45
+ print(
46
+ f"[Vertical] t_fall={t_fall}, v_impact={v_impact}, "
47
+ f"t_peak={t_peak}, h_max={h_max}, times@15m={up_down_times}"
48
+ )
49
+
50
+ try:
51
+ time_to_height("20 m/s", "30 m", gravity="10 m/s^2")
52
+ except PhysicalDomainError as exc:
53
+ print("[Vertical] Unreachable height caught:", exc)
54
+
55
+
56
+ if __name__ == "__main__":
57
+ main()
@@ -0,0 +1,52 @@
1
+ """Examples covering 2D projectile motion and uniform circular motion (UCM)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.constants import STANDARD_GRAVITY
6
+ from physu.kinematics import (
7
+ angular_displacement,
8
+ angular_velocity_from_frequency,
9
+ arc_length,
10
+ centripetal_acceleration,
11
+ frequency_from_period,
12
+ period_from_angular_velocity,
13
+ projectile_flight_time,
14
+ projectile_max_height,
15
+ projectile_position,
16
+ projectile_range,
17
+ projectile_velocity,
18
+ tangential_speed,
19
+ velocity_components,
20
+ )
21
+
22
+
23
+ def main() -> None:
24
+ """Run projectile motion and uniform circular motion examples."""
25
+ # 1. 2D Projectile Motion
26
+ vx0, vy0 = velocity_components("20 m/s", "45 deg")
27
+ t_flight = projectile_flight_time("20 m/s", "45 deg", gravity=STANDARD_GRAVITY)
28
+ h_max = projectile_max_height("20 m/s", "45 deg", gravity=STANDARD_GRAVITY)
29
+ rng = projectile_range("20 m/s", "45 deg", gravity=STANDARD_GRAVITY)
30
+ pos_1s = projectile_position("20 m/s", "45 deg", "1 s")
31
+ vel_1s = projectile_velocity("20 m/s", "45 deg", "1 s")
32
+ print(f"[Projectile] vx0={vx0:.2f}, vy0={vy0:.2f}")
33
+ print(f"[Projectile] flight_time={t_flight:.2f}, max_height={h_max:.2f}, range={rng:.2f}")
34
+ print(
35
+ f"[Projectile] at t=1s: pos=({pos_1s[0]:.2f}, {pos_1s[1]:.2f}), "
36
+ f"vel=({vel_1s[0]:.2f}, {vel_1s[1]:.2f})"
37
+ )
38
+
39
+ # 2. Uniform Circular Motion (UCM)
40
+ omega = angular_velocity_from_frequency("2 Hz")
41
+ period = period_from_angular_velocity("60 rpm")
42
+ freq = frequency_from_period(period)
43
+ v_tan = tangential_speed("60 rpm", "2 m")
44
+ a_c = centripetal_acceleration("2 m", angular_velocity="60 rpm")
45
+ d_theta = angular_displacement("60 rpm", "0.5 s")
46
+ s_arc = arc_length("2 m", "90 deg")
47
+ print(f"[Circular] omega(2Hz)={omega:.2f}, T(60rpm)={period:.2f}, f={freq:.2f}")
48
+ print(f"[Circular] v_tan={v_tan:.2f}, a_c={a_c:.2f}, d_theta={d_theta:.2f}, arc={s_arc:.2f}")
49
+
50
+
51
+ if __name__ == "__main__":
52
+ main()
@@ -0,0 +1,53 @@
1
+ """Examples covering physu.units, physu.constants, physu.validation, and exceptions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pint
6
+
7
+ from physu import PhysicalDomainError, Quantity, ureg
8
+ from physu.constants import GRAVITATIONAL_CONSTANT, SPEED_OF_LIGHT, STANDARD_GRAVITY
9
+ from physu.units import convert_to, to_quantity, to_si, to_unit
10
+ from physu.validation import require_range, validate_quantity
11
+
12
+
13
+ def main() -> None:
14
+ """Demonstrate unit normalization, constants, and dimensional/domain validation."""
15
+ # Units and conversion helpers
16
+ speed = to_quantity("72 km/h")
17
+ print("Speed:", speed)
18
+ print("Speed in m/s:", to_si(speed))
19
+ print("Speed in mph:", round(convert_to(speed, "mph"), 2))
20
+
21
+ external_reg = pint.UnitRegistry()
22
+ normalized = to_unit(external_reg.Quantity(1500, "g"), "kg")
23
+ print("Normalized from external registry:", normalized)
24
+
25
+ # Built-in physical constants
26
+ print("Standard gravity:", STANDARD_GRAVITY)
27
+ print("Speed of light:", SPEED_OF_LIGHT)
28
+ print("Gravitational constant:", GRAVITATIONAL_CONSTANT)
29
+
30
+ # Validation helpers
31
+ mass = validate_quantity(5 * ureg.kg, "[mass]", name="mass", allow_negative=False)
32
+ incline = require_range(
33
+ Quantity(30, "deg"),
34
+ min_value=Quantity(0, "rad"),
35
+ max_value=Quantity(90, "deg"),
36
+ name="incline",
37
+ )
38
+ print("Validated mass & angle:", mass, incline.to("rad"))
39
+
40
+ # Catching dimensional vs domain errors
41
+ try:
42
+ validate_quantity("10 kg", "[velocity]", name="speed")
43
+ except pint.DimensionalityError as exc:
44
+ print("Dimensional error caught:", exc)
45
+
46
+ try:
47
+ validate_quantity("-5 s", "[time]", name="time", allow_negative=False)
48
+ except PhysicalDomainError as exc:
49
+ print("Physical domain error caught:", exc)
50
+
51
+
52
+ if __name__ == "__main__":
53
+ main()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "physu"
7
- version = "0.1.0"
7
+ version = "0.2.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"
@@ -19,6 +19,7 @@ keywords = [
19
19
  "pint",
20
20
  "dimensional-analysis",
21
21
  "kinematics",
22
+ "dynamics",
22
23
  "scientific-computing",
23
24
  ]
24
25
  classifiers = [
@@ -2,11 +2,11 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from . import constants, exceptions, kinematics, units, validation
5
+ from . import constants, dynamics, exceptions, kinematics, units, validation
6
6
  from .exceptions import PhysicalDomainError, PhysuError
7
7
  from .units import Quantity, ureg
8
8
 
9
- __version__ = "0.1.0"
9
+ __version__ = "0.2.0"
10
10
 
11
11
  __all__ = [
12
12
  "PhysicalDomainError",
@@ -14,6 +14,7 @@ __all__ = [
14
14
  "Quantity",
15
15
  "__version__",
16
16
  "constants",
17
+ "dynamics",
17
18
  "exceptions",
18
19
  "kinematics",
19
20
  "units",
@@ -0,0 +1,79 @@
1
+ """Classical dynamics formulas and utilities for physu."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from . import elasticity, friction, gravitation, momentum, newton
6
+ from .elasticity import (
7
+ parallel_spring_constant,
8
+ series_spring_constant,
9
+ spring_constant,
10
+ spring_displacement,
11
+ spring_force,
12
+ spring_force_magnitude,
13
+ )
14
+ from .friction import (
15
+ critical_incline_angle,
16
+ friction_coefficient,
17
+ kinetic_friction,
18
+ max_static_friction,
19
+ normal_force,
20
+ )
21
+ from .gravitation import (
22
+ centripetal_force,
23
+ gravitational_field_strength,
24
+ gravitational_force,
25
+ orbital_speed,
26
+ )
27
+ from .momentum import (
28
+ average_force,
29
+ collision_velocities,
30
+ elastic_collision_velocities,
31
+ impulse,
32
+ inelastic_collision_velocity,
33
+ linear_momentum,
34
+ momentum_change,
35
+ )
36
+ from .newton import (
37
+ acceleration,
38
+ force,
39
+ inclined_normal_force,
40
+ inclined_parallel_force,
41
+ mass,
42
+ weight,
43
+ )
44
+
45
+ __all__ = [
46
+ "acceleration",
47
+ "average_force",
48
+ "centripetal_force",
49
+ "collision_velocities",
50
+ "critical_incline_angle",
51
+ "elastic_collision_velocities",
52
+ "elasticity",
53
+ "force",
54
+ "friction",
55
+ "friction_coefficient",
56
+ "gravitation",
57
+ "gravitational_field_strength",
58
+ "gravitational_force",
59
+ "impulse",
60
+ "inclined_normal_force",
61
+ "inclined_parallel_force",
62
+ "inelastic_collision_velocity",
63
+ "kinetic_friction",
64
+ "linear_momentum",
65
+ "mass",
66
+ "max_static_friction",
67
+ "momentum",
68
+ "momentum_change",
69
+ "newton",
70
+ "normal_force",
71
+ "orbital_speed",
72
+ "parallel_spring_constant",
73
+ "series_spring_constant",
74
+ "spring_constant",
75
+ "spring_displacement",
76
+ "spring_force",
77
+ "spring_force_magnitude",
78
+ "weight",
79
+ ]