Create documentation page for astropy.constants - #540

It might be cool to auto-generate a table of the available constants, as is currently done for units. See astropy/units/utils.py:generate_unit_summary.

The docstring for astropy.constants.cgs and astropy.constants.si already have some kind of table, but this could definitely be improved to include the LaTeX notation for the website.

Help on module astropy.constants.si in astropy.constants:

NAME
    astropy.constants.si

FILE
    /Users/tom/Library/Python/2.7/lib/python/site-packages/astropy/constants/si.py

DESCRIPTION
    Astronomical and physics constants in SI units. The constants
    available (with approximate values) are:

    ========== ============== ================ =========================
       Name        Value            Unit       Description
    ========== ============== ================ =========================
        G       6.67384e-11     m3 / (kg s2)   Gravitational constant
      L_sun      3.846e+26           W         Solar luminosity
     M_earth     5.9742e+24          kg        Earth mass
      M_jup      1.8987e+27          kg        Jupiter mass
      M_sun      1.9891e+30          kg        Solar mass
       N_A     6.02214129e+23    1 / (mol)     Avogadro's number
        R        8.3144621      J / (K mol)    Gas constant
     R_earth      6378136            m         Earth equatorial radius
      R_jup       71492000           m         Jupiter equatorial radius
      R_sun      695508000           m         Solar radius
       Ryd       10973731.6       1 / (m)      Rydberg constant
        au     1.49597871e+11        m         Astronomical Unit
        c        299792458        m / (s)      Speed of light in vacuum
        e      1.60217657e-19        C         Electron charge
        h      6.62606957e-34       J s        Planck constant
       hbar    1.05457173e-34       J s        Reduced Planck constant
       k_B     1.3806488e-23      J / (K)      Boltzmann constant
       kpc     3.08567758e+19        m         Kiloparsec
       m_e     9.10938291e-31        kg        Electron mass
       m_n     1.67492735e-27        kg        Neutron mass
       m_p     1.67262178e-27        kg        Proton mass
        pc     3.08567758e+16        m         Parsec
     sigma_sb   5.670373e-08    W / (K4 m2)    Stefan-Boltzmann constant
    ========== ============== ================ =========================

+1 on the autogenerating idea. I can look into that if you'd rather focus on the narrative docs, @astrofrog

@eteq - ok, feel free to do that!

@eteq - I've added an initial narrative. There are already tables appearing (this was actually implemented in the module docstring before, so this is not something I added). However, we might want to make it more similar to astropy.units and have the TeX output. Let me know if you want to do this, or if I should just go ahead and merge as-is.

Actually, I think it's ok - I had a closer look at how these docstrings are generated and it seems fine for now. It would make sense to do this consistently the same way units does (maybe a utility function that can be shared between them?), but for now I think this is fine, as there probably isn't too much call for the TeX docs.

Reading over the docs did make me realize an oddity about the way the package is currently working, though. Right now, it's possible to do

from astropy.constants import si

cincgs = si.c.cgs

So this begs the question: why don't we just do

from astropy import constants
cincgs = constants.c.cgs

?

I think someone mentioned this and I was actually under the impression that that's what we'd settled on doing, but I can see from the docstring here that there's significant potential for confusion. if we have two very different (easy) ways to convert between si and cgs.

The main reason I can think of is that while you can do si.c.cgs, you might as well just do cgs.c. Also, it's useful to provide the constants pre-converted in each system. Furthermore, some cgs and SI units are fundamentally different - try e.cgs for example, and you'll see that it cannot currently convert. If you do provide the constants at the top level, what is the default system? SI? I'm not saying it can't be done, but I wonder whether there is really much confusion if I simply don't mention in the docs that the constants can be converted to the other system with the cgs convenience attribute? The short answer I would give is (a) convenience, and (b) avoid confusion about what the default system is, so that they never do float(G), which is ambiguous, but float(si.G).

@astrofrog - I'm continuing the discussion below but I understand if you want to move it elsewhere because it's more about the package itself than the documentation. If you prefer, I could open up a PR to change it to what I was thinking, and then we can discuss it there.

I guess what I realized after reading these docs is that it's confusing and unexpected to have to do si.c if they are Quantity objects. My natural inclination was to do:

from constants import c

float(c.cgs)

That seems just as convenient and unambiguous, and is more consistent with the fact that all other Quantity objects you'd do somequantity.to(someunit) rather than to(someqnantity, someunit).

That said, I admit I have no solution to the problem of that annoying 4pi for the E&M units.

@eteq - I agree that your suggestion is better (I'm fine with discussing it here). Let's think a bit more about the E&M units to see if we can find a clean solution. Maybe e.cgs and e.si could be overloaded with a custom transformation? Or is that too hacky?

Hmm... what about adding a unit equivalency? You could implement it as a private function in constants (or _constants) and extend Constant to allow it to optionally store equivalencies that are important for that particular value (and automatically use them if they are present)? Maybe even put that functionality in Quantity directly?

True, we could use equivalencies. @mdboom - do you have any thoughts about this?

A couple of options I thought of last night:

• Don't allow e to be used directly as a quantity, and require .si or .cgs to be specified (i.e. overload and disable the operators)
• Explicitly name the two versions of the constants, e_si and e_cgs (since e_si.cgs and e_cgs.si won't work anyway)

@eteq: To answer the question: It seems like using equivalencies would work, but I worry about the implicitness of that approach being too confusing. I think I prefer @astrofrog's overnight suggestions immediately above better...

Whoops, I thought I commented on this days ago, but I'm just realizing now it never appeared.

I'm ok with either of @astrofrog's sugestions, although I think I slightly favor e_cgs/e_si because it will probably be easier to implement and makes it clear that these are special in that it's more than just a simple rescaling.

See the mailing list for some more related discussion. I'm mildly in favor of keeping the status quo, with the justification that in si.c and si.e, the si doesn't refer so much to the units as to the system (important for EM units). I'm in favor of finalizing this PR (which was supposed to be about the docs) and then if we reach a consensus about the constants API, we can always open a PR.

@mdboom @eteq - see #572 for an alternative API for constants. Let me know what you think!

I am planning to merge this (as discussed in #572) unless there are any objections. It describes the current behavior, and we an always update it if we change the API.