physu 0.3.0__tar.gz → 0.4.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 (54) hide show
  1. {physu-0.3.0 → physu-0.4.0}/PKG-INFO +10 -3
  2. {physu-0.3.0 → physu-0.4.0}/README.md +8 -1
  3. physu-0.4.0/changelogs/0.4.md +17 -0
  4. physu-0.4.0/examples/thermodynamics.py +87 -0
  5. {physu-0.3.0 → physu-0.4.0}/pyproject.toml +2 -1
  6. {physu-0.3.0 → physu-0.4.0}/src/physu/__init__.py +3 -2
  7. {physu-0.3.0 → physu-0.4.0}/src/physu/constants.py +7 -1
  8. physu-0.4.0/src/physu/thermodynamics/__init__.py +73 -0
  9. physu-0.4.0/src/physu/thermodynamics/calorimetry.py +167 -0
  10. physu-0.4.0/src/physu/thermodynamics/heat_transfer.py +105 -0
  11. physu-0.4.0/src/physu/thermodynamics/ideal_gas.py +252 -0
  12. physu-0.4.0/src/physu/thermodynamics/laws.py +154 -0
  13. physu-0.4.0/src/physu/thermodynamics/temperature.py +205 -0
  14. {physu-0.3.0 → physu-0.4.0}/tests/test_constants.py +3 -0
  15. physu-0.4.0/tests/test_thermodynamics.py +325 -0
  16. {physu-0.3.0 → physu-0.4.0}/.gitignore +0 -0
  17. {physu-0.3.0 → physu-0.4.0}/AGENTS.md +0 -0
  18. {physu-0.3.0 → physu-0.4.0}/LICENSE +0 -0
  19. {physu-0.3.0 → physu-0.4.0}/changelogs/0.1.md +0 -0
  20. {physu-0.3.0 → physu-0.4.0}/changelogs/0.2.md +0 -0
  21. {physu-0.3.0 → physu-0.4.0}/changelogs/0.3.md +0 -0
  22. {physu-0.3.0 → physu-0.4.0}/examples/dynamics_elasticity_momentum_gravitation.py +0 -0
  23. {physu-0.3.0 → physu-0.4.0}/examples/dynamics_forces_and_friction.py +0 -0
  24. {physu-0.3.0 → physu-0.4.0}/examples/energy_work_and_power.py +0 -0
  25. {physu-0.3.0 → physu-0.4.0}/examples/kinematics_1d.py +0 -0
  26. {physu-0.3.0 → physu-0.4.0}/examples/kinematics_2d_and_circular.py +0 -0
  27. {physu-0.3.0 → physu-0.4.0}/examples/units_and_validation.py +0 -0
  28. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/__init__.py +0 -0
  29. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/elasticity.py +0 -0
  30. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/friction.py +0 -0
  31. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/gravitation.py +0 -0
  32. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/momentum.py +0 -0
  33. {physu-0.3.0 → physu-0.4.0}/src/physu/dynamics/newton.py +0 -0
  34. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/__init__.py +0 -0
  35. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/conservation.py +0 -0
  36. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/kinetic.py +0 -0
  37. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/potential.py +0 -0
  38. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/power.py +0 -0
  39. {physu-0.3.0 → physu-0.4.0}/src/physu/energy/work.py +0 -0
  40. {physu-0.3.0 → physu-0.4.0}/src/physu/exceptions.py +0 -0
  41. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/__init__.py +0 -0
  42. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/accelerated.py +0 -0
  43. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/circular.py +0 -0
  44. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/projectile.py +0 -0
  45. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/uniform.py +0 -0
  46. {physu-0.3.0 → physu-0.4.0}/src/physu/kinematics/vertical.py +0 -0
  47. {physu-0.3.0 → physu-0.4.0}/src/physu/py.typed +0 -0
  48. {physu-0.3.0 → physu-0.4.0}/src/physu/units.py +0 -0
  49. {physu-0.3.0 → physu-0.4.0}/src/physu/validation.py +0 -0
  50. {physu-0.3.0 → physu-0.4.0}/tests/test_dynamics.py +0 -0
  51. {physu-0.3.0 → physu-0.4.0}/tests/test_energy.py +0 -0
  52. {physu-0.3.0 → physu-0.4.0}/tests/test_kinematics.py +0 -0
  53. {physu-0.3.0 → physu-0.4.0}/tests/test_units.py +0 -0
  54. {physu-0.3.0 → physu-0.4.0}/tests/test_validation.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: physu
3
- Version: 0.3.0
3
+ Version: 0.4.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,energy,kinematics,physics,pint,scientific-computing,units
11
+ Keywords: dimensional-analysis,dynamics,energy,kinematics,physics,pint,scientific-computing,thermodynamics,units
12
12
  Classifier: Development Status :: 3 - Alpha
13
13
  Classifier: Intended Audience :: Developers
14
14
  Classifier: Intended Audience :: Education
@@ -65,13 +65,14 @@ Runnable scripts covering every module and submodule live in [examples/](example
65
65
  - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — inclined ramp winch sizing and crate slip threshold
66
66
  - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — vehicle suspension sag, rear-end impact force, and CubeSat LEO orbit
67
67
  - [energy_work_and_power.py](examples/energy_work_and_power.py) — crane hoist motor sizing, spring coaster launch, and LEO escape speed
68
+ - [thermodynamics.py](examples/thermodynamics.py) — rail expansion gap, steel quenching bath, scuba cylinder pressure, Carnot limit, and window heat loss
68
69
 
69
70
  ## Modules
70
71
 
71
72
  - **`physu.units`**: Centralized `ureg`, `Quantity`, `to_quantity`, `check_dimension`, `convert_to`, `to_si`, and `to_unit`.
72
73
  - **`physu.exceptions`**: `PhysuError` and `PhysicalDomainError`.
73
74
  - **`physu.validation`**: `validate_quantity`, `require_non_negative`, `require_positive`, `require_non_zero`, and `require_range`.
74
- - **`physu.constants`**: Fundamental SI / CODATA 2022 constants (`STANDARD_GRAVITY`, `SPEED_OF_LIGHT`, `GRAVITATIONAL_CONSTANT`, `PLANCK_CONSTANT`, `ELEMENTARY_CHARGE`, `BOLTZMANN_CONSTANT`, `AVOGADRO_CONSTANT`, `MOLAR_GAS_CONSTANT`, `STANDARD_ATMOSPHERE`, `ELECTRON_MASS`, `PROTON_MASS`, `VACUUM_PERMITTIVITY`, `VACUUM_PERMEABILITY`).
75
+ - **`physu.constants`**: Fundamental SI / CODATA 2022 constants (`STANDARD_GRAVITY`, `SPEED_OF_LIGHT`, `GRAVITATIONAL_CONSTANT`, `PLANCK_CONSTANT`, `ELEMENTARY_CHARGE`, `BOLTZMANN_CONSTANT`, `AVOGADRO_CONSTANT`, `MOLAR_GAS_CONSTANT`, `STANDARD_ATMOSPHERE`, `STEFAN_BOLTZMANN_CONSTANT`, `ELECTRON_MASS`, `PROTON_MASS`, `VACUUM_PERMITTIVITY`, `VACUUM_PERMEABILITY`).
75
76
  - **`physu.kinematics`**:
76
77
  - `uniform`: MRU (`displacement`, `position`, `average_velocity`, `travel_time`)
77
78
  - `accelerated`: MRUA / SUVAT (`final_velocity`, `displacement`, `position`, `displacement_from_velocities`, `acceleration`, `torricelli_velocity`, `time_to_velocity`, `time_to_displacement`)
@@ -90,6 +91,12 @@ Runnable scripts covering every module and submodule live in [examples/](example
90
91
  - `potential`: Gravitational and elastic potential energy (`gravitational_potential_energy`, `universal_gravitational_potential_energy`, `elastic_potential_energy`)
91
92
  - `conservation`: Mechanical energy conservation and efficiency (`mechanical_energy`, `non_conservative_work`, `final_speed_conservation`, `final_height_conservation`, `escape_speed`, `mechanical_efficiency`)
92
93
  - `power`: Mechanical power (`average_power`, `instantaneous_power`, `work_from_power`, `force_from_power`, `velocity_from_power`)
94
+ - **`physu.thermodynamics`**:
95
+ - `temperature`: Temperature scales and thermal expansion (`to_kelvin`, `to_celsius`, `to_fahrenheit`, `temperature_difference`, `linear_thermal_expansion`, `volumetric_thermal_expansion`)
96
+ - `calorimetry`: Sensible heat, latent heat, and thermal equilibrium (`sensible_heat`, `latent_heat`, `specific_heat_capacity`, `equilibrium_temperature`)
97
+ - `ideal_gas`: Ideal gas law and kinetic theory (`ideal_gas_pressure`, `ideal_gas_volume`, `ideal_gas_moles`, `ideal_gas_temperature`, `combined_gas_law`, `rms_molecular_speed`, `average_molecular_kinetic_energy`)
98
+ - `laws`: First/second laws, process work, and engines (`internal_energy_change`, `isobaric_work`, `isothermal_work`, `thermal_efficiency`, `carnot_efficiency`, `isothermal_entropy_change`)
99
+ - `heat_transfer`: Conduction and thermal radiation (`conduction_heat_rate`, `radiation_power`)
93
100
 
94
101
  ## Development
95
102
 
@@ -33,13 +33,14 @@ Runnable scripts covering every module and submodule live in [examples/](example
33
33
  - [dynamics_forces_and_friction.py](examples/dynamics_forces_and_friction.py) — inclined ramp winch sizing and crate slip threshold
34
34
  - [dynamics_elasticity_momentum_gravitation.py](examples/dynamics_elasticity_momentum_gravitation.py) — vehicle suspension sag, rear-end impact force, and CubeSat LEO orbit
35
35
  - [energy_work_and_power.py](examples/energy_work_and_power.py) — crane hoist motor sizing, spring coaster launch, and LEO escape speed
36
+ - [thermodynamics.py](examples/thermodynamics.py) — rail expansion gap, steel quenching bath, scuba cylinder pressure, Carnot limit, and window heat loss
36
37
 
37
38
  ## Modules
38
39
 
39
40
  - **`physu.units`**: Centralized `ureg`, `Quantity`, `to_quantity`, `check_dimension`, `convert_to`, `to_si`, and `to_unit`.
40
41
  - **`physu.exceptions`**: `PhysuError` and `PhysicalDomainError`.
41
42
  - **`physu.validation`**: `validate_quantity`, `require_non_negative`, `require_positive`, `require_non_zero`, and `require_range`.
42
- - **`physu.constants`**: Fundamental SI / CODATA 2022 constants (`STANDARD_GRAVITY`, `SPEED_OF_LIGHT`, `GRAVITATIONAL_CONSTANT`, `PLANCK_CONSTANT`, `ELEMENTARY_CHARGE`, `BOLTZMANN_CONSTANT`, `AVOGADRO_CONSTANT`, `MOLAR_GAS_CONSTANT`, `STANDARD_ATMOSPHERE`, `ELECTRON_MASS`, `PROTON_MASS`, `VACUUM_PERMITTIVITY`, `VACUUM_PERMEABILITY`).
43
+ - **`physu.constants`**: Fundamental SI / CODATA 2022 constants (`STANDARD_GRAVITY`, `SPEED_OF_LIGHT`, `GRAVITATIONAL_CONSTANT`, `PLANCK_CONSTANT`, `ELEMENTARY_CHARGE`, `BOLTZMANN_CONSTANT`, `AVOGADRO_CONSTANT`, `MOLAR_GAS_CONSTANT`, `STANDARD_ATMOSPHERE`, `STEFAN_BOLTZMANN_CONSTANT`, `ELECTRON_MASS`, `PROTON_MASS`, `VACUUM_PERMITTIVITY`, `VACUUM_PERMEABILITY`).
43
44
  - **`physu.kinematics`**:
44
45
  - `uniform`: MRU (`displacement`, `position`, `average_velocity`, `travel_time`)
45
46
  - `accelerated`: MRUA / SUVAT (`final_velocity`, `displacement`, `position`, `displacement_from_velocities`, `acceleration`, `torricelli_velocity`, `time_to_velocity`, `time_to_displacement`)
@@ -58,6 +59,12 @@ Runnable scripts covering every module and submodule live in [examples/](example
58
59
  - `potential`: Gravitational and elastic potential energy (`gravitational_potential_energy`, `universal_gravitational_potential_energy`, `elastic_potential_energy`)
59
60
  - `conservation`: Mechanical energy conservation and efficiency (`mechanical_energy`, `non_conservative_work`, `final_speed_conservation`, `final_height_conservation`, `escape_speed`, `mechanical_efficiency`)
60
61
  - `power`: Mechanical power (`average_power`, `instantaneous_power`, `work_from_power`, `force_from_power`, `velocity_from_power`)
62
+ - **`physu.thermodynamics`**:
63
+ - `temperature`: Temperature scales and thermal expansion (`to_kelvin`, `to_celsius`, `to_fahrenheit`, `temperature_difference`, `linear_thermal_expansion`, `volumetric_thermal_expansion`)
64
+ - `calorimetry`: Sensible heat, latent heat, and thermal equilibrium (`sensible_heat`, `latent_heat`, `specific_heat_capacity`, `equilibrium_temperature`)
65
+ - `ideal_gas`: Ideal gas law and kinetic theory (`ideal_gas_pressure`, `ideal_gas_volume`, `ideal_gas_moles`, `ideal_gas_temperature`, `combined_gas_law`, `rms_molecular_speed`, `average_molecular_kinetic_energy`)
66
+ - `laws`: First/second laws, process work, and engines (`internal_energy_change`, `isobaric_work`, `isothermal_work`, `thermal_efficiency`, `carnot_efficiency`, `isothermal_entropy_change`)
67
+ - `heat_transfer`: Conduction and thermal radiation (`conduction_heat_rate`, `radiation_power`)
61
68
 
62
69
  ## Development
63
70
 
@@ -0,0 +1,17 @@
1
+ # `physu` 0.4.0 (2026-11-17)
2
+
3
+ Adds thermodynamics (`physu.thermodynamics`) with safe handling of Pint offset temperature units, plus `STEFAN_BOLTZMANN_CONSTANT` and real-world examples.
4
+
5
+ ## Added
6
+
7
+ ### Thermodynamics (`physu.thermodynamics`)
8
+ - **`temperature`**: Absolute-zero-validated temperature conversions (`to_kelvin`, `to_celsius`, `to_fahrenheit`), offset-safe `temperature_difference`, and thermal expansion (`linear_thermal_expansion`, `volumetric_thermal_expansion`).
9
+ - **`calorimetry`**: Sensible heat (`sensible_heat`), phase-change `latent_heat`, `specific_heat_capacity`, and multi-body `equilibrium_temperature`.
10
+ - **`ideal_gas`**: Ideal gas law solvers (`ideal_gas_pressure`, `ideal_gas_volume`, `ideal_gas_moles`, `ideal_gas_temperature`), `combined_gas_law`, `rms_molecular_speed`, and `average_molecular_kinetic_energy`.
11
+ - **`laws`**: First law (`internal_energy_change`), `isobaric_work`, `isothermal_work`, `thermal_efficiency`, `carnot_efficiency`, and `isothermal_entropy_change`.
12
+ - **`heat_transfer`**: Fourier conduction (`conduction_heat_rate`) and Stefan-Boltzmann thermal radiation (`radiation_power`).
13
+
14
+ ### Constants, Examples & Tests
15
+ - Added `STEFAN_BOLTZMANN_CONSTANT` to `physu.constants`.
16
+ - Added real-world thermodynamics script [thermodynamics.py](../examples/thermodynamics.py) and updated `README.md`.
17
+ - Added unit tests in `tests/test_thermodynamics.py` and `tests/test_constants.py` (61 tests total across the suite), verified with `ruff` and strict `mypy`.
@@ -0,0 +1,87 @@
1
+ """Real-world thermodynamics examples: rail gaps, quenching, scuba tank, Carnot, and heat loss."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from physu.thermodynamics import (
6
+ carnot_efficiency,
7
+ combined_gas_law,
8
+ conduction_heat_rate,
9
+ equilibrium_temperature,
10
+ ideal_gas_moles,
11
+ linear_thermal_expansion,
12
+ radiation_power,
13
+ sensible_heat,
14
+ temperature_difference,
15
+ )
16
+
17
+
18
+ def main() -> None:
19
+ """Solve practical thermal engineering and everyday physics problems."""
20
+ # 1. Steel railway track thermal expansion gap between spring install and summer peak
21
+ rail_length = "25 m"
22
+ steel_alpha = "1.2e-5 / K"
23
+ rail_dt = temperature_difference("15 degC", "48 degC")
24
+ expansion_gap = linear_thermal_expansion(rail_length, steel_alpha, rail_dt)
25
+
26
+ print("=== Railway Track Expansion Gap (25 m steel rail) ===")
27
+ print(
28
+ f"Temperature swing: {rail_dt.to('delta_degC'):.1f} | "
29
+ f"Required gap: {expansion_gap.to('mm'):.2f}"
30
+ )
31
+
32
+ # 2. Quenching a 2.5 kg hot steel part (450 degC) in 12 kg of water (22 degC)
33
+ water_c = "4184 J / (kg * K)"
34
+ steel_c = "490 J / (kg * K)"
35
+ t_eq = equilibrium_temperature(
36
+ [
37
+ ("2.5 kg", steel_c, "450 degC"),
38
+ ("12 kg", water_c, "22 degC"),
39
+ ]
40
+ )
41
+ water_gain = sensible_heat("12 kg", water_c, temperature_difference("22 degC", t_eq))
42
+
43
+ print("\n=== Steel Quenching Bath Equilibrium ===")
44
+ print(f"Final bath temperature: {t_eq.to('degC'):.2f}")
45
+ print(f"Heat absorbed by water: {water_gain.to('kJ'):.1f}")
46
+
47
+ # 3. Scuba tank pressure drop entering 8 degC ocean water
48
+ tank_volume = "12 liter"
49
+ fill_pressure = "200 bar"
50
+ fill_temp = "28 degC"
51
+ dive_temp = "8 degC"
52
+
53
+ air_moles = ideal_gas_moles(fill_pressure, tank_volume, fill_temp)
54
+ dive_pressure = combined_gas_law(
55
+ fill_pressure,
56
+ tank_volume,
57
+ fill_temp,
58
+ final_volume=tank_volume,
59
+ final_temperature=dive_temp,
60
+ )
61
+
62
+ print("\n=== Scuba Cylinder Pressure Check ===")
63
+ print(f"Stored air: {air_moles:.1f} | Pressure at {dive_temp}: {dive_pressure.to('bar'):.1f}")
64
+
65
+ # 4. Steam power plant Carnot ceiling & winter window conduction / radiator output
66
+ max_eta = carnot_efficiency("35 degC", "540 degC")
67
+ window_loss = conduction_heat_rate(
68
+ "0.8 W / (m * K)",
69
+ "1.8 m^2",
70
+ temperature_difference("2 degC", "21 degC"),
71
+ "6 mm",
72
+ )
73
+ radiator_net = radiation_power(
74
+ 0.92,
75
+ "1.4 m^2",
76
+ "55 degC",
77
+ ambient_temperature="21 degC",
78
+ )
79
+
80
+ print("\n=== Power Plant Limit & Home Heating ===")
81
+ print(f"Carnot ceiling (540 degC -> 35 degC): {max_eta.to('%'):.1f}")
82
+ print(f"Single-pane window heat loss: {window_loss.to('kW'):.2f}")
83
+ print(f"Net radiative heat output from radiator (55 degC): {radiator_net:.1f}")
84
+
85
+
86
+ if __name__ == "__main__":
87
+ main()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "physu"
7
- version = "0.3.0"
7
+ version = "0.4.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"
@@ -21,6 +21,7 @@ keywords = [
21
21
  "kinematics",
22
22
  "dynamics",
23
23
  "energy",
24
+ "thermodynamics",
24
25
  "scientific-computing",
25
26
  ]
26
27
  classifiers = [
@@ -2,11 +2,11 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from . import constants, dynamics, energy, exceptions, kinematics, units, validation
5
+ from . import constants, dynamics, energy, exceptions, kinematics, thermodynamics, units, validation
6
6
  from .exceptions import PhysicalDomainError, PhysuError
7
7
  from .units import Quantity, ureg
8
8
 
9
- __version__ = "0.3.0"
9
+ __version__ = "0.4.0"
10
10
 
11
11
  __all__ = [
12
12
  "PhysicalDomainError",
@@ -18,6 +18,7 @@ __all__ = [
18
18
  "energy",
19
19
  "exceptions",
20
20
  "kinematics",
21
+ "thermodynamics",
21
22
  "units",
22
23
  "ureg",
23
24
  "validation",
@@ -9,7 +9,7 @@ import math
9
9
 
10
10
  import pint
11
11
 
12
- from .units import Quantity
12
+ from .units import Quantity, to_unit
13
13
 
14
14
  # Mechanics & gravitation
15
15
  STANDARD_GRAVITY: pint.Quantity = Quantity(9.80665, "m / s^2")
@@ -33,6 +33,11 @@ BOLTZMANN_CONSTANT: pint.Quantity = Quantity(1.380649e-23, "J / K")
33
33
  AVOGADRO_CONSTANT: pint.Quantity = Quantity(6.02214076e23, "1 / mol")
34
34
  MOLAR_GAS_CONSTANT: pint.Quantity = AVOGADRO_CONSTANT * BOLTZMANN_CONSTANT
35
35
  STANDARD_ATMOSPHERE: pint.Quantity = Quantity(101_325, "Pa")
36
+ STEFAN_BOLTZMANN_CONSTANT: pint.Quantity = to_unit(
37
+ (2.0 * (math.pi**5) * (BOLTZMANN_CONSTANT**4))
38
+ / (15.0 * (PLANCK_CONSTANT**3) * (SPEED_OF_LIGHT**2)),
39
+ "W / (m^2 * K^4)",
40
+ )
36
41
 
37
42
  # Atomic & particle masses
38
43
  ELECTRON_MASS: pint.Quantity = Quantity(9.1093837139e-31, "kg")
@@ -51,6 +56,7 @@ __all__ = [
51
56
  "SPEED_OF_LIGHT",
52
57
  "STANDARD_ATMOSPHERE",
53
58
  "STANDARD_GRAVITY",
59
+ "STEFAN_BOLTZMANN_CONSTANT",
54
60
  "VACUUM_PERMEABILITY",
55
61
  "VACUUM_PERMITTIVITY",
56
62
  ]
@@ -0,0 +1,73 @@
1
+ """Thermodynamics formulas and utilities for physu."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from . import calorimetry, heat_transfer, ideal_gas, laws, temperature
6
+ from .calorimetry import (
7
+ equilibrium_temperature,
8
+ latent_heat,
9
+ sensible_heat,
10
+ specific_heat_capacity,
11
+ )
12
+ from .heat_transfer import (
13
+ conduction_heat_rate,
14
+ radiation_power,
15
+ )
16
+ from .ideal_gas import (
17
+ average_molecular_kinetic_energy,
18
+ combined_gas_law,
19
+ ideal_gas_moles,
20
+ ideal_gas_pressure,
21
+ ideal_gas_temperature,
22
+ ideal_gas_volume,
23
+ rms_molecular_speed,
24
+ )
25
+ from .laws import (
26
+ carnot_efficiency,
27
+ internal_energy_change,
28
+ isobaric_work,
29
+ isothermal_entropy_change,
30
+ isothermal_work,
31
+ thermal_efficiency,
32
+ )
33
+ from .temperature import (
34
+ linear_thermal_expansion,
35
+ temperature_difference,
36
+ to_celsius,
37
+ to_fahrenheit,
38
+ to_kelvin,
39
+ volumetric_thermal_expansion,
40
+ )
41
+
42
+ __all__ = [
43
+ "average_molecular_kinetic_energy",
44
+ "calorimetry",
45
+ "carnot_efficiency",
46
+ "combined_gas_law",
47
+ "conduction_heat_rate",
48
+ "equilibrium_temperature",
49
+ "heat_transfer",
50
+ "ideal_gas",
51
+ "ideal_gas_moles",
52
+ "ideal_gas_pressure",
53
+ "ideal_gas_temperature",
54
+ "ideal_gas_volume",
55
+ "internal_energy_change",
56
+ "isobaric_work",
57
+ "isothermal_entropy_change",
58
+ "isothermal_work",
59
+ "latent_heat",
60
+ "laws",
61
+ "linear_thermal_expansion",
62
+ "radiation_power",
63
+ "rms_molecular_speed",
64
+ "sensible_heat",
65
+ "specific_heat_capacity",
66
+ "temperature",
67
+ "temperature_difference",
68
+ "thermal_efficiency",
69
+ "to_celsius",
70
+ "to_fahrenheit",
71
+ "to_kelvin",
72
+ "volumetric_thermal_expansion",
73
+ ]
@@ -0,0 +1,167 @@
1
+ """Calorimetry formulas for sensible heat, latent heat, and thermal equilibrium."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from collections.abc import Sequence
7
+
8
+ import pint
9
+
10
+ from ..exceptions import PhysicalDomainError
11
+ from ..units import Quantity, QuantityLike, to_unit
12
+ from ..validation import validate_quantity
13
+ from .temperature import _to_absolute_kelvin, _to_delta_kelvin
14
+
15
+
16
+ def sensible_heat(
17
+ mass: QuantityLike,
18
+ specific_heat: QuantityLike,
19
+ delta_temperature: QuantityLike,
20
+ ) -> pint.Quantity:
21
+ """Compute heat transferred during a temperature change: ``Q = m * c * delta_T``.
22
+
23
+ Args:
24
+ mass: Object mass (dimension ``[mass]``, ``>= 0``).
25
+ specific_heat: Specific heat capacity (compatible with ``J / (kg * K)``, ``>= 0``).
26
+ delta_temperature: Temperature interval (``K``, ``delta_degC``, or ``delta_degF``).
27
+
28
+ Returns:
29
+ Heat transferred as a ``pint.Quantity`` in ``joule``.
30
+ """
31
+ m = validate_quantity(mass, "[mass]", name="mass", allow_negative=False)
32
+ c = validate_quantity(
33
+ specific_heat,
34
+ "J / (kg * K)",
35
+ name="specific_heat",
36
+ allow_negative=False,
37
+ )
38
+ dt = _to_delta_kelvin(delta_temperature, name="delta_temperature")
39
+ result = to_unit(m * c * dt, "J")
40
+ return Quantity(0.0, "J") if result.magnitude == 0 else result
41
+
42
+
43
+ def latent_heat(
44
+ mass: QuantityLike,
45
+ specific_latent_heat: QuantityLike,
46
+ ) -> pint.Quantity:
47
+ """Compute thermal energy for a phase transition: ``Q = m * L``.
48
+
49
+ Args:
50
+ mass: Substance mass undergoing phase change (dimension ``[mass]``, ``>= 0``).
51
+ specific_latent_heat: Specific latent heat (compatible with ``J / kg``, ``>= 0``).
52
+
53
+ Returns:
54
+ Latent heat magnitude as a ``pint.Quantity`` in ``joule``.
55
+ """
56
+ m = validate_quantity(mass, "[mass]", name="mass", allow_negative=False)
57
+ l_val = validate_quantity(
58
+ specific_latent_heat,
59
+ "J / kg",
60
+ name="specific_latent_heat",
61
+ allow_negative=False,
62
+ )
63
+ return to_unit(m * l_val, "J")
64
+
65
+
66
+ def specific_heat_capacity(
67
+ heat: QuantityLike,
68
+ mass: QuantityLike,
69
+ delta_temperature: QuantityLike,
70
+ ) -> pint.Quantity:
71
+ """Compute specific heat capacity: ``c = Q / (m * delta_T)``.
72
+
73
+ Args:
74
+ heat: Heat energy transferred (dimension ``[energy]``).
75
+ mass: Sample mass (dimension ``[mass]``, ``> 0``).
76
+ delta_temperature: Non-zero temperature interval (``K``, ``delta_degC``, or
77
+ ``delta_degF``).
78
+
79
+ Returns:
80
+ Specific heat capacity as a ``pint.Quantity`` in ``joule / (kilogram * kelvin)``.
81
+
82
+ Raises:
83
+ PhysicalDomainError: If ``heat`` and ``delta_temperature`` have opposite signs.
84
+ """
85
+ q = validate_quantity(heat, "[energy]", name="heat")
86
+ m = validate_quantity(mass, "[mass]", name="mass", allow_negative=False, allow_zero=False)
87
+ dt = _to_delta_kelvin(delta_temperature, name="delta_temperature", allow_zero=False)
88
+ computed = to_unit(q / (m * dt), "J / (kg * K)")
89
+ if float(computed.magnitude) < 0.0:
90
+ raise PhysicalDomainError(
91
+ "Heat and temperature change have opposite signs, yielding a non-physical "
92
+ f"negative specific heat capacity ({computed})."
93
+ )
94
+ return computed
95
+
96
+
97
+ def equilibrium_temperature(
98
+ bodies: Sequence[tuple[QuantityLike, QuantityLike, QuantityLike]],
99
+ ) -> pint.Quantity:
100
+ """Compute final thermal equilibrium temperature of mixed bodies without phase change.
101
+
102
+ Solves ``T_eq = sum(m_i * c_i * T_i) / sum(m_i * c_i)``.
103
+
104
+ Args:
105
+ bodies: Non-empty sequence of ``(mass, specific_heat, initial_temperature)``
106
+ tuples, where each ``mass >= 0``, ``specific_heat >= 0``, and
107
+ ``initial_temperature >= 0 K``.
108
+
109
+ Returns:
110
+ Equilibrium temperature as a ``pint.Quantity`` in ``kelvin`` (convertible
111
+ to ``degC`` or ``degF``).
112
+ """
113
+ if len(bodies) == 0:
114
+ raise PhysicalDomainError("At least one body must be provided.")
115
+
116
+ weighted_temps: list[float] = []
117
+ heat_capacities: list[float] = []
118
+ for idx, entry in enumerate(bodies):
119
+ if len(entry) != 3:
120
+ raise ValueError(
121
+ f"Expected a 3-tuple (mass, specific_heat, temperature) at bodies[{idx}]."
122
+ )
123
+ mass_val, c_val, temp_val = entry
124
+ m = float(
125
+ validate_quantity(
126
+ mass_val,
127
+ "[mass]",
128
+ name=f"bodies[{idx}].mass",
129
+ allow_negative=False,
130
+ )
131
+ .to("kg")
132
+ .magnitude
133
+ )
134
+ c = float(
135
+ validate_quantity(
136
+ c_val,
137
+ "J / (kg * K)",
138
+ name=f"bodies[{idx}].specific_heat",
139
+ allow_negative=False,
140
+ )
141
+ .to("J / (kg * K)")
142
+ .magnitude
143
+ )
144
+ t = float(
145
+ _to_absolute_kelvin(
146
+ temp_val,
147
+ name=f"bodies[{idx}].temperature",
148
+ ).magnitude
149
+ )
150
+ cap = m * c
151
+ heat_capacities.append(cap)
152
+ weighted_temps.append(cap * t)
153
+
154
+ total_capacity = math.fsum(heat_capacities)
155
+ if total_capacity <= 0.0:
156
+ raise PhysicalDomainError(
157
+ "Total heat capacity across bodies must be strictly positive."
158
+ )
159
+ return Quantity(math.fsum(weighted_temps) / total_capacity, "K")
160
+
161
+
162
+ __all__ = [
163
+ "equilibrium_temperature",
164
+ "latent_heat",
165
+ "sensible_heat",
166
+ "specific_heat_capacity",
167
+ ]
@@ -0,0 +1,105 @@
1
+ """Conduction and thermal radiation heat-transfer formulas."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pint
6
+
7
+ from ..constants import STEFAN_BOLTZMANN_CONSTANT
8
+ from ..units import Quantity, QuantityLike, to_unit
9
+ from ..validation import require_range, validate_quantity
10
+ from .temperature import _to_absolute_kelvin, _to_delta_kelvin
11
+
12
+
13
+ def conduction_heat_rate(
14
+ thermal_conductivity: QuantityLike,
15
+ area: QuantityLike,
16
+ delta_temperature: QuantityLike,
17
+ thickness: QuantityLike,
18
+ ) -> pint.Quantity:
19
+ """Compute steady-state conductive heat transfer rate: ``Q_dot = k * A * delta_T / L``.
20
+
21
+ Args:
22
+ thermal_conductivity: Material thermal conductivity (compatible with
23
+ ``W / (m * K)``, ``>= 0``).
24
+ area: Cross-sectional area perpendicular to heat flow (``[area]``, ``>= 0``).
25
+ delta_temperature: Temperature difference across material (``K``,
26
+ ``delta_degC``, or ``delta_degF``).
27
+ thickness: Conduction path thickness (dimension ``[length]``, ``> 0``).
28
+
29
+ Returns:
30
+ Heat transfer rate as a ``pint.Quantity`` in ``watt``.
31
+ """
32
+ k = validate_quantity(
33
+ thermal_conductivity,
34
+ "W / (m * K)",
35
+ name="thermal_conductivity",
36
+ allow_negative=False,
37
+ )
38
+ a = validate_quantity(area, "[area]", name="area", allow_negative=False)
39
+ dt = _to_delta_kelvin(delta_temperature, name="delta_temperature")
40
+ length = validate_quantity(
41
+ thickness,
42
+ "[length]",
43
+ name="thickness",
44
+ allow_negative=False,
45
+ allow_zero=False,
46
+ )
47
+ result = to_unit(k * a * dt / length, "W")
48
+ return Quantity(0.0, "W") if result.magnitude == 0 else result
49
+
50
+
51
+ def radiation_power(
52
+ emissivity: QuantityLike,
53
+ area: QuantityLike,
54
+ temperature: QuantityLike,
55
+ *,
56
+ ambient_temperature: QuantityLike | None = None,
57
+ stefan_boltzmann_constant: QuantityLike = STEFAN_BOLTZMANN_CONSTANT,
58
+ ) -> pint.Quantity:
59
+ """Compute radiated thermal power via Stefan-Boltzmann law.
60
+
61
+ Computes ``P = emissivity * sigma * A * T^4`` when ``ambient_temperature`` is
62
+ omitted, or net radiative heat transfer ``P_net = emissivity * sigma * A * (T^4 - T_amb^4)``
63
+ when ``ambient_temperature`` is provided.
64
+
65
+ Args:
66
+ emissivity: Surface emissivity in ``[0, 1]`` (dimensionless).
67
+ area: Radiating surface area (dimension ``[area]``, ``>= 0``).
68
+ temperature: Radiating surface absolute temperature (``>= 0 K``).
69
+ ambient_temperature: Optional surrounding absolute temperature (``>= 0 K``).
70
+ stefan_boltzmann_constant: Stefan-Boltzmann constant (compatible with
71
+ ``W / (m^2 * K^4)``, ``> 0``, defaults to ``STEFAN_BOLTZMANN_CONSTANT``).
72
+
73
+ Returns:
74
+ Radiated power as a ``pint.Quantity`` in ``watt``.
75
+ """
76
+ eps = validate_quantity(emissivity, "dimensionless", name="emissivity")
77
+ require_range(
78
+ eps,
79
+ min_value=Quantity(0.0, "dimensionless"),
80
+ max_value=Quantity(1.0, "dimensionless"),
81
+ name="emissivity",
82
+ )
83
+ a = validate_quantity(area, "[area]", name="area", allow_negative=False)
84
+ t = _to_absolute_kelvin(temperature, name="temperature")
85
+ sigma = validate_quantity(
86
+ stefan_boltzmann_constant,
87
+ "W / (m^2 * K^4)",
88
+ name="stefan_boltzmann_constant",
89
+ allow_negative=False,
90
+ allow_zero=False,
91
+ )
92
+ if ambient_temperature is None:
93
+ temp_factor = to_unit(t**4, "K^4")
94
+ else:
95
+ t_amb = _to_absolute_kelvin(ambient_temperature, name="ambient_temperature")
96
+ temp_factor = to_unit((t**4) - (t_amb**4), "K^4")
97
+
98
+ result = to_unit(eps * sigma * a * temp_factor, "W")
99
+ return Quantity(0.0, "W") if result.magnitude == 0 else result
100
+
101
+
102
+ __all__ = [
103
+ "conduction_heat_rate",
104
+ "radiation_power",
105
+ ]