Repository: scipy/scipy
Pull request: DOC: Add units to scipy.constants description
Closes #17571 

As noted in issue #17571, while most constants have units indicated, the "Physical constants" at the top of the documentation do not. I copied the unit symbols from _codata.py. This should close the issue.

[skip actions] [skip cirrus]

Problem statement:
ENH: Add units to scipy.constants description
### Is your feature request related to a problem? Please describe.

I could not find out, in which units the constants of `scipy.constants` are.
I guess they are in SI notation, but I'd like to be sure, before I use these numbers.

### Describe the solution you'd like.

Could you add either a general note, that all the constants are given in base units of the SI system, or add to every constant the relavant units (e.g. speed of light in vacuum in meters/second).

### Describe alternatives you've considered.

_No response_

### Additional context (e.g. screenshots, GIFs)

_No response_

Hints from issue discussion:
Hi @bmoneke, thank you for reporting. Units are in the doc here https://docs.scipy.org/doc/scipy/reference/constants.html

Is there something missing? (scroll down). Otherwise yes, everything is in SI and yes maybe we can add a note at the beginning to make it clear. Would you like to do it?
Below are the constants with units, but the "base constants" are not labelled.

I can do it.

I'll add a general note at the beginning.

What do you think about writing to every constant (in that list) the unit as well? Just as a reminder for the readers.
Spelling out all constants, as done for the rest, is a good idea 👍 

(If you are looking into making changes to this doc. There is a stalled PR that wanted to change the organisation etc https://github.com/scipy/scipy/pull/11682. If you are interested, it would be great to pick up 😃) 

Thanks!
@bmoneke maybe hold on a bit here. As you can see in #11682 some work might start again. In any case, thank you for raising this as it helped move things!
I saw that other point, when I searched for open/closed issues before opening my own one.

Thanks for your fast responses.
@bmoneke : Could you answer me two questions for clarification?

> Below are the constants with units, but the "base constants" are not labelled.
> 
The base constants are included in the CODATA constants provided by scipy but the base constants are not emphasized explicitly. So you are right, they can be easily overlooked.
Do you want to list the base constants in an dedicated section or do you want to just emphasize them? In the first case they would be listed twice (which I would neither consider ideal) whereas the second case will not be easy to implement.
@jakobjakobson13 , thanks for the question.

I just want to know the units next to the name. They don't have to be emphasized.

Here my problem: I imported the package and found `c = 3e8` (approximately). Then I try to figure out, what the unit of that `c` is and I don't find anything in the documentation.
The documentation regarding CODATA did not help either, as the same constant is included several times (e.g. Boltzmann constant), albeit in different units. Which of these is now the directly imported value?

I cannot use a constant without knowing, that the units fit.

Maybe a (bold) remark, that these base constants are the numbers in the SI system might be enough and a small change. However, being explicit about the units is better, I think.

I hope I succeeded in showing my problem.
Congratulations, you picked a nice corner case here :)
By loading the `scipy.constants` module some constants are currently imported automatically.
https://github.com/scipy/scipy/blob/5da8a3adc664ca57235b9f60f57d705561117893/scipy/constants/__init__.py#L325
Among these constants is `c` or the `speed of light in vacuum`.
https://github.com/scipy/scipy/blob/5da8a3adc664ca57235b9f60f57d705561117893/scipy/constants/_constants.py#L109
The problem now is however that `_cd` only imports the value but not the unit.
https://github.com/scipy/scipy/blob/5da8a3adc664ca57235b9f60f57d705561117893/scipy/constants/_constants.py#L15
https://github.com/scipy/scipy/blob/5da8a3adc664ca57235b9f60f57d705561117893/scipy/constants/_codata.py#L1575

If you had imported the constant via ` scipy.constants.physical_constants` you would have had the constant with its value AND its unit. I hope that helps to your understanding.
Thanks for your explanation. Maybe you can use my experience during your adjustments, in order to make it more understandable, how to use it.

Commit message: DOC: Indicate alpha = fine_structure is unitless

[skip actions] [skip cirrus]

Patch to review:
diff --git a/scipy/constants/__init__.py b/scipy/constants/__init__.py
index ed1f39350d23..be68e2ae90b2 100644
--- a/scipy/constants/__init__.py
+++ b/scipy/constants/__init__.py
@@ -22,36 +22,36 @@
 ==================
 
 ===========================  =================================================================
-``c``                        speed of light in vacuum
-``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
+``c``                        speed of light in vacuum in m s^-1
+``speed_of_light``           speed of light in vacuum in m s^-1
+``mu_0``                     the magnetic constant :math:`\mu_0` in N A^-2
+``epsilon_0``                the electric constant (vacuum permittivity), :math:`\epsilon_0` in F m^-1
+``h``                        the Planck constant :math:`h` in J Hz^-1
+``Planck``                   the Planck constant :math:`h` in J Hz^-1
+``hbar``                     the reduced Planck constant, :math:`\hbar = h/(2\pi)`, in J s
+``G``                        Newtonian constant of gravitation in m^3 kg^-1 s^-2
+``gravitational_constant``   Newtonian constant of gravitation in m^3 kg^-1 s^-2
+``g``                        standard acceleration of gravity in m s^-2
+``e``                        elementary charge in C
+``elementary_charge``        elementary charge in C
+``R``                        molar gas constant in J mol^-1 K^-1
+``gas_constant``             molar gas constant in J mol^-1 K^-1
+``alpha``                    fine-structure constant (unitless)
+``fine_structure``           fine-structure constant (unitless)
+``N_A``                      Avogadro constant in mol^-1
+``Avogadro``                 Avogadro constant in mol^-1
+``k``                        Boltzmann constant in J K^-1
+``Boltzmann``                Boltzmann constant in J K^-1
+``sigma``                    Stefan-Boltzmann constant :math:`\sigma` in W m^-2 K^-4
+``Stefan_Boltzmann``         Stefan-Boltzmann constant :math:`\sigma` in W m^-2 K^-4
+``Wien``                     Wien wavelength displacement law constant in m K
+``Rydberg``                  Rydberg constant in m^-1
+``m_e``                      electron mass in kg
+``electron_mass``            electron mass in kg
+``m_p``                      proton mass in kg
+``proton_mass``              proton mass in kg
+``m_n``                      neutron mass in kg
+``neutron_mass``             neutron mass in kg
 ===========================  =================================================================
 
 


Code review comments:
diff_hunk: @@ -22,36 +22,36 @@
 ==================
 
 ===========================  =================================================================
-``c``                        speed of light in vacuum
-``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
+``c``                        speed of light in vacuum in m s^-1
path: scipy/constants/__init__.py
text: @user1:
A nitpick: I think using the phrase “in” throughout this file to designate the units could be confusing, as it could easily be misread as “inch” to people taking a quick look at this. “Inch meter per second” doesn’t really make sense as a combination of units, but honestly I’ve seen worse in my career and this isn’t unimaginable. Using some punctuation mark to separate would make this unambiguous. For example:

```
speed of light in vacuum: m s^-1
speed of light in vacuum, m s^-1
speed of light in vacuum (m s^-1)
speed of light in vacuum [m s^-1]
```

@user2:
The IUPAC Green Book, 3rd edition (Quantities, Units, and Symbols in Physical Chemistry) states:

> The value of a physical quantity Q can be expressed as the product of a numerical value {Q} and a unit [Q]
> Q = {Q} [Q]
> Neither the name of the physical quantity, nor the symbol used to denote it, implies a particular choice of unit (see footnote 1, p. 4).
>
> Footnote 1: The symbol [Q] was formerly used for dimension of Q, but this symbol is used and preferred for unit of Q.

Therefore I would object to the following option:
> ```
> speed of light in vacuum [m s^-1]
> ```

The first two options seems fine to me.


@author:
I see your point, @user1  and "vacuum, m s^-1" is my preferred style. Thanks to you and @user2 for your comments.

When I started to make that change, I realized there were more than 100 uses of "in" in the file, and then checked the [source cited for the constants](https://physics.nist.gov/cuu/Constants/Table/allascii.txt) for style. That page always uses "in" to say what units something is in. That source only uses SI units so there's no ambiguity with "inch".

Elsewhere in that same Python file, we do use inch and spell it out:

https://github.com/scipy/scipy/blob/913c3ffafd1179dccc723a23fca3f0d661f633dc/scipy/constants/__init__.py#L188

Inches are not used to define any constants, so the reader would need to assume that the constant definitions are mixing inches in with what are clearly SI units.

I think that the NIST people who compiled the first table have considered the style for how to display units more than I have, and we have a precedent for how to work around inches in the same doc (just spell it out). Therefore, I think it's best to leave it as it is.

@user1:
> the reader would need to assume that the constant definitions are mixing inches in with what are clearly SI units.

I'm dealing with a contractor right now who is reporting out moments of inertia in `kg in^2`, which is not even the most cursed combination of units I've had to use in my professional life. I'll also make the point that we shouldn't expect users to need to read across other comments to find the context needed to disambiguate something confusing. Changing all the other uses of "in" to the comma notation as you prefer would make most sense IMO.

But I don't want to bikeshed too hard here, I'm fine with keeping it as-is if you think it's clear enough.

@author:
I feel your pain! I used to teach machine design with most things in US units but some in SI. I know who uses gross units like `kg in^2` and why.

@user3:
Made this a separate column of the table.