[Numpy-svn] r4131 - trunk/numpy/doc

numpy-svn@scip... numpy-svn@scip...
Tue Sep 25 06:32:50 CDT 2007


Author: stefan
Date: 2007-09-25 06:32:19 -0500 (Tue, 25 Sep 2007)
New Revision: 4131

Modified:
   trunk/numpy/doc/CAPI.txt
   trunk/numpy/doc/pep_buffer.txt
   trunk/numpy/doc/records.txt
   trunk/numpy/doc/ufuncs.txt
Log:
ReST fixes.


Modified: trunk/numpy/doc/CAPI.txt
===================================================================
--- trunk/numpy/doc/CAPI.txt	2007-09-25 11:04:33 UTC (rev 4130)
+++ trunk/numpy/doc/CAPI.txt	2007-09-25 11:32:19 UTC (rev 4131)
@@ -3,9 +3,11 @@
 ===============
 
 :Author:          Travis Oliphant
-:Discussions to:  scipy-dev@scipy.org
+:Discussions to:  `numpy-discussion@scipy.org`__
 :Created:         October 2005
 
+__ http://www.scipy.org/Mailing_Lists
+
 The C API of NumPy is (mostly) backward compatible with Numeric.
 
 There are a few non-standard Numeric usages (that were not really part

Modified: trunk/numpy/doc/pep_buffer.txt
===================================================================
--- trunk/numpy/doc/pep_buffer.txt	2007-09-25 11:04:33 UTC (rev 4130)
+++ trunk/numpy/doc/pep_buffer.txt	2007-09-25 11:32:19 UTC (rev 4131)
@@ -1,13 +1,13 @@
-PEP: 3118
-Title: Revising the buffer protocol
-Version: $Revision$
-Last-Modified: $Date$
-Authors: Travis Oliphant <oliphant@ee.byu.edu>, Carl Banks <pythondev@aerojockey.com>
-Status: Draft
-Type: Standards Track
-Content-Type: text/x-rst
-Created: 28-Aug-2006
-Python-Version: 3000
+:PEP: 3118
+:Title: Revising the buffer protocol
+:Version: $Revision$
+:Last-Modified: $Date$
+:Authors: Travis Oliphant <oliphant@ee.byu.edu>, Carl Banks <pythondev@aerojockey.com>
+:Status: Draft
+:Type: Standards Track
+:Content-Type: text/x-rst
+:Created: 28-Aug-2006
+:Python-Version: 3000
 
 Abstract
 ========

Modified: trunk/numpy/doc/records.txt
===================================================================
--- trunk/numpy/doc/records.txt	2007-09-25 11:04:33 UTC (rev 4130)
+++ trunk/numpy/doc/records.txt	2007-09-25 11:32:19 UTC (rev 4131)
@@ -1,86 +1,87 @@
 
-The ndarray supports records intrinsically.  
-None of the default descriptors have fields defined, but you can create new
-descriptors easily.  The ndarray even supports nested arrays of records inside 
-of a record.  Any record that the array protocol can describe can be represented. 
-The ndarray also supports partial field descriptors.  Not every byte has to be
-accounted for. 
+The ndarray supports records intrinsically.  None of the default
+descriptors have fields defined, but you can create new descriptors
+easily.  The ndarray even supports nested arrays of records inside of
+a record.  Any record that the array protocol can describe can be
+represented.  The ndarray also supports partial field descriptors.
+Not every byte has to be accounted for.
 
-This was done by adding to the established PyArray_Descr * structure:
+This was done by adding to the established ``PyArray_Descr *`` structure:
 
-1) a PyObject *fields member which contains a dictionary of 
-"field name" : (PyArray_Descr *field-type, offset, [optional field title]). 
-If a title is given, then it is also inserted into the dictionary and used to 
-key the same entry. 
+1. A PyObject ``*fields`` member which contains a dictionary of "field
+   name" : (``PyArray_Descr`` ``*field-type``, ``offset``, [optional field
+   title]).  If a title is given, then it is also inserted into the
+   dictionary and used to key the same entry.
 
-2) A byteorder member.  By default this is '=' (native), or '|' (not-applicable).
+2. A byteorder member.  By default this is '=' (native), or '|'
+   (not-applicable).
 
-3) An additional PyArray_ArrDescr *member of the structure which
-contains a simple representation of an array of another base-type.
-types. The PyArray_ArrayDescr structure has members PyArray_Descr *,
-PyObject *, for holding a reference to the base-type and the shape of
-the sub-array.
+3. An additional ``PyArray_ArrDescr`` ``*member`` of the structure which
+   contains a simple representation of an array of another base-type.
+   types. The ``PyArray_ArrayDescr`` structure has members
+   ``PyArray_Descr *``, ``PyObject *``, for holding a reference to
+   the base-type and the shape of the sub-array.
 
-4) The PyArray_Descr * as official Python object that fully describes
-a region of memory for the data
+4. The ``PyArray_Descr *`` as official Python object that fully describes
+   a region of memory for the data
 
- 
-Data type conversions: We can support additional data-type
-conversions.  The data-type passed in is converted to a PyArray_Descr*
-object.
 
+Data type conversions
+---------------------
+
+We can support additional data-type
+conversions.  The data-type passed in is converted to a
+``PyArray_Descr *`` object.
+
 New possibilities for the "data-type"
+`````````````````````````````````````
 
-List [data-type 1, data-type 2, ..., data-type n]
-===============================
-Equivalent to  {'names':['f1','f2',...,'fn'],
+**List [data-type 1, data-type 2, ..., data-type n]**
+  Equivalent to  {'names':['f1','f2',...,'fn'],
 	        'formats': [data-type 1, data-type 2, ..., data-type n]}
 
-This is a quick way to specify a record format with default field names.
+  This is a quick way to specify a record format with default field names.
 
 
-Tuple  (flexible type, itemsize)
-       (fixed type, shape)
-===============================
+**Tuple  (flexible type, itemsize) (fixed type, shape)**
+  Get converted to a new ``PyArray_Descr *`` object with a flexible
+  type. The latter structure also sets the ``PyArray_ArrayDescr`` field of the
+  returned ``PyArray_Descr *``.
 
-Get converted to a new PyArray_Descr * object with a flexible
-type. The latter structure also sets the PyArray_ArrayDescr field of the
-returned PyArray_Descr *.
 
+**Dictionary (keys "names", "titles", and "formats")**
+  This will be converted to a ``PyArray_VOID`` type with corresponding
+  fields parameter (the formats list will be converted to actual
+  ``PyArray_Descr *`` objects).
 
-Dictionary (keys "names", "titles", and "formats")
-===============================
 
-This will be converted to a PyArray_VOID type with corresponding
-fields parameter (the formats list will be converted to actual
-PyArray_Descr * objects).
+**Objects (anything with an .itemsize and .fields attribute)**
+  If its an instance of (a sub-class of) void type, then a new
+  ``PyArray_Descr*`` structure is created corresponding to its
+  typeobject (and ``PyArray_VOID``) typenumber.  If the type is
+  registered, then the registered type-number is used.
 
+  Otherwise a new ``PyArray_VOID PyArray_Descr*`` structure is created
+  and filled ->elsize and ->fields filled in appropriately.
 
-Objects (anything with an .itemsize and .fields attribute)
-=============================== 
+  The itemsize attribute must return a number > 0. The fields
+  attribute must return a dictionary with at least "names" and
+  "formats" entries.  The "formats" entry will be converted to a
+  "proper" descr->fields entry (all generic data-types converted to
+  ``PyArray_Descr *`` structure).
 
-If its an instance of (a sub-class of) void type, then a new
-PyArray_Descr* structure is created corresponding to its typeobject 
-(and PyArray_VOID) typenumber.  If the type is registered, then the
-registered type-number is used. 
 
-otherwise a new PyArray_VOID PyArray_Descr* structure is created and
-filled ->elsize and ->fields filled in appropriately.
+Reference counting for ``PyArray_Descr *`` objects.
+```````````````````````````````````````````````````
 
-The itemsize attribute must return a number > 0
-The fields attribute must return a dictionary with at least 
-"names" and "formats" entries.  The "formats" entry will be 
-converted to a "proper" descr->fields entry (all generic data-types
-converted to PyArray_Descr * structure). 
+Most functions that take ``PyArary_Descr *`` as arguments and return a
+``PyObject *`` steal the reference unless otherwise noted in the code:
 
+Functions that return ``PyArray_Descr *`` objects return a new
+reference.
 
-Reference counting for PyArray_Descr * objects.
+.. tip::
 
-Most functions that take PyArary_Descr * as arguments and return a PyObject *
-steal the reference unless otherwise noted in the code: 
+  There is a new function  and a new method of array objects both labelled
+  dtypescr which can be used to try out the ``PyArray_DescrConverter``.
 
-Functions that return PyArray_Descr * objects return a new reference. 
-
-There is a new function  and a new method of array objects both labelled
-dtypescr which can be used to try out the PyArray_DescrConverter.
-

Modified: trunk/numpy/doc/ufuncs.txt
===================================================================
--- trunk/numpy/doc/ufuncs.txt	2007-09-25 11:04:33 UTC (rev 4130)
+++ trunk/numpy/doc/ufuncs.txt	2007-09-25 11:32:19 UTC (rev 4131)
@@ -1,18 +1,20 @@
+BUFFERED General Ufunc explanation
+==================================
 
-BUFFERED General Ufunc explanation:
+.. note::
 
-Note:  This was implemented already, but the notes are kept here for historical 
-       and explanatory purposes.
+  This was implemented already, but the notes are kept here for historical
+  and explanatory purposes.
 
 We need to optimize the section of ufunc code that handles mixed-type
 and misbehaved arrays.  In particular, we need to fix it so that items
-are not copied into the buffer if they don't have to be. 
+are not copied into the buffer if they don't have to be.
 
 Right now, all data is copied into the buffers (even scalars are copied
-multiple times into the buffers even if they are not going to be cast). 
+multiple times into the buffers even if they are not going to be cast).
 
-Some benchmarks show that this results in a significant slow-down 
-(factor of 4) over similar numarray code. 
+Some benchmarks show that this results in a significant slow-down
+(factor of 4) over similar numarray code.
 
 The approach is therefore, to loop over the largest-dimension (just like
 the NO_BUFFER) portion of the code.  All arrays will either have N or
@@ -31,31 +33,31 @@
 If N > B, then we have to do the above operation in a loop (with an extra loop
 at the end with a different buffer size).
 
-Both of these cases are handled with the following code:
+Both of these cases are handled with the following code::
 
-Compute N = quotient * B + remainder.   
-   quotient = N / B  # integer math    
-         (store quotient + 1) as the number of innerloops
+   Compute N = quotient * B + remainder.
+   quotient = N / B  # integer math
+   (store quotient + 1) as the number of innerloops
    remainder = N % B # integer remainder
 
-On the inner-dimension we will have (quotient + 1) loops where 
+On the inner-dimension we will have (quotient + 1) loops where
 the size of the inner function is B for all but the last when the niter size is
-remainder. 
+remainder.
 
-So, the code looks very similar to NOBUFFER_LOOP except the inner loop is 
-replaced with...
+So, the code looks very similar to NOBUFFER_LOOP except the inner loop is
+replaced with::
 
-for(k=0; i<quotient+1; k++) {
-	 if (k==quotient+1) make itersize remainder size
-	 copy only needed items to buffer.
-	 swap input buffers if needed
-	 cast input buffers if needed
-	 call function()
-	 cast outputs in buffers if needed
-	 swap outputs in buffers if needed
- 	 copy only needed items back to output arrays.	 
-	 update all data-pointers by strides*niter
-}
+  for(k=0; i<quotient+1; k++) {
+      if (k==quotient+1) make itersize remainder size
+      copy only needed items to buffer.
+      swap input buffers if needed
+      cast input buffers if needed
+      call function()
+      cast outputs in buffers if needed
+      swap outputs in buffers if needed
+      copy only needed items back to output arrays.
+      update all data-pointers by strides*niter
+  }
 
 
 Reference counting for OBJECT arrays:
@@ -63,19 +65,19 @@
 If there are object arrays involved then loop->obj gets set to 1.  Then there are two cases:
 
 1) The loop function is an object loop:
-  
-   Inputs:  
+
+   Inputs:
 	    - castbuf starts as NULL and then gets filled with new references.
 	    - function gets called and doesn't alter the reference count in castbuf
 	    - on the next iteration (next value of k), the casting function will
 	      DECREF what is present in castbuf already and place a new object.
-	     
+
 	    - At the end of the inner loop (for loop over k), the final new-references
 	      in castbuf must be DECREF'd.  If its a scalar then a single DECREF suffices
-	      Otherwise, "bufsize" DECREF's are needed (unless there was only one 
+	      Otherwise, "bufsize" DECREF's are needed (unless there was only one
 	      loop, then "remainder" DECREF's are needed).
 
-   Outputs: 
+   Outputs:
             - castbuf contains a new reference as the result of the function call.  This
 	      gets converted to the type of interest and.  This new reference in castbuf
 	      will be DECREF'd by later calls to the function.  Thus, only after the
@@ -89,13 +91,13 @@
 	      reference.  This reference is then used but not altered by the cast
 	      call.   Nothing needs to be done.
 
-   Outputs: 
-   
-            - The buffer[i] memory receives the PyObject input after the cast.  This is 
-	      a new reference which will be "stolen" as it is copied over into memory. 
+   Outputs:
+
+            - The buffer[i] memory receives the PyObject input after the cast.  This is
+	      a new reference which will be "stolen" as it is copied over into memory.
 	      The only problem is that what is presently in memory must be DECREF'd first.
 
 
 
-	 
-	      
+
+



More information about the Numpy-svn mailing list