Merge pull request sympy#1033 from smichr/root-doc

add note about real_root to root function

doc/src/modules/physics/mechanics/examples.txt

@@ -323,7 +323,7 @@ Assignment the relevant points to each body. ::
   >>> BodyWR.mc = WR_mc
 
 Sets the inertias of each body. Uses the inertia frame to construct the inertia
-dyadics. Wheel inertias are only defined by principle moments of inertia, and
+dyadics. Wheel inertias are only defined by principal moments of inertia, and
 are in fact constant in the frame and fork reference frames; it is for this
 reason that the orientations of the wheels does not need to be defined. The
 frame and fork inertias are defined in the 'Temp' frames which are fixed to the

sympy/functions/elementary/miscellaneous.py

@@ -68,7 +68,7 @@ def sqrt(arg):
     >>> x.subs(x, -1)
     -1
 
-    This is because sqrt computes the principle square root, so the square may
+    This is because sqrt computes the principal square root, so the square may
     put the argument in a different branch.  This identity does hold if x is
     positive:
 
@@ -148,6 +148,24 @@ def root(arg, n):
     >>> [ RootOf(x**4-1,i) for i in (0,1,2,3) ]
     [-1, 1, -I, I]
 
+    SymPy, like other symbolic algebra systems, returns the
+    complex root of negative numbers. This is the principal
+    root and differs from the text-book result that one might
+    be expecting. For example, the cube root of -8 does not
+    come back as -2:
+
+    >>> root(-8, 3)
+    2*(-1)**(1/3)
+
+    The real_root function can be used to either make such a result
+    real or simply return the real root in the first place:
+
+    >>> from sympy import real_root
+    >>> real_root(_)
+    -2
+    >>> real_root(-32, 5)
+    -2
+
     See Also
     ========
 
@@ -162,6 +180,7 @@ def root(arg, n):
     * http://en.wikipedia.org/wiki/real_root
     * http://en.wikipedia.org/wiki/Root_of_unity
     * http://en.wikipedia.org/wiki/Principal_value
+    * http://mathworld.wolfram.com/CubeRoot.html
 
     """
     n = sympify(n)

sympy/solvers/solvers.py

@@ -1992,7 +1992,7 @@ def _invert(eq, *symbols, **kwargs):
     (0, sqrt(x) + y)
 
     If there is more than one symbol in a power's base and the exponent
-    is not an Integer, then the principle root will be used for the
+    is not an Integer, then the principal root will be used for the
     inversion:
 
     >>> invert(sqrt(x + y) - 2)
@@ -2001,7 +2001,7 @@ def _invert(eq, *symbols, **kwargs):
     (4, x + y)
 
     If the exponent is an integer, setting ``integer_power`` to True
-    will force the principle root to be selected:
+    will force the principal root to be selected:
 
     >>> invert(x**2 - 4, integer_power=True)
     (2, x)