Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: drastic rewrite of constants documentation #11682

Closed
wants to merge 28 commits into from
Closed

DOC: drastic rewrite of constants documentation #11682

Changes from 10 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
80df09b
Pretty drastic rewrite of __init__py
jakobjakobson13 Mar 18, 2020
2647c7d
Cleaning up and corrections
jakobjakobson13 Mar 18, 2020
9b167ea
fix of references and lists
jakobjakobson13 Mar 18, 2020
c693761
further list fixes
jakobjakobson13 Mar 18, 2020
286fc06
fix references
jakobjakobson13 Mar 18, 2020
a1ff9d8
Further rewrites and formatting
jakobjakobson13 Mar 18, 2020
16d1700
minor grammatical fixes
jakobjakobson13 Mar 18, 2020
ebe41a9
reduced number of references
jakobjakobson13 Mar 18, 2020
10c827c
minor rewrites
jakobjakobson13 Mar 18, 2020
39c6063
Move reference to end of sentence
jakobjakobson13 Mar 19, 2020
41fd3d4
symbols in brackets; rewritten dictionary sentence
jakobjakobson13 Mar 19, 2020
96dc5fc
Change name of reference; reintroduce global data
jakobjakobson13 Mar 19, 2020
f7a0158
minor typos, reinclude auxilliary functions
jakobjakobson13 Mar 20, 2020
6385e30
drastic slimming down of constants.py
jakobjakobson13 Mar 20, 2020
dec5237
fix variable lambda to lambda_
jakobjakobson13 Mar 20, 2020
7f06356
simplify test_basic_table_parse
jakobjakobson13 Mar 20, 2020
779c1f9
change speed_of_light to c
jakobjakobson13 Mar 20, 2020
5f554bb
include phi or golden_ratio respectively
jakobjakobson13 Mar 20, 2020
bf269b7
include phi or golden ratio respectively
jakobjakobson13 Mar 20, 2020
d82b0fa
change _math.sqrt to np.sqrt
Mar 21, 2020
e03f21c
fix doctest, pep8 warning and refguide
Mar 21, 2020
1ab3967
further fixes
Mar 21, 2020
88c2cdb
move phi to func, fix tests
Mar 25, 2020
45cc0a3
fix docs by deleting object in codata
Mar 25, 2020
dbde5e0
cleanup codata docstring
Mar 26, 2020
c3a5985
reintroduce dict to doc; simplify tests
Mar 30, 2020
06b8b58
revert file encoding to ASCII
Mar 31, 2020
e5a139a
Revert all changes except doc related ones
Apr 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
348 changes: 68 additions & 280 deletions scipy/constants/__init__.py
View file
Open in desktop
Expand Up @@ -5,316 +5,104 @@

.. currentmodule:: scipy.constants

Physical and mathematical constants and units.


Mathematical constants
======================

================ =================================================================
``pi`` Pi
``golden`` Golden ratio
``golden_ratio`` Golden ratio
================ =================================================================


Physical constants
About the SI units
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is reference documentation, so background material would better go to the bottom of the page, as people are mainly going to be looking for variable/function names etc. (except maybe the first time when reading this).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I'll do it later.

==================
In 2019 seven système international d’unités (SI) base units were (re)defined to
serve as a basis for all physical quantities by the bureau
international des poids et mesures (BIPM) [SIunits]_. They can be summarized as followed
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the [ ] brackets need removing.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, here I wanted to provide the link with background information. Should I delete it anyway or change its label into "Introduction" or something similar?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No the link is fine, it's just the brackets that are now part of the link and look weird, also SIunits isn't the most informative name. How about simply:

(see [1])

even though for a detailed background the given link is recommended:

=========================== =================================================================
``c`` speed of light in vacuum
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, this you removed and didn't put back. Same for the other ones - that explains the CI failure

``speed_of_light`` speed of light in vacuum
``mu_0`` the magnetic constant :math:`\mu_0`
``epsilon_0`` the electric constant (vacuum permittivity), :math:`\epsilon_0`
``h`` the Planck constant :math:`h`
``Planck`` the Planck constant :math:`h`
``hbar`` :math:`\hbar = h/(2\pi)`
``G`` Newtonian constant of gravitation
``gravitational_constant`` Newtonian constant of gravitation
``g`` standard acceleration of gravity
``e`` elementary charge
``elementary_charge`` elementary charge
``R`` molar gas constant
``gas_constant`` molar gas constant
``alpha`` fine-structure constant
``fine_structure`` fine-structure constant
``N_A`` Avogadro constant
``Avogadro`` Avogadro constant
``k`` Boltzmann constant
``Boltzmann`` Boltzmann constant
``sigma`` Stefan-Boltzmann constant :math:`\sigma`
``Stefan_Boltzmann`` Stefan-Boltzmann constant :math:`\sigma`
``Wien`` Wien displacement law constant
``Rydberg`` Rydberg constant
``m_e`` electron mass
``electron_mass`` electron mass
``m_p`` proton mass
``proton_mass`` proton mass
``m_n`` neutron mass
``neutron_mass`` neutron mass
=========================== =================================================================


Constants database
------------------

In addition to the above variables, :mod:`scipy.constants` also contains the
2018 CODATA recommended values [CODATA2018]_ database containing more physical
constants.

.. autosummary::
:toctree: generated/

value -- Value in physical_constants indexed by key
unit -- Unit in physical_constants indexed by key
precision -- Relative precision in physical_constants indexed by key
find -- Return list of physical_constant keys with a given string
ConstantWarning -- Constant sought not in newest CODATA data set

.. data:: physical_constants

Dictionary of physical constants, of the format
``physical_constants[name] = (value, unit, uncertainty)``.

Available constants:

====================================================================== ====
%(constant_names)s
====================================================================== ====


Units
=====

SI prefixes
-----------

============ =================================================================
``yotta`` :math:`10^{24}`
``zetta`` :math:`10^{21}`
``exa`` :math:`10^{18}`
``peta`` :math:`10^{15}`
``tera`` :math:`10^{12}`
``giga`` :math:`10^{9}`
``mega`` :math:`10^{6}`
``kilo`` :math:`10^{3}`
``hecto`` :math:`10^{2}`
``deka`` :math:`10^{1}`
``deci`` :math:`10^{-1}`
``centi`` :math:`10^{-2}`
``milli`` :math:`10^{-3}`
``micro`` :math:`10^{-6}`
``nano`` :math:`10^{-9}`
``pico`` :math:`10^{-12}`
``femto`` :math:`10^{-15}`
``atto`` :math:`10^{-18}`
``zepto`` :math:`10^{-21}`
============ =================================================================

Binary prefixes
---------------
- The second :math:`\mathrm{s}` as the SI unit of time is derived from the
unperturbed ground-state hyperfine transition frequency of the caesium-133
atom :math:`\Delta \nu_{\mathrm{Cs}}`.

============ =================================================================
``kibi`` :math:`2^{10}`
``mebi`` :math:`2^{20}`
``gibi`` :math:`2^{30}`
``tebi`` :math:`2^{40}`
``pebi`` :math:`2^{50}`
``exbi`` :math:`2^{60}`
``zebi`` :math:`2^{70}`
``yobi`` :math:`2^{80}`
============ =================================================================
- The metre :math:`\mathrm{m}` as the SI unit of length is derived from the
speed of light in vaccum :math:`c`.

Mass
----
- The kilogram :math:`\mathrm{kg}` as the SI unit of mass is derived from the
Planck constant :math:`h`.

================= ============================================================
``gram`` :math:`10^{-3}` kg
``metric_ton`` :math:`10^{3}` kg
``grain`` one grain in kg
``lb`` one pound (avoirdupous) in kg
``pound`` one pound (avoirdupous) in kg
``blob`` one inch version of a slug in kg (added in 1.0.0)
``slinch`` one inch version of a slug in kg (added in 1.0.0)
``slug`` one slug in kg (added in 1.0.0)
``oz`` one ounce in kg
``ounce`` one ounce in kg
``stone`` one stone in kg
``grain`` one grain in kg
``long_ton`` one long ton in kg
``short_ton`` one short ton in kg
``troy_ounce`` one Troy ounce in kg
``troy_pound`` one Troy pound in kg
``carat`` one carat in kg
``m_u`` atomic mass constant (in kg)
``u`` atomic mass constant (in kg)
``atomic_mass`` atomic mass constant (in kg)
================= ============================================================
- The ampere :math:`\mathrm{A}` as the SI unit of electric current is derived
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would read better as ampere (A) rather than ampere A. And same for next lines.

from the elementary charge :math:`e`.

Angle
-----
- The kelvin :math:`\mathrm{K}` as the SI unit of thermodynamic temperature is
derived from the Boltzmann constant :math:`k`.

================= ============================================================
``degree`` degree in radians
``arcmin`` arc minute in radians
``arcminute`` arc minute in radians
``arcsec`` arc second in radians
``arcsecond`` arc second in radians
================= ============================================================
- The mole :math:`\mathrm{mol}` as the SI unit of amount of substance is
derived from the Avogadro constant :math:`N_{\mathrm{A}}`.

- The candela :math:`\mathrm{cd}` as the SI unit of luminous intensity in a
given direction is derived from the luminous efficacy of monochromatic
radiation :math:`K_{\mathrm{cd}}`.

Time
----
All physical quantities and "traditional" units such as newton or pascal
can expressed by a combination of these base units. Therefore the BIPM
lists in addition to the seven base units 22 derived units with special
names and serveral non-SI units. Of course all of before mentioned units
can be used with the SI prefixes.

================= ============================================================
``minute`` one minute in seconds
``hour`` one hour in seconds
``day`` one day in seconds
``week`` one week in seconds
``year`` one year (365 days) in seconds
``Julian_year`` one Julian year (365.25 days) in seconds
================= ============================================================
However, one has to keep in mind that different systems of measurements apply
for different problems and therefore the SI units are not necessarily the
best (in terms of convenience) units for every problem. An overview of
different systems of measurement can be found on Wikipedia [Wikipedia]_ .


Length
------
About the notation of physical units
====================================
A physical quantity is written as the product of a number and a unit such as in

===================== ============================================================
``inch`` one inch in meters
``foot`` one foot in meters
``yard`` one yard in meters
``mile`` one mile in meters
``mil`` one mil in meters
``pt`` one point in meters
``point`` one point in meters
``survey_foot`` one survey foot in meters
``survey_mile`` one survey mile in meters
``nautical_mile`` one nautical mile in meters
``fermi`` one Fermi in meters
``angstrom`` one Angstrom in meters
``micron`` one micron in meters
``au`` one astronomical unit in meters
``astronomical_unit`` one astronomical unit in meters
``light_year`` one light year in meters
``parsec`` one parsec in meters
===================== ============================================================
:math:`T = 293 \ \mathrm{K}`

Pressure
--------
where :math:`293` is the number and :math:`\mathrm{K}` is the unit. The
quantity, in the given example :math:`T`, is written in italic (slanted)
letters and the unit, in the given example :math:`\mathrm{K}`, is written
in roman (upright) letters. As quantities are written as a product of a number
and a unit they are treated by the common rules of algebra meaning that
:math:`T = 293 \ \mathrm{K}` equals :math:`T / \mathrm{K} = 293`. The latter
form is also the recommended form for tables or figures where
:math:`T / \mathrm{K}` is put in the table header or on the axis label and the
numerical value(s) is/are put in the table rows or on the axis ticks.

================= ============================================================
``atm`` standard atmosphere in pascals
``atmosphere`` standard atmosphere in pascals
``bar`` one bar in pascals
``torr`` one torr (mmHg) in pascals
``mmHg`` one torr (mmHg) in pascals
``psi`` one psi in pascals
================= ============================================================

Area
----

================= ============================================================
``hectare`` one hectare in square meters
``acre`` one acre in square meters
================= ============================================================


Volume
------

=================== ========================================================
``liter`` one liter in cubic meters
``litre`` one liter in cubic meters
``gallon`` one gallon (US) in cubic meters
``gallon_US`` one gallon (US) in cubic meters
``gallon_imp`` one gallon (UK) in cubic meters
``fluid_ounce`` one fluid ounce (US) in cubic meters
``fluid_ounce_US`` one fluid ounce (US) in cubic meters
``fluid_ounce_imp`` one fluid ounce (UK) in cubic meters
``bbl`` one barrel in cubic meters
``barrel`` one barrel in cubic meters
=================== ========================================================

Speed
-----

================== ==========================================================
``kmh`` kilometers per hour in meters per second
``mph`` miles per hour in meters per second
``mach`` one Mach (approx., at 15 C, 1 atm) in meters per second
``speed_of_sound`` one Mach (approx., at 15 C, 1 atm) in meters per second
``knot`` one knot in meters per second
================== ==========================================================


Temperature
-----------

===================== =======================================================
``zero_Celsius`` zero of Celsius scale in Kelvin
``degree_Fahrenheit`` one Fahrenheit (only differences) in Kelvins
===================== =======================================================
List of all constants
=====================
The properties of the constants in :mod:`scipy.constants` are taken from
[CODATA2018]_ and can be either accessed directly via

.. autosummary::
:toctree: generated/

value -- Value in physical_constants indexed by key
unit -- Unit in physical_constants indexed by key
precision -- Relative precision in physical_constants indexed by key
find -- Return list of physical_constant keys with a given string
ConstantWarning -- Constant sought not in newest CODATA data set

convert_temperature

Energy
------

==================== =======================================================
``eV`` one electron volt in Joules
``electron_volt`` one electron volt in Joules
``calorie`` one calorie (thermochemical) in Joules
``calorie_th`` one calorie (thermochemical) in Joules
``calorie_IT`` one calorie (International Steam Table calorie, 1956) in Joules
``erg`` one erg in Joules
``Btu`` one British thermal unit (International Steam Table) in Joules
``Btu_IT`` one British thermal unit (International Steam Table) in Joules
``Btu_th`` one British thermal unit (thermochemical) in Joules
``ton_TNT`` one ton of TNT in Joules
==================== =======================================================

Power
-----

==================== =======================================================
``hp`` one horsepower in watts
``horsepower`` one horsepower in watts
==================== =======================================================

Force
-----
or via the dictionaries stored in :mod:`scipy.constants.physical_constants`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the cause of the doc build warnings, there is no module physical_constants. Shouldn't this just be scipy.constants?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah no, you are wanting to refer to physical_constants, which is simply a dictionary not a module (so both the :mod: is wrong and the sentence may need a tweak:

In [3]: type(constants.physical_constants)                                                     
Out[3]: dict

with the following format:

==================== =======================================================
``dyn`` one dyne in newtons
``dyne`` one dyne in newtons
``lbf`` one pound force in newtons
``pound_force`` one pound force in newtons
``kgf`` one kilogram force in newtons
``kilogram_force`` one kilogram force in newtons
==================== =======================================================
``physical_constants[name] = (value, unit, uncertainty)``.

Optics
------
A complete list of available constants is given in the following:

.. autosummary::
:toctree: generated/
====================================================================== ====
%(constant_names)s
====================================================================== ====

lambda2nu
nu2lambda

References
==========
.. [SIunits] Introduction to SI units,
https://www.bipm.org/en/measurement-units/
.. [Wikipedia] Wikipedia, Systems of measurements,
https://en.wikipedia.org/wiki/System_of_measurement
.. [CODATA2018] Fundamental Physical Constants --- Complete Listing, 2018
CODATA adjustment 2018,
https://physics.nist.gov/cuu/Constants/Table/allascii.txt
"""

.. [CODATA2018] CODATA Recommended Values of the Fundamental
Physical Constants 2018.

https://physics.nist.gov/cuu/Constants/

"""
# Modules contributed by BasSw (wegwerp@gmail.com)
from .codata import *
from .constants import *
Expand Down