diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/reference/arrays.classes.rst | 8 | ||||
| -rw-r--r-- | doc/source/reference/arrays.ndarray.rst | 41 | ||||
| -rw-r--r-- | doc/source/reference/c-api.array.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/distutils.rst | 30 | ||||
| -rw-r--r-- | doc/source/reference/routines.math.rst | 7 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 2 | ||||
| -rw-r--r-- | doc/source/user/index.rst | 19 | ||||
| -rw-r--r-- | doc/source/user/whatisnumpy.rst | 156 |
8 files changed, 159 insertions, 106 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 6d5e7bde0..51d97e53a 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -230,8 +230,8 @@ Character arrays (:mod:`numpy.char`) .. note:: The chararray module exists for backwards compatibility with Numarray, it is not recommended for new development. If one needs - arrays of strings, use arrays of `dtype` `object_`, `string_` or - `unicode_`. + arrays of strings, use arrays of `dtype` `object_`, `str` or + `unicode`. These are enhanced arrays of either :class:`string_` type or :class:`unicode_` type. These arrays inherit from the @@ -242,7 +242,7 @@ character type. In addition, the :class:`chararray` has all of the standard :class:`string <str>` (and :class:`unicode`) methods, executing them on an element-by-element basis. Perhaps the easiest way to create a chararray is to use :meth:`self.view(chararray) -<ndarray.view>` where *self* is an ndarray of string or unicode +<ndarray.view>` where *self* is an ndarray of str or unicode data-type. However, a chararray can also be created using the :meth:`numpy.chararray` constructor, or via the :func:`numpy.char.array <core.defchararray.array>` function: @@ -253,7 +253,7 @@ data-type. However, a chararray can also be created using the chararray core.defchararray.array -Another difference with the standard ndarray of string data-type is +Another difference with the standard ndarray of str data-type is that the chararray inherits the feature introduced by Numarray that white-space at the end of any element in the array will be ignored on item retrieval and comparison operations. diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 1bf7d1ac8..0cad2ac6e 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -120,6 +120,8 @@ strided scheme, and correspond to the strides: .. index:: single-segment, contiguous, non-contiguous +where :math:`d_j` = `self.itemsize * self.shape[j]`. + Both the C and Fortran orders are :term:`contiguous`, *i.e.,* :term:`single-segment`, memory layouts, in which every part of the memory block can be accessed by some combination of the indices. @@ -231,7 +233,7 @@ Array methods An :class:`ndarray` object has many methods which operate on or with the array in some fashion, typically returning an array result. These -methods are briefly explained below. (Each method's doc string has a +methods are briefly explained below. (Each method's docstring has a more complete description.) For the following methods there are also corresponding functions in @@ -317,11 +319,45 @@ Many of these methods take an argument named *axis*. In such cases, - If *axis* is *None* (the default), the array is treated as a 1-D array and the operation is performed over the entire array. This behavior is also the default if self is a 0-dimensional array or - array scalar. + array scalar. (An array scalar is an instance of the types/classes + float32, float64, etc., whereas a 0-dimensional array is an ndarray + instance containing precisely one array scalar.) - If *axis* is an integer, then the operation is done over the given axis (for each 1-D subarray that can be created along the given axis). +.. admonition:: Example of the *axis* argument + + A 3-dimensional array of size 3 x 3 x 3, summed over each of its + three axes + + >>> x + array([[[ 0, 1, 2], + [ 3, 4, 5], + [ 6, 7, 8]], + [[ 9, 10, 11], + [12, 13, 14], + [15, 16, 17]], + [[18, 19, 20], + [21, 22, 23], + [24, 25, 26]]]) + >>> x.sum(axis=0) + array([[27, 30, 33], + [36, 39, 42], + [45, 48, 51]]) + >>> # for sum, axis is the first keyword, so we may omit it, + >>> # specifying only its value + >>> x.sum(0), x.sum(1), x.sum(2) + (array([[27, 30, 33], + [36, 39, 42], + [45, 48, 51]]), + array([[ 9, 12, 15], + [36, 39, 42], + [63, 66, 69]]), + array([[ 3, 12, 21], + [30, 39, 48], + [57, 66, 75]])) + The parameter *dtype* specifies the data type over which a reduction operation (like summing) should take place. The default reduce data type is the same as the data type of *self*. To avoid overflow, it can @@ -333,7 +369,6 @@ argument must be an :class:`ndarray` and have the same number of elements. It can have a different data type in which case casting will be performed. - .. autosummary:: :toctree: generated/ diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 3716fa16b..49d073b7e 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -2372,7 +2372,7 @@ Other conversions signed and unsigned integers, floating point numbers, and complex-floating point numbers are recognized and converted. Other values of gentype are returned. This function can be used to - convert, for example, the string'f4' to :cdata:`NPY_FLOAT32`. + convert, for example, the string 'f4' to :cdata:`NPY_FLOAT32`. Miscellaneous diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst index bb01a529a..63174c2c7 100644 --- a/doc/source/reference/distutils.rst +++ b/doc/source/reference/distutils.rst @@ -6,7 +6,7 @@ Packaging (:mod:`numpy.distutils`) NumPy provides enhanced distutils functionality to make it easier to build and install sub-packages, auto-generate code, and extension -modules that use Fortran-compiled libraries. To use features of numpy +modules that use Fortran-compiled libraries. To use features of NumPy distutils, use the :func:`setup <core.setup>` command from :mod:`numpy.distutils.core`. A useful :class:`Configuration <misc_util.Configuration>` class is also provided in @@ -33,7 +33,6 @@ misc_util Configuration get_numpy_include_dirs - get_numarray_include_dirs dict_append appendpath allpath @@ -128,13 +127,13 @@ Other modules Building Installable C libraries ================================ -Conventional C libraries (installed through add_library) are not installed, and +Conventional C libraries (installed through `add_library`) are not installed, and are just used during the build (they are statically linked). An installable C library is a pure C library, which does not depend on the python C runtime, and -is installed such as it may be used by third-party packages. To build and -install the C library, you just use the method add_installed_library instead of -add_library, which takes the same arguments except for an additional -install_dir argument:: +is installed such that it may be used by third-party packages. To build and +install the C library, you just use the method `add_installed_library` instead of +`add_library`, which takes the same arguments except for an additional +``install_dir`` argument:: >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib') @@ -142,8 +141,8 @@ npy-pkg-config files -------------------- To make the necessary build options available to third parties, you could use -the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is -based on an .ini file which contains all the options. A .ini file is very +the `npy-pkg-config` mechanism implemented in `numpy.distutils`. This mechanism is +based on a .ini file which contains all the options. A .ini file is very similar to .pc files as used by the pkg-config unix utility:: [meta] @@ -162,7 +161,7 @@ similar to .pc files as used by the pkg-config unix utility:: Generally, the file needs to be generated during the build, since it needs some information known at build time only (e.g. prefix). This is mostly automatic if -one uses the Configuration method add_npy_pkg_config. Assuming we have a +one uses the `Configuration` method `add_npy_pkg_config`. Assuming we have a template file foo.ini.in as follows:: [meta] @@ -186,22 +185,23 @@ and the following code in setup.py:: >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst) This will install the file foo.ini into the directory package_dir/lib, and the -foo.ini file will be generated from foo.ini.in, where each @version@ will be -replaced by subst_dict['version']. The dictionary has an additional prefix +foo.ini file will be generated from foo.ini.in, where each ``@version@`` will be +replaced by ``subst_dict['version']``. The dictionary has an additional prefix substitution rule automatically added, which contains the install prefix (since this is not easy to get from setup.py). npy-pkg-config files can also be installed at the same location as used for numpy, using the path returned from -get_npy_pkg_dir function. +`get_npy_pkg_dir` function. Reusing a C library from another package ---------------------------------------- -Info are easily retrieved from the get_info function in numpy.distutils.misc_util:: +Info are easily retrieved from the `get_info` function in +`numpy.distutils.misc_util`:: >>> info = get_info('npymath') >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info) -An additional list of paths to look for .ini files can be given to get_info. +An additional list of paths to look for .ini files can be given to `get_info`. Conversion of ``.src`` files ============================ diff --git a/doc/source/reference/routines.math.rst b/doc/source/reference/routines.math.rst index 326391292..7ce77c24d 100644 --- a/doc/source/reference/routines.math.rst +++ b/doc/source/reference/routines.math.rst @@ -19,6 +19,8 @@ Trigonometric functions degrees radians unwrap + deg2rad + rad2deg Hyperbolic functions -------------------- @@ -43,6 +45,7 @@ Rounding fix floor ceil + trunc Sums, products, differences --------------------------- @@ -67,10 +70,13 @@ Exponents and logarithms exp expm1 + exp2 log log10 log2 log1p + logaddexp + logaddexp2 Other special functions ----------------------- @@ -86,6 +92,7 @@ Floating point routines :toctree: generated/ signbit + copysign frexp ldexp diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index 59cdb71de..77269be58 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -313,7 +313,7 @@ possess. None of the attributes can be set. ============ ================================================================= **__doc__** A docstring for each ufunc. The first part of the docstring is dynamically generated from the number of outputs, the name, and - the number of inputs. The second part of the doc string is + the number of inputs. The second part of the docstring is provided at creation time and stored with the ufunc. **__name__** The name of the ufunc. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index ed8e186a7..c365c0af3 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,20 +1,23 @@ .. _user: ################ -Numpy User Guide +NumPy User Guide ################ -This guide explains how to make use of different features -of Numpy. For a detailed documentation about different functions -and classes, see :ref:`reference`. +This guide is intended as an introductory overview of NumPy and +explains how to install and make use of the most important features of +NumPy. For detailed reference documentation of the functions and +classes contained in the package, see the :ref:`reference`. .. warning:: - This "User Guide" is still very much work in progress; the material - is not organized, and many aspects of Numpy are not covered. + This "User Guide" is still a work in progress; some of the material + is not organized, and several aspects of NumPy are not yet covered + in sufficient detail. However, we are continually working to + improve the documentation. - More documentation for Numpy can be found on the - `scipy.org <http://www.scipy.org/Documentation>`__ website. + More documentation for NumPy can be found on the `numpy.org + <http://www.numpy.org>`__ website. .. toctree:: :maxdepth: 2 diff --git a/doc/source/user/whatisnumpy.rst b/doc/source/user/whatisnumpy.rst index 3a9abb79d..1c3f96b8b 100644 --- a/doc/source/user/whatisnumpy.rst +++ b/doc/source/user/whatisnumpy.rst @@ -2,52 +2,59 @@ What is NumPy? ************** -NumPy is the fundamental package for scientific computing in Python. It is a -Python library that provides a multidimensional array object, various derived -objects (such as masked arrays and matrices), and an assortment of routines -for fast operations on arrays, including mathematical, logical, shape -manipulation, sorting, I/O, discrete Fourier transform, basic linear algebra, -basic statistical and random simulation, etc., etc., etc. - -The core of the NumPy package, however, is the `ndarray` object. This -encapsulates *n*-dimensional arrays of homogeneous data. There are several -important differences between NumPy arrays and the standard Python sequences: - -- Unlike Python lists, NumPy arrays have a fixed size - changing their size - *will* create a new array and delete the original. - -- Unlike Python tuples, the elements in a NumPy array are all required to be - the same data type, and thus *will* be the same size in memory. The - exception: one can have arrays of (Python, including NumPy) objects, thereby +NumPy is the fundamental package for scientific computing in Python. +It is a Python library that provides a multidimensional array object, +various derived objects (such as masked arrays and matrices), and an +assortment of routines for fast operations on arrays, including +mathematical, logical, shape manipulation, sorting, selecting, I/O, +discrete Fourier transforms, basic linear algebra, basic statistical +operations, random simulation and much more. + +At the core of the NumPy package, is the `ndarray` object. This +encapsulates *n*-dimensional arrays of homogeneous data types, with +many operations being performed in compiled code for performance. +There are several important differences between NumPy arrays and the +standard Python sequences: + +- NumPy arrays have a fixed size at creation, unlike Python lists + (which can grow dynamically). Changing the size of an `ndarray` will + create a new array and delete the original. + +- The elements in a NumPy array are all required to be of the same + data type, and thus will be the same size in memory. The exception: + one can have arrays of (Python, including NumPy) objects, thereby allowing for arrays of different sized elements. -- NumPy arrays facilitate advanced mathematical and other types of operations - on large amounts of data. Typically, such operations are executed much - faster and with less code compared to what is possible using Python's - built-in sequences. +- NumPy arrays facilitate advanced mathematical and other types of + operations on large numbers of data. Typically, such operations are + executed more efficiently and with less code than is possible using + Python's built-in sequences. -- A growing plethora of scientific and mathematical Python-based packages are - keyed to using NumPy arrays; though these typically support Python-sequence - input, they convert such input to NumPy arrays prior to processing, and they - output NumPy arrays. In other words, in order to *efficiently* use much - (perhaps even most) of today's scientific/mathematical Python-based software, just - knowing how to use Python's built-in sequence types is insufficient - one - also needs to know how to use NumPy arrays. +- A growing plethora of scientific and mathematical Python-based + packages are using NumPy arrays; though these typically support + Python-sequence input, they convert such input to NumPy arrays prior + to processing, and they often output NumPy arrays. In other words, + in order to efficiently use much (perhaps even most) of today's + scientific/mathematical Python-based software, just knowing how to + use Python's built-in sequence types is insufficient - one also + needs to know how to use NumPy arrays. The points about sequence size and speed are particularly important in -scientific computing. For a simple example, consider the case of multiplying -every element in a 1-D sequence with the corresponding element in another -sequence of the same length. If the data are in two Python lists, ``a`` and -``b``, we could iterate over each element:: +scientific computing. As a simple example, consider the case of +multiplying each element in a 1-D sequence with the corresponding +element in another sequence of the same length. If the data are +stored in two Python lists, ``a`` and ``b``, we could iterate over +each element:: c = [] for i in range(len(a)): c.append(a[i]*b[i]) -This gives the right answer, but if ``a`` and ``b`` each contain millions of -numbers, we will be waiting a rather long time fot it. We could accomplish -the same task much more quickly in C by writing (neglecting variable -declarations and initializations, memory allocation, etc.) +This produces the correct answer, but if ``a`` and ``b`` each contain +millions of numbers, we will pay the price for the inefficiencies of +looping in Python. We could accomplish the same task much more +quickly in C by writing (for clarity we neglect variable declarations +and initializations, memory allocation, etc.) :: @@ -55,11 +62,11 @@ declarations and initializations, memory allocation, etc.) c[i] = a[i]*b[i]; } -This saves all the overhead involved in interpreting the Python code and -manipulating Python objects, but at the expense of our beloved Python benefits. -Furthermore, the coding work required increases with the dimensionality of our -data. In the case of a 2-D array, for example, the C code (abridged as before) -expands to +This saves all the overhead involved in interpreting the Python code +and manipulating Python objects, but at the expense of the benefits +gained from coding in Python. Furthermore, the coding work required +increases with the dimensionality of our data. In the case of a 2-D +array, for example, the C code (abridged as before) expands to :: @@ -69,9 +76,10 @@ expands to } } -NumPy gives us the best of both worlds: such element-by-element operation is -the "default mode" when an `ndarray` is involved, but the element-by-element -operation is speedily executed by pre-compiled C code. In NumPy +NumPy gives us the best of both worlds: element-by-element operations +are the "default mode" when an `ndarray` is involved, but the +element-by-element operation is speedily executed by pre-compiled C +code. In NumPy :: @@ -79,42 +87,42 @@ operation is speedily executed by pre-compiled C code. In NumPy does what the earlier examples do, at near-C speeds, but with the code simplicity we expect from something based on Python (indeed, the NumPy -idiom is even simpler!) This last example illustrates two of NumPy's +idiom is even simpler!). This last example illustrates two of NumPy's features which are the basis of much of its power: vectorization and broadcasting. -Vectorization describes the absence of any *explicit* looping, indexing, etc., -in the code - these things are taking place, of course, just "behind the -scenes" (in optimized, pre-compiled C code). Vectorized code has many -advantages, among which are: +Vectorization describes the absence of any explicit looping, indexing, +etc., in the code - these things are taking place, of course, just +"behind the scenes" (in optimized, pre-compiled C code). Vectorized +code has many advantages, among which are: - vectorized code is more concise and easier to read - fewer lines of code generally means fewer bugs -- the code more closely resembles standard mathematical notation (making it - easier, typically, to correctly code written mathematics) - -- vectorization results in more "Pythonic" code (without vectorization, our - code would still be littered with ``for`` loops; though of course not absent - in Python, generally speaking, we feel that if we have to use a ``for`` loop - in Python, we must be doing something wrong!) :-) - -Broadcasting, on the other hand, is the term used to describe the *implicit* -element-by-element behavior of operations; generally speaking, in NumPy all -"operations" (i.e., not just arithmetic operations, but logical, bit-wise, -function, etc.) behave in this implicit element-by-element fashion, i.e., they -"broadcast." Moreover, in the example above, ``a`` and ``b`` could be -multidimensional arrays of the same shape, or a scalar and an array, or even -two arrays of different shapes, as long as the smaller one is "expandable" to +- the code more closely resembles standard mathematical notation + (making it easier, typically, to correctly code mathematical + constructs) + +- vectorization results in more "Pythonic" code (without + vectorization, our code would still be littered with inefficient and + difficult to read ``for`` loops. + +Broadcasting is the term used to describe the implicit +element-by-element behavior of operations; generally speaking, in +NumPy all operations (i.e., not just arithmetic operations, but +logical, bit-wise, functional, etc.) behave in this implicit +element-by-element fashion, i.e., they broadcast. Moreover, in the +example above, ``a`` and ``b`` could be multidimensional arrays of the +same shape, or a scalar and an array, or even two arrays of with +different shapes. Provided that the smaller array is "expandable" to the shape of the larger in such a way that the resulting broadcast is -unambiguous and "makes sense" (the detailed "rules" of broadcasting are -described in `numpy.doc.broadcasting`). - -Finally, in tune with the rest of Python, NumPy fully supports an -object-oriented approach, starting, once again, with `ndarray`. -Unexceptionally, `ndarray` is a class, possessing many, *many* attributes, -both method and "other." Many, if not all, of its attributes duplicate -(indeed, call) functions in the outer-most NumPy namespace, so the programmer -has complete freedom to code in whichever paradigm she prefers and/or that -seems most appropriate to the task at hand. +unambiguous (for detailed "rules" of broadcasting see +`numpy.doc.broadcasting`). + +NumPy fully supports an object-oriented approach, starting, once +again, with `ndarray`. For example, `ndarray` is a class, possessing +numerous methods and attributes. Many, of it's methods mirror +functions in the outer-most NumPy namespace, giving the programmer has +complete freedom to code in whichever paradigm she prefers and/or +which seems most appropriate to the task at hand. |