DOC: add docstrings to units (#172)

As mentioned in issue #119 , it can help the users a great bit if we add
doc string to the unit api. (Just realized there are so many different
metric systems we have around the world...)

---------

Co-authored-by: Chengyu Liu <cyliu@aus552cyliu.local>

scimath/units/SI.py

@@ -16,6 +16,21 @@
 #
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+""" Defines units of SI
+
+    Symbols defined: meter, kilogram, second, ampere, mole, candela,
+                     radian, steradian, hertz, newton,
+                     pascal, joule, watt, coulomb,
+                     volt, farad, ohm, siemens, weber,
+                     tesla, henry, lumen, lux, becquerel,
+                     gray, sievert, katal [and aliases]
+
+    Prefixes defined: yotta, zetta, exa, peta, tera, giga, mega, kilo,
+                      hecto, deka, deci, centi, milli, micro, nano, pico,
+                      femto, atto, zepto, yocto
+
+"""
+
 from copy import copy
 from scimath.units.unit import unit, dimensionless, none
 

scimath/units/acceleration.py

@@ -9,6 +9,9 @@
 # Thanks for using Enthought open source!
 
 """ Define units of acceleration
+
+    Symbols defined: feet_per_second_squared, meters_per_second_squared [and aliases]
+
 """
 
 #####################################################################

scimath/units/angle.py

@@ -9,6 +9,10 @@
 # Thanks for using Enthought open source!
 
 """ Define units of angle (dimensionless with meaning)
+
+    Symbols defined: circle, degree, grad, quadrant, mil, right_angle, radian, revolution, sextant, sign, turn
+                     minute, second, [and aliases]
+
 """
 
 #############################################################################

scimath/units/area.py

@@ -18,6 +18,13 @@
 
 from .length import meter, centimeter, inch, foot, mile
 
+""" Define units of area
+
+    Symbols defined: acre, hectare,
+                     barn,
+                     square_centimeter, square_foot, square_inch, square_meter, square_mile [and aliases]
+
+"""
 
 #
 # Definitions of common area units

scimath/units/convert.py

@@ -22,44 +22,44 @@
 def convert(value, from_unit, to_unit):
     """ Coverts value from one unit to another.
 
-    Parameters
-    ----------
-    value : float
-        value to convert
-    from_unit : scimath.unit object
-        implied units of 'value'
-    to_unit : scimath.unit object
-        implied units of the returned float
-
-    Returns
-    -------
-    value * conversion_factor + offset : data type is the same as was passed
-    in.
-
-    Description
-    -----------
-
-    Checks first to see if from_unit and to_unit are equal and passes value
-    back in that case. Then convert() forms a conversion factor by dividing the
-    units. The offset is zero unless explicitly set otherwise in the unit
-    definition. Handling of UnitArrays is done by checking whether value is a
-    numpy.ndarray.
-
-    **Note**: Enthought has extended the original units implementation to
-    handle temperature conversions.  Temperature units are a special case
-    because they can have a different origin.
-
-    This causes a fundamental ambiguity. What behavior do we expect when we
-    convert temperature?
-
-    Option #1 When we convert 0 degrees centigrade we get 32 fahrenheit.
-
-    Option #2 When we convert a temperature difference of 0 degrees centigrade
-    we get a temperature difference of 0 degrees fahrenheit.
-
-    By convention we have made the units system behave like in Option
-    #1 so that convert() handles absolute temperatures, not temperature
-    differences.
+        Parameters
+        ----------
+        value : float
+            value to convert
+        from_unit : scimath.unit object
+            implied units of 'value'
+        to_unit : scimath.unit object
+            implied units of the returned float
+
+        Returns
+        -------
+        value * conversion_factor + offset : data type is the same as was passed
+        in.
+
+        Description
+        -----------
+
+        Checks first to see if from_unit and to_unit are equal and passes value
+        back in that case. Then convert() forms a conversion factor by dividing the
+        units. The offset is zero unless explicitly set otherwise in the unit
+        definition. Handling of UnitArrays is done by checking whether value is a
+        numpy.ndarray.
+
+        **Note**: Enthought has extended the original units implementation to
+        handle temperature conversions.  Temperature units are a special case
+        because they can have a different origin.
+
+        This causes a fundamental ambiguity. What behavior do we expect when we
+        convert temperature?
+
+        Option #1 When we convert 0 degrees centigrade we get 32 fahrenheit.
+
+        Option #2 When we convert a temperature difference of 0 degrees centigrade
+        we get a temperature difference of 0 degrees fahrenheit.
+
+        By convention we have made the units system behave like in Option
+        #1 so that convert() handles absolute temperatures, not temperature
+        differences.
     """
 
     # TODO: it would be nice if this function could handle inversion as well as

scimath/units/density.py

@@ -9,10 +9,14 @@
 # Thanks for using Enthought open source!
 
 """ Defines units of density
-Derived from: units/density.py [pyre system]
-              Michael A.G. Aivazis
-              California Institute of Technology
-              (c) 1998-2003
+
+    Derived from: units/density.py [pyre system]
+                  Michael A.G. Aivazis
+                  California Institute of Technology
+                  (c) 1998-2003
+
+    Symbols defined: grams_per_cubic_centimeter, kilograms_per_cubic_meter, lb_per_gal [and aliases]
+
 """
 
 #############################################################################

scimath/units/dimensionless.py

@@ -8,6 +8,12 @@
 #
 # Thanks for using Enthought open source!
 
+""" Defines units of dimensionless
+
+    Symbols defined: fractional, parts_per_million, parts_per_one, percent [and aliases]
+
+"""
+
 from copy import copy
 from scimath.units.SI import dimensionless
 from scimath.units.unit import one, dim

scimath/units/electromagnetism.py

@@ -8,6 +8,19 @@
 #
 # Thanks for using Enthought open source!
 
+""" Defines units of electromagnetism
+
+    Symbols defined: ampere, milli_ampere,
+                     farad, micro_farad, pico_farad,
+                     henry,
+                     ohm, ohm_meter, ohmm,
+                     siemen, mSiemen, siemens_per_meter,
+                     tesla,
+                     volt, milivolt,
+                     weber [and aliases]
+
+"""
+
 from copy import copy
 
 from scimath.units.SI import ampere, coulomb, farad, henry, joule, ohm, \

scimath/units/energy.py

@@ -19,17 +19,21 @@
 from .SI import joule, kilo, mega, giga
 
 
-#
-# Definitions of common energy units
-#
-# Data taken from
-#
-#     Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
-#         fourth edition, John Willey and Sons, 1993
-#
-#     The NIST Reference on Constants, Units and Uncertainty,
-#         http://physics.nist.gov/cuu
-#
+""" Definitions of common energy units
+
+    Data taken from Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
+    fourth edition, John Willey and Sons, 1993
+
+    The NIST Reference on Constants, Units and Uncertainty,
+    http://physics.nist.gov/cuu
+
+    Symbols defined: Btu,
+                     Calorie, calorie,
+                     electron_volt,
+                     erg,
+                     foot_pound,
+                     horse_power_hour, kilowatt_hour [and aliases]
+"""
 
 
 Btu = 1055 * joule

scimath/units/force.py

@@ -8,6 +8,12 @@
 #
 # Thanks for using Enthought open source!
 
+""" Defines units of force
+
+    Symbols defined: lbf, lbs, N [and aliases]
+
+"""
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 #                             Michael A.G. Aivazis

scimath/units/frequency.py

@@ -9,6 +9,8 @@
 # Thanks for using Enthought open source!
 
 """ Defines units of frequency
+
+    Symbols defined: hertz, kilohertz, rpm [and aliases]
 """
 
 #############################################################################

scimath/units/geo_units.py

@@ -8,6 +8,15 @@
 #
 # Thanks for using Enthought open source!
 
+""" Defines units of Geo Units
+
+    Symbols defined: g_km_per_cc_s, g_ft_per_cc_s, rayl, mrayl,
+                     barns_per_electron, psi_per_f,
+                     MPa_per_m, MPa_per_100f,
+                     lb_per_gal, api, gapi, us_per_ft [and aliases]
+
+"""
+
 from copy import copy
 
 from scimath.units.SI import ampere, atto, becquerel, candela, centi, \

scimath/units/length.py

@@ -9,10 +9,18 @@
 # Thanks for using Enthought open source!
 
 """ Defines units of length
-Derived from: units/length.py [pyre system]
-              Michael A.G. Aivazis
-              California Institute of Technology
-              (c) 1998-2003
+
+    Derived from: units/length.py [pyre system]
+                  Michael A.G. Aivazis
+                  California Institute of Technology
+                  (c) 1998-2003
+
+    Symbols defined: kilo-, centi-, milli-, micro-, nano-, pico-, meter,
+                     inch, foot, yard, mile,
+                     fathom, nautical_mile,
+                     angstrom, fermi, survey_foot, us_foot, us_feet,
+                     astronomical_unit, light_year, parsec [and aliases]
+
 """
 
 #############################################################################

scimath/units/mass.py

@@ -9,10 +9,16 @@
 # Thanks for using Enthought open source!
 
 """ Defines units of mass
-Derived from: units/mass.py [pyre system]
-              Michael A.G. Aivazis
-              California Institute of Technology
-              (c) 1998-2003
+
+    Derived from: units/mass.py [pyre system]
+                  Michael A.G. Aivazis
+                  California Institute of Technology
+                  (c) 1998-2003
+
+    Symbols defined: centigram, gram, kilogram, milligram,
+                     metric_ton, ton,
+                     ounce, pound [and aliases]
+              
 """
 
 #############################################################################

scimath/units/power.py

@@ -18,10 +18,12 @@
 
 from .SI import watt, kilo
 
-#
-# Definitions of common power units
-# Data taken from Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
-#     fourth edition, John Willey and Sons, 1993
+""" Definitions of common power units
+
+    Data taken from Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
+    fourth edition, John Willey and Sons, 1993
+    Symbols defined: kilowatt, horsepower [and aliases]
+"""
 
 kilowatt = kilo * watt
 kw = kilowatt

scimath/units/pressure.py

@@ -20,17 +20,17 @@
 from scimath.units.force import lbf
 from scimath.units.length import inch
 from scimath.units.unit import unit
-#
-# Definitions of common pressure units
-#
-# Data taken from
-#     Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
-#         fourth edition, John Willey and Sons, 1993
-#
-#     The NIST Reference on Constants, Units and Uncertainty,
-#         http://physics.nist.gov/cuu
-#
+""" Definitions of common pressure units
+
+    Data taken from Appendix F of Halliday, Resnick, Walker, "Fundamentals of Physics",
+    fourth edition, John Willey and Sons, 1993
+    The NIST Reference on Constants, Units and Uncertainty,
+    http://physics.nist.gov/cuu
 
+    Symbols defined: pascal, kPa, MPa, GPa, inHg,
+                     bar, kilobar, millibar, torr, atmosphere,
+                     pounds_per_square_inch [and aliases]
+"""
 
 # aliases
 

scimath/units/speed.py

@@ -9,10 +9,15 @@
 # Thanks for using Enthought open source!
 
 """ Defines units of density.
-Derived from: units/density.py [pyre system]
-              Michael A.G. Aivazis
-              California Institute of Technology
-              (c) 1998-2003
+
+    Derived from: units/density.py [pyre system]
+                  Michael A.G. Aivazis
+                  California Institute of Technology
+                  (c) 1998-2003
+
+    Symbols defined: feet_per_second, meters_per_second, kilometers_per_second, miles_per_hour,
+                     knot [and aliases]
+
 """
 
 #############################################################################

scimath/units/substance.py

@@ -16,6 +16,11 @@
 #
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+""" Defines units of substance
+
+    Symbols defined: mole, kmole [and aliases]
+"""
+
 from .SI import mole, kilo
 
 

scimath/units/temperature.py

@@ -16,6 +16,11 @@
 #
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+""" Defines units of temperature
+
+    Symbols defined: celsius, fahrenheit, kelvin, rankine [and aliases]
+"""
+
 from scimath.units.unit import unit
 
 # Tk = Tk