Coverage for /usr/lib/python3/dist-packages/scipy/constants/_constants.py: 86%
152 statements
« prev ^ index » next coverage.py v7.9.1, created at 2025-06-14 15:55 +0200
1"""
2Collection of physical constants and conversion factors.
4Most constants are in SI units, so you can do
5print '10 mile per minute is', 10*mile/minute, 'm/s or', 10*mile/(minute*knot), 'knots'
7The list is not meant to be comprehensive, but just convenient for everyday use.
8"""
10from __future__ import annotations
12import math as _math
13from typing import TYPE_CHECKING, Any
15from ._codata import value as _cd
16import numpy as _np
18if TYPE_CHECKING:
19 import numpy.typing as npt
21"""
22BasSw 2006
23physical constants: imported from CODATA
24unit conversion: see e.g., NIST special publication 811
25Use at own risk: double-check values before calculating your Mars orbit-insertion burn.
26Some constants exist in a few variants, which are marked with suffixes.
27The ones without any suffix should be the most common ones.
28"""
30__all__ = [
31 'Avogadro', 'Boltzmann', 'Btu', 'Btu_IT', 'Btu_th', 'G',
32 'Julian_year', 'N_A', 'Planck', 'R', 'Rydberg',
33 'Stefan_Boltzmann', 'Wien', 'acre', 'alpha',
34 'angstrom', 'arcmin', 'arcminute', 'arcsec',
35 'arcsecond', 'astronomical_unit', 'atm',
36 'atmosphere', 'atomic_mass', 'atto', 'au', 'bar',
37 'barrel', 'bbl', 'blob', 'c', 'calorie',
38 'calorie_IT', 'calorie_th', 'carat', 'centi',
39 'convert_temperature', 'day', 'deci', 'degree',
40 'degree_Fahrenheit', 'deka', 'dyn', 'dyne', 'e',
41 'eV', 'electron_mass', 'electron_volt',
42 'elementary_charge', 'epsilon_0', 'erg',
43 'exa', 'exbi', 'femto', 'fermi', 'fine_structure',
44 'fluid_ounce', 'fluid_ounce_US', 'fluid_ounce_imp',
45 'foot', 'g', 'gallon', 'gallon_US', 'gallon_imp',
46 'gas_constant', 'gibi', 'giga', 'golden', 'golden_ratio',
47 'grain', 'gram', 'gravitational_constant', 'h', 'hbar',
48 'hectare', 'hecto', 'horsepower', 'hour', 'hp',
49 'inch', 'k', 'kgf', 'kibi', 'kilo', 'kilogram_force',
50 'kmh', 'knot', 'lambda2nu', 'lb', 'lbf',
51 'light_year', 'liter', 'litre', 'long_ton', 'm_e',
52 'm_n', 'm_p', 'm_u', 'mach', 'mebi', 'mega',
53 'metric_ton', 'micro', 'micron', 'mil', 'mile',
54 'milli', 'minute', 'mmHg', 'mph', 'mu_0', 'nano',
55 'nautical_mile', 'neutron_mass', 'nu2lambda',
56 'ounce', 'oz', 'parsec', 'pebi', 'peta',
57 'pi', 'pico', 'point', 'pound', 'pound_force',
58 'proton_mass', 'psi', 'pt', 'quecto', 'quetta', 'ronna', 'ronto',
59 'short_ton', 'sigma', 'slinch', 'slug', 'speed_of_light',
60 'speed_of_sound', 'stone', 'survey_foot',
61 'survey_mile', 'tebi', 'tera', 'ton_TNT',
62 'torr', 'troy_ounce', 'troy_pound', 'u',
63 'week', 'yard', 'year', 'yobi', 'yocto',
64 'yotta', 'zebi', 'zepto', 'zero_Celsius', 'zetta'
65]
68# mathematical constants
69pi = _math.pi
70golden = golden_ratio = (1 + _math.sqrt(5)) / 2
72# SI prefixes
73quetta = 1e30
74ronna = 1e27
75yotta = 1e24
76zetta = 1e21
77exa = 1e18
78peta = 1e15
79tera = 1e12
80giga = 1e9
81mega = 1e6
82kilo = 1e3
83hecto = 1e2
84deka = 1e1
85deci = 1e-1
86centi = 1e-2
87milli = 1e-3
88micro = 1e-6
89nano = 1e-9
90pico = 1e-12
91femto = 1e-15
92atto = 1e-18
93zepto = 1e-21
94yocto = 1e-24
95ronto = 1e-27
96quecto = 1e-30
98# binary prefixes
99kibi = 2**10
100mebi = 2**20
101gibi = 2**30
102tebi = 2**40
103pebi = 2**50
104exbi = 2**60
105zebi = 2**70
106yobi = 2**80
108# physical constants
109c = speed_of_light = _cd('speed of light in vacuum')
110mu_0 = _cd('vacuum mag. permeability')
111epsilon_0 = _cd('vacuum electric permittivity')
112h = Planck = _cd('Planck constant')
113hbar = h / (2 * pi)
114G = gravitational_constant = _cd('Newtonian constant of gravitation')
115g = _cd('standard acceleration of gravity')
116e = elementary_charge = _cd('elementary charge')
117R = gas_constant = _cd('molar gas constant')
118alpha = fine_structure = _cd('fine-structure constant')
119N_A = Avogadro = _cd('Avogadro constant')
120k = Boltzmann = _cd('Boltzmann constant')
121sigma = Stefan_Boltzmann = _cd('Stefan-Boltzmann constant')
122Wien = _cd('Wien wavelength displacement law constant')
123Rydberg = _cd('Rydberg constant')
125# mass in kg
126gram = 1e-3
127metric_ton = 1e3
128grain = 64.79891e-6
129lb = pound = 7000 * grain # avoirdupois
130blob = slinch = pound * g / 0.0254 # lbf*s**2/in (added in 1.0.0)
131slug = blob / 12 # lbf*s**2/foot (added in 1.0.0)
132oz = ounce = pound / 16
133stone = 14 * pound
134long_ton = 2240 * pound
135short_ton = 2000 * pound
137troy_ounce = 480 * grain # only for metals / gems
138troy_pound = 12 * troy_ounce
139carat = 200e-6
141m_e = electron_mass = _cd('electron mass')
142m_p = proton_mass = _cd('proton mass')
143m_n = neutron_mass = _cd('neutron mass')
144m_u = u = atomic_mass = _cd('atomic mass constant')
146# angle in rad
147degree = pi / 180
148arcmin = arcminute = degree / 60
149arcsec = arcsecond = arcmin / 60
151# time in second
152minute = 60.0
153hour = 60 * minute
154day = 24 * hour
155week = 7 * day
156year = 365 * day
157Julian_year = 365.25 * day
159# length in meter
160inch = 0.0254
161foot = 12 * inch
162yard = 3 * foot
163mile = 1760 * yard
164mil = inch / 1000
165pt = point = inch / 72 # typography
166survey_foot = 1200.0 / 3937
167survey_mile = 5280 * survey_foot
168nautical_mile = 1852.0
169fermi = 1e-15
170angstrom = 1e-10
171micron = 1e-6
172au = astronomical_unit = 149597870700.0
173light_year = Julian_year * c
174parsec = au / arcsec
176# pressure in pascal
177atm = atmosphere = _cd('standard atmosphere')
178bar = 1e5
179torr = mmHg = atm / 760
180psi = pound * g / (inch * inch)
182# area in meter**2
183hectare = 1e4
184acre = 43560 * foot**2
186# volume in meter**3
187litre = liter = 1e-3
188gallon = gallon_US = 231 * inch**3 # US
189# pint = gallon_US / 8
190fluid_ounce = fluid_ounce_US = gallon_US / 128
191bbl = barrel = 42 * gallon_US # for oil
193gallon_imp = 4.54609e-3 # UK
194fluid_ounce_imp = gallon_imp / 160
196# speed in meter per second
197kmh = 1e3 / hour
198mph = mile / hour
199mach = speed_of_sound = 340.5 # approx value at 15 degrees in 1 atm. Is this a common value?
200knot = nautical_mile / hour
202# temperature in kelvin
203zero_Celsius = 273.15
204degree_Fahrenheit = 1/1.8 # only for differences
206# energy in joule
207eV = electron_volt = elementary_charge # * 1 Volt
208calorie = calorie_th = 4.184
209calorie_IT = 4.1868
210erg = 1e-7
211Btu_th = pound * degree_Fahrenheit * calorie_th / gram
212Btu = Btu_IT = pound * degree_Fahrenheit * calorie_IT / gram
213ton_TNT = 1e9 * calorie_th
214# Wh = watt_hour
216# power in watt
217hp = horsepower = 550 * foot * pound * g
219# force in newton
220dyn = dyne = 1e-5
221lbf = pound_force = pound * g
222kgf = kilogram_force = g # * 1 kg
224# functions for conversions that are not linear
227def convert_temperature(
228 val: npt.ArrayLike,
229 old_scale: str,
230 new_scale: str,
231) -> Any:
232 """
233 Convert from a temperature scale to another one among Celsius, Kelvin,
234 Fahrenheit, and Rankine scales.
236 Parameters
237 ----------
238 val : array_like
239 Value(s) of the temperature(s) to be converted expressed in the
240 original scale.
241 old_scale : str
242 Specifies as a string the original scale from which the temperature
243 value(s) will be converted. Supported scales are Celsius ('Celsius',
244 'celsius', 'C' or 'c'), Kelvin ('Kelvin', 'kelvin', 'K', 'k'),
245 Fahrenheit ('Fahrenheit', 'fahrenheit', 'F' or 'f'), and Rankine
246 ('Rankine', 'rankine', 'R', 'r').
247 new_scale : str
248 Specifies as a string the new scale to which the temperature
249 value(s) will be converted. Supported scales are Celsius ('Celsius',
250 'celsius', 'C' or 'c'), Kelvin ('Kelvin', 'kelvin', 'K', 'k'),
251 Fahrenheit ('Fahrenheit', 'fahrenheit', 'F' or 'f'), and Rankine
252 ('Rankine', 'rankine', 'R', 'r').
254 Returns
255 -------
256 res : float or array of floats
257 Value(s) of the converted temperature(s) expressed in the new scale.
259 Notes
260 -----
261 .. versionadded:: 0.18.0
263 Examples
264 --------
265 >>> from scipy.constants import convert_temperature
266 >>> import numpy as np
267 >>> convert_temperature(np.array([-40, 40]), 'Celsius', 'Kelvin')
268 array([ 233.15, 313.15])
270 """
271 # Convert from `old_scale` to Kelvin
272 if old_scale.lower() in ['celsius', 'c']:
273 tempo = _np.asanyarray(val) + zero_Celsius
274 elif old_scale.lower() in ['kelvin', 'k']:
275 tempo = _np.asanyarray(val)
276 elif old_scale.lower() in ['fahrenheit', 'f']:
277 tempo = (_np.asanyarray(val) - 32) * 5 / 9 + zero_Celsius
278 elif old_scale.lower() in ['rankine', 'r']:
279 tempo = _np.asanyarray(val) * 5 / 9
280 else:
281 raise NotImplementedError("%s scale is unsupported: supported scales "
282 "are Celsius, Kelvin, Fahrenheit, and "
283 "Rankine" % old_scale)
284 # and from Kelvin to `new_scale`.
285 if new_scale.lower() in ['celsius', 'c']:
286 res = tempo - zero_Celsius
287 elif new_scale.lower() in ['kelvin', 'k']:
288 res = tempo
289 elif new_scale.lower() in ['fahrenheit', 'f']:
290 res = (tempo - zero_Celsius) * 9 / 5 + 32
291 elif new_scale.lower() in ['rankine', 'r']:
292 res = tempo * 9 / 5
293 else:
294 raise NotImplementedError("'%s' scale is unsupported: supported "
295 "scales are 'Celsius', 'Kelvin', "
296 "'Fahrenheit', and 'Rankine'" % new_scale)
298 return res
301# optics
304def lambda2nu(lambda_: npt.ArrayLike) -> Any:
305 """
306 Convert wavelength to optical frequency
308 Parameters
309 ----------
310 lambda_ : array_like
311 Wavelength(s) to be converted.
313 Returns
314 -------
315 nu : float or array of floats
316 Equivalent optical frequency.
318 Notes
319 -----
320 Computes ``nu = c / lambda`` where c = 299792458.0, i.e., the
321 (vacuum) speed of light in meters/second.
323 Examples
324 --------
325 >>> from scipy.constants import lambda2nu, speed_of_light
326 >>> import numpy as np
327 >>> lambda2nu(np.array((1, speed_of_light)))
328 array([ 2.99792458e+08, 1.00000000e+00])
330 """
331 return c / _np.asanyarray(lambda_)
334def nu2lambda(nu: npt.ArrayLike) -> Any:
335 """
336 Convert optical frequency to wavelength.
338 Parameters
339 ----------
340 nu : array_like
341 Optical frequency to be converted.
343 Returns
344 -------
345 lambda : float or array of floats
346 Equivalent wavelength(s).
348 Notes
349 -----
350 Computes ``lambda = c / nu`` where c = 299792458.0, i.e., the
351 (vacuum) speed of light in meters/second.
353 Examples
354 --------
355 >>> from scipy.constants import nu2lambda, speed_of_light
356 >>> import numpy as np
357 >>> nu2lambda(np.array((1, speed_of_light)))
358 array([ 2.99792458e+08, 1.00000000e+00])
360 """
361 return c / _np.asanyarray(nu)