Move the 3k reST doc tree in place.

1 files changed, 156 insertions, 0 deletions

diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
new file mode 100644
index 0000000..2bc162c
--- /dev/null
+++ b/Doc/library/cmath.rst
@@ -0,0 +1,156 @@
+
+:mod:`cmath` --- Mathematical functions for complex numbers
+===========================================================
+
+.. module:: cmath
+   :synopsis: Mathematical functions for complex numbers.
+
+
+This module is always available.  It provides access to mathematical functions
+for complex numbers.  The functions in this module accept integers,
+floating-point numbers or complex numbers as arguments. They will also accept
+any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
+method: these methods are used to convert the object to a complex or
+floating-point number, respectively, and the function is then applied to the
+result of the conversion.
+
+The functions are:
+
+
+.. function:: acos(x)
+
+   Return the arc cosine of *x*. There are two branch cuts: One extends right from
+   1 along the real axis to ∞, continuous from below. The other extends left from
+   -1 along the real axis to -∞, continuous from above.
+
+
+.. function:: acosh(x)
+
+   Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
+   from 1 along the real axis to -∞, continuous from above.
+
+
+.. function:: asin(x)
+
+   Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+
+
+.. function:: asinh(x)
+
+   Return the hyperbolic arc sine of *x*. There are two branch cuts, extending
+   left from ``±1j`` to ``±∞j``, both continuous from above. These branch cuts
+   should be considered a bug to be corrected in a future release. The correct
+   branch cuts should extend along the imaginary axis, one from ``1j`` up to
+   ``∞j`` and continuous from the right, and one from ``-1j`` down to ``-∞j``
+   and continuous from the left.
+
+
+.. function:: atan(x)
+
+   Return the arc tangent of *x*. There are two branch cuts: One extends from
+   ``1j`` along the imaginary axis to ``∞j``, continuous from the left. The
+   other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
+   from the left. (This should probably be changed so the upper cut becomes
+   continuous from the other side.)
+
+
+.. function:: atanh(x)
+
+   Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
+   extends from ``1`` along the real axis to ``∞``, continuous from above. The
+   other extends from ``-1`` along the real axis to ``-∞``, continuous from
+   above. (This should probably be changed so the right cut becomes continuous
+   from the other side.)
+
+
+.. function:: cos(x)
+
+   Return the cosine of *x*.
+
+
+.. function:: cosh(x)
+
+   Return the hyperbolic cosine of *x*.
+
+
+.. function:: exp(x)
+
+   Return the exponential value ``e**x``.
+
+
+.. function:: log(x[, base])
+
+   Returns the logarithm of *x* to the given *base*. If the *base* is not
+   specified, returns the natural logarithm of *x*. There is one branch cut, from 0
+   along the negative real axis to -∞, continuous from above.
+
+   .. versionchanged:: 2.4
+      *base* argument added.
+
+
+.. function:: log10(x)
+
+   Return the base-10 logarithm of *x*. This has the same branch cut as
+   :func:`log`.
+
+
+.. function:: sin(x)
+
+   Return the sine of *x*.
+
+
+.. function:: sinh(x)
+
+   Return the hyperbolic sine of *x*.
+
+
+.. function:: sqrt(x)
+
+   Return the square root of *x*. This has the same branch cut as :func:`log`.
+
+
+.. function:: tan(x)
+
+   Return the tangent of *x*.
+
+
+.. function:: tanh(x)
+
+   Return the hyperbolic tangent of *x*.
+
+The module also defines two mathematical constants:
+
+
+.. data:: pi
+
+   The mathematical constant *pi*, as a float.
+
+
+.. data:: e
+
+   The mathematical constant *e*, as a float.
+
+.. index:: module: math
+
+Note that the selection of functions is similar, but not identical, to that in
+module :mod:`math`.  The reason for having two modules is that some users aren't
+interested in complex numbers, and perhaps don't even know what they are.  They
+would rather have ``math.sqrt(-1)`` raise an exception than return a complex
+number. Also note that the functions defined in :mod:`cmath` always return a
+complex number, even if the answer can be expressed as a real number (in which
+case the complex number has an imaginary part of zero).
+
+A note on branch cuts: They are curves along which the given function fails to
+be continuous.  They are a necessary feature of many complex functions.  It is
+assumed that if you need to compute with complex functions, you will understand
+about branch cuts.  Consult almost any (not too elementary) book on complex
+variables for enlightenment.  For information of the proper choice of branch
+cuts for numerical purposes, a good reference should be the following:
+
+
+.. seealso::
+
+   Kahan, W:  Branch cuts for complex elementary functions; or, Much ado about
+   nothing's sign bit.  In Iserles, A., and Powell, M. (eds.), The state of the art
+   in numerical analysis. Clarendon Press (1987) pp165-211.
+