From 2aca81bca9af7b61a320ff0a0a81af15e404613f Mon Sep 17 00:00:00 2001 From: Ankit Daftery Date: Wed, 31 Aug 2011 12:35:56 +0000 Subject: [PATCH] Added temporary directory for Reference documentation --- libs/numpy/doc/Reference/Jamfile | 25 ++ libs/numpy/doc/Reference/binary_ufunc.rst | 95 ++++++ libs/numpy/doc/Reference/dtype.rst | 88 +++++ libs/numpy/doc/Reference/multi_iter.rst | 104 ++++++ libs/numpy/doc/Reference/ndarray.rst | 383 ++++++++++++++++++++++ libs/numpy/doc/Reference/unary_ufunc.rst | 87 +++++ 6 files changed, 782 insertions(+) create mode 100644 libs/numpy/doc/Reference/Jamfile create mode 100644 libs/numpy/doc/Reference/binary_ufunc.rst create mode 100644 libs/numpy/doc/Reference/dtype.rst create mode 100644 libs/numpy/doc/Reference/multi_iter.rst create mode 100644 libs/numpy/doc/Reference/ndarray.rst create mode 100644 libs/numpy/doc/Reference/unary_ufunc.rst diff --git a/libs/numpy/doc/Reference/Jamfile b/libs/numpy/doc/Reference/Jamfile new file mode 100644 index 00000000..ca045773 --- /dev/null +++ b/libs/numpy/doc/Reference/Jamfile @@ -0,0 +1,25 @@ +# Copyright David Abrahams 2006. Distributed under the Boost +# Software License, Version 1.0. (See accompanying +# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +project user-config : requirements rst2html ; + +import docutils ; + +import path ; +sources = dtype.rst ndarray.rst multi_iter.rst unary_ufunc.rst binary_ufunc.rst ; +bases = $(sources:S=) ; + +# This is a path relative to the html/ subdirectory where the +# generated output will eventually be moved. +stylesheet = "--stylesheet=rst.css" ; + +for local b in $(bases) +{ + html $(b) : $(b).rst : + + "-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) + ; +} + +alias htmls : $(bases) ; +stage . : $(bases) ; diff --git a/libs/numpy/doc/Reference/binary_ufunc.rst b/libs/numpy/doc/Reference/binary_ufunc.rst new file mode 100644 index 00000000..6f569ffe --- /dev/null +++ b/libs/numpy/doc/Reference/binary_ufunc.rst @@ -0,0 +1,95 @@ +binary_ufunc +============ + +.. contents :: + +A ``binary_ufunc`` is a struct used as an intermediate step to broadcast two arguments so that a C++ function can be converted to a ufunc like function + + ```` contains the ``binary_ufunc`` structure definitions + + +synopsis +-------- + +:: + + namespace boost + { + namespace numpy + { + + template + + struct binary_ufunc + { + + static python::object call(TBinaryFunctor & self, python::object const & input1, python::object const & input2,python::object const & output) + + static python::object make(); + + } + } + } + + +constructors +------------ + +:: + + struct example_binary_ufunc + { + typedef any_valid first_argument_type; + typedef any_valid second_argument_type; + typedef any_valid result_type; + }; + +:Requirements: The ``any_valid`` type must be defined using typedef as a valid C++ type in order to use the struct methods correctly + +:Note: The struct must be exposed as a Python class, and an instance of the class must be created to use the ``call`` method corresponding to the ``__call__`` attribute of the Python object + +accessors +--------- + +:: + + template + static python::object call(TBinaryFunctor & self, python::object const & input, python::object const & output) ; + +:Requires: Typenames ``TBinaryFunctor`` and optionally ``TArgument1`` and ``TArgument2`` for argument type and ``TResult`` for result type + +:Effects: Passes a Python object to the underlying C++ functor after broadcasting its arguments + +:: + + template + static python::object make(); + +:Requires: Typenames ``TBinaryFunctor`` and optionally ``TArgument1`` and ``TArgument2`` for argument type and ``TResult`` for result type + +:Returns: A Python function object to call the overloaded () operator in the struct (in typical usage) + + + +Example(s) +---------- + +:: + + struct BinarySquare + { + typedef double first_argument_type; + typedef double second_argument_type; + typedef double result_type; + + double operator()(double a,double b) const { return (a*a + b*b) ; } + }; + + p::object ud = p::class_ >("BinarySquare").def("__call__", np::binary_ufunc::make()); + p::object inst = ud(); + result_array = inst.attr("__call__")(demo_array,demo_array) ; + std::cout << "Square of list with binary ufunc is " << p::extract (p::str(result_array)) << std::endl ; + diff --git a/libs/numpy/doc/Reference/dtype.rst b/libs/numpy/doc/Reference/dtype.rst new file mode 100644 index 00000000..d059ef46 --- /dev/null +++ b/libs/numpy/doc/Reference/dtype.rst @@ -0,0 +1,88 @@ +dtype +===== + +.. contents :: + +A `dtype`_ is an object describing the type of the elements of an ndarray + +.. _dtype: http://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html#data-type-objects-dtype + + ```` contains the method calls necessary to generate a python object equivalent to a numpy.dtype from builtin C++ objects, as well as to create custom dtypes from user defined types + + +synopsis +-------- + +:: + + namespace boost + { + namespace numpy + { + + class dtype : public python::object + { + static python::detail::new_reference convert(python::object::object_cref arg, bool align); + public: + + // Convert an arbitrary Python object to a data-type descriptor object. + template + explicit dtype(T arg, bool align=false) : python::object(convert(arg, align)) {} + + template static dtype get_builtin(); // Get the built-in numpy dtype associated with the given scalar template type. + + int get_itemsize() const; // Return the size of the data type in bytes. + + BOOST_PYTHON_FORWARD_OBJECT_CONSTRUCTORS(dtype, python::object); + + }; + + } + +constructors +------------ + +:: + + template + explicit dtype(T arg, bool align=false) : python::object(convert(arg, align)) {} + +:Requirements: The typename supplied, ``T`` must be either : + * a built-in C++ typename convertible to object + * a valid python object or convertible to object + +:Effects: Constructs an object from the supplied python object / convertible + to object / builtin C++ data type + +:Throws: Nothing + +:: + + template static dtype get_builtin(); + +:Requirements: The typename supplied, ``T`` must be a builtin C++ type also supported by numpy + +:Returns: Numpy dtype corresponding to builtin C++ type + +accessors +--------- + +:: + + int get_itemsize() const; + +:Returns: the size of the data type in bytes. + + +Example(s) +---------- + +:: + + namespace np = boost::numpy ; + + np::dtype dtype = np::dtype::get_builtin(); + + p::tuple for_custom_dtype = p::make_tuple("ha",dtype) ; + np::dtype custom_dtype = np::dtype(list_for_dtype) ; + diff --git a/libs/numpy/doc/Reference/multi_iter.rst b/libs/numpy/doc/Reference/multi_iter.rst new file mode 100644 index 00000000..9317b52e --- /dev/null +++ b/libs/numpy/doc/Reference/multi_iter.rst @@ -0,0 +1,104 @@ +multi_iter +========== + +.. contents :: + +A ``multi_iter`` is a Python object, intended to be used as an iterator It should generally only be used in loops. + + ```` contains the class definitions for ``multi_iter`` + + +synopsis +-------- + +:: + + namespace boost + { + namespace numpy + { + + class multi_iter : public python::object + { + public: + + BOOST_PYTHON_FORWARD_OBJECT_CONSTRUCTORS(multi_iter, python::object); + + void next(); + + bool not_done() const; + + char * get_data(int n) const; + + int const get_nd() const; + + Py_intptr_t const * get_shape() const; + + Py_intptr_t const shape(int n) const; + + }; + + + multi_iter make_multi_iter(python::object const & a1); + + multi_iter make_multi_iter(python::object const & a1, python::object const & a2); + + multi_iter make_multi_iter(python::object const & a1, python::object const & a2, python::object const & a3); + + } + } // namespace boost::numpy + + +constructors +------------ + +:: + + multi_iter make_multi_iter(python::object const & a1); + + multi_iter make_multi_iter(python::object const & a1, python::object const & a2); + + multi_iter make_multi_iter(python::object const & a1, python::object const & a2, python::object const & a3); + +:Returns: A Python iterator object broadcasting over one, two or three sequences as supplied + +accessors +--------- + +:: + + void next(); + +:Effects: Increments the iterator + +:: + + bool not_done() const; + +:Returns: boolean value indicating whether the iterator is at its end + +:: + + char * get_data(int n) const; + +:Returns: a pointer to the element of the nth broadcasted array. + +:: + + int const get_nd() const; + +:Returns: the number of dimensions of the broadcasted array expression + +:: + + Py_intptr_t const * get_shape() const; + +:Returns: the shape of the broadcasted array expression as an array of integers. + +:: + + Py_intptr_t const shape(int n) const; + +:Returns: the shape of the broadcasted array expression in the nth dimension. + + diff --git a/libs/numpy/doc/Reference/ndarray.rst b/libs/numpy/doc/Reference/ndarray.rst new file mode 100644 index 00000000..1adc0da4 --- /dev/null +++ b/libs/numpy/doc/Reference/ndarray.rst @@ -0,0 +1,383 @@ +ndarray +======= + +.. contents :: + +A `ndarray`_ is an N-dimensional array which contains items of the same type and size, where N is the number of dimensions and is specified in the form of a ``shape`` tuple. Optionally, the numpy ``dtype`` for the objects contained may also be specified. + +.. _ndarray: http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html +.. _dtype: http://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html#data-type-objects-dtype + + ```` contains the structures and methods necessary to move raw data between C++ and Python and create ndarrays from the data + + + +synopsis +-------- + +:: + + namespace boost + { + namespace numpy + { + + class ndarray : public python::object + { + + public: + + enum bitflag + { + NONE=0x0, C_CONTIGUOUS=0x1, F_CONTIGUOUS=0x2, V_CONTIGUOUS=0x1|0x2, + ALIGNED=0x4, WRITEABLE=0x8, BEHAVED=0x4|0x8, + CARRAY_RO=0x1|0x4, CARRAY=0x1|0x4|0x8, CARRAY_MIS=0x1|0x8, + FARRAY_RO=0x2|0x4, FARRAY=0x2|0x4|0x8, FARRAY_MIS=0x2|0x8, + UPDATE_ALL=0x1|0x2|0x4, VARRAY=0x1|0x2|0x8, ALL=0x1|0x2|0x4|0x8 + }; + + BOOST_PYTHON_FORWARD_OBJECT_CONSTRUCTORS(ndarray, object); + + ndarray view(dtype const & dt) const; + + ndarray copy() const; + + int const shape(int n) const { return get_shape()[n]; } + + int const strides(int n) const { return get_strides()[n]; } + + char * get_data() const { return get_struct()->data; } + + dtype get_dtype() const; + + python::object get_base() const; + + void set_base(object const & base); + + Py_intptr_t const * get_shape() const { return get_struct()->shape; } + + Py_intptr_t const * get_strides() const { return get_struct()->strides; } + + int const get_nd() const { return get_struct()->nd; } + + bitflag const get_flags() const; + + ndarray transpose() const; + + ndarray squeeze() const; + + ndarray reshape(python::tuple const & shape) const; + + python::object scalarize() const; + }; + + ndarray zeros(python::tuple const & shape, dtype const & dt); + ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt); + + ndarray empty(python::tuple const & shape, dtype const & dt); + ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt); + + ndarray array(python::object const & obj); + ndarray array(python::object const & obj, dtype const & dt); + + template + inline ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner); + + template + inline ndarray from_data(void const * data, dtype const & dt, Container shape, Container strides, python::object const & owner); + + ndarray from_object(python::object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE); + + inline ndarray from_object(python::object const & obj, dtype const & dt,int nd, ndarray::bitflag flags=ndarray::NONE); + + inline ndarray from_object(python::object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE); + + ndarray from_object(python::object const & obj, int nd_min, int nd_max,ndarray::bitflag flags=ndarray::NONE); + + inline ndarray from_object(python::object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE); + + inline ndarray from_object(python::object const & obj, ndarray::bitflag flags=ndarray::NONE) + + inline ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b) ; + + inline ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b); + + } // namespace boost::numpy + + +constructors +------------ + +:: + + ndarray view(dtype const & dt) const; + +:Returns: new ndarray with old ndarray data cast as supplied dtype + +:: + + ndarray copy() const; + +:Returns: Copy of calling ndarray object + +:: + + ndarray transpose() const; + +:Returns: An ndarray with the rows and columns interchanged + +:: + + ndarray squeeze() const; + +:Returns: An ndarray with all unit-shaped dimensions removed + +:: + + ndarray reshape(python::tuple const & shape) const; + +:Requirements: The new ``shape`` of the ndarray must be supplied as a tuple + +:Returns: An ndarray with the same data but reshaped to the ``shape`` supplied + + +:: + + python::object scalarize() const; + +:Returns: A scalar if the ndarray has only one element, otherwise it returns the entire array + +:: + + ndarray zeros(python::tuple const & shape, dtype const & dt); + ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt); + +:Requirements: The following parameters must be supplied as required : + * the ``shape`` or the size of all dimensions, as a tuple + * the ``dtype`` of the data + * the ``nd`` size for a square shaped ndarray + * the ``shape`` Py_intptr_t + +:Returns: A new ndarray with the given shape and data type, with data initialized to zero. + +:: + + ndarray empty(python::tuple const & shape, dtype const & dt); + ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt); + + +:Requirements: The following parameters must be supplied : + * the ``shape`` or the size of all dimensions, as a tuple + * the ``dtype`` of the data + * the ``shape`` Py_intptr_t + +:Returns: A new ndarray with the given shape and data type, with data left uninitialized. + +:: + + ndarray array(python::object const & obj); + ndarray array(python::object const & obj, dtype const & dt); + +:Returns: A new ndarray from an arbitrary Python sequence, with dtype of each element specified optionally + +:: + + template + inline ndarray from_data(void * data,dtype const & dt,Container shape,Container strides,python::object const & owner) + +:Requirements: The following parameters must be supplied : + * the ``data`` which is a generic C++ data container + * the dtype ``dt`` of the data + * the ``shape`` of the ndarray as Python object + * the ``strides`` of each dimension of the array as a Python object + * the ``owner`` of the data, in case it is not the ndarray itself + +:Returns: ndarray with attributes and data supplied + +:Note: The ``Container`` typename must be one that is convertible to a std::vector or python object type + +:: + + ndarray from_object(python::object const & obj, dtype const & dt,int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE); + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * the dtype ``dt`` of the data + * minimum number of dimensions ``nd_min`` of the ndarray as Python object + * maximum number of dimensions ``nd_max`` of the ndarray as Python object + * optional ``flags`` bitflags + +:Returns: ndarray constructed with dimensions and data supplied as parameters + +:: + + inline ndarray from_object(python::object const & obj, dtype const & dt, int nd, ndarray::bitflag flags=ndarray::NONE); + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * the dtype ``dt`` of the data + * number of dimensions ``nd`` of the ndarray as Python object + * optional ``flags`` bitflags + +:Returns: ndarray with dimensions ``nd`` x ``nd`` and suplied parameters + +:: + + inline ndarray from_object(python::object const & obj, dtype const & dt, ndarray::bitflag flags=ndarray::NONE) + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * the dtype ``dt`` of the data + * optional ``flags`` bitflags + +:Returns: Supplied Python object as ndarray + +:: + + ndarray from_object(python::object const & obj, int nd_min, int nd_max, ndarray::bitflag flags=ndarray::NONE); + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * minimum number of dimensions ``nd_min`` of the ndarray as Python object + * maximum number of dimensions ``nd_max`` of the ndarray as Python object + * optional ``flags`` bitflags + +:Returns: ndarray with supplied dimension limits and parameters + +:Note: dtype need not be supplied here + +:: + + inline ndarray from_object(python::object const & obj, int nd, ndarray::bitflag flags=ndarray::NONE); + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * the dtype ``dt`` of the data + * number of dimensions ``nd`` of the ndarray as Python object + * optional ``flags`` bitflags + +:Returns: ndarray of ``nd`` x ``nd`` dimensions constructed from the supplied object + +:: + + inline ndarray from_object(python::object const & obj, ndarray::bitflag flags=ndarray::NONE) + +:Requirements: The following parameters must be supplied : + * the ``obj`` Python object to convert to ndarray + * optional ``flags`` bitflags + +:Returns: ndarray of same dimensions and dtype as supplied Python object + + +accessors +--------- + +:: + + int const shape(int n) const { return get_shape()[n]; } + +:Returns: The size of the n-th dimension of the ndarray + +:: + + int const strides(int n) const { return get_strides()[n]; } + +:Returns: The stride of the nth dimension. + +:: + + char * get_data() const { return get_struct()->data; } + +:Returns: Array's raw data pointer as a char + +:Note: This returns char so stride math works properly on it.User will have to reinterpret_cast it. + +:: + + dtype get_dtype() const; + +:Returns: Array's data-type descriptor object (dtype) + + +:: + + python::object get_base() const; + +:Returns: Object that owns the array's data, or None if the array owns its own data. + + +:: + + void set_base(object const & base); + +:Returns: Set the object that owns the array's data. Exercise caution while using this + + +:: + + Py_intptr_t const * get_shape() const { return get_struct()->shape; } + +:Returns: Shape of the array as an array of integers + + +:: + + Py_intptr_t const * get_strides() const { return get_struct()->strides; } + +:Returns: Stride of the array as an array of integers + + +:: + + int const get_nd() const { return get_struct()->nd; } + +:Returns: Number of array dimensions + + +:: + + bitflag const get_flags() const; + +:Returns: Array flags + +:: + + inline ndarray::bitflag operator|(ndarray::bitflag a, ndarray::bitflag b) + +:Returns: bitflag logically OR-ed as (a | b) + +:: + + inline ndarray::bitflag operator&(ndarray::bitflag a, ndarray::bitflag b) + +:Returns: bitflag logically AND-ed as (a & b) + + +Example(s) +---------- + +:: + + p::object tu = p::make_tuple('a','b','c') ; + np::ndarray example_tuple = np::array (tu) ; + + p::list l ; + np::ndarray example_list = np::array (l) ; + + np::dtype dt = np::dtype::get_builtin(); + np::ndarray example_list1 = np::array (l,dt); + + int data[] = {1,2,3,4} ; + p::tuple shape = p::make_tuple(4) ; + p::tuple stride = p::make_tuple(4) ; + p::object own ; + np::ndarray data_ex = np::from_data(data,dt,shape,stride,own); + + uint8_t mul_data[][4] = {{1,2,3,4},{5,6,7,8},{1,3,5,7}}; + shape = p::make_tuple(3,2) ; + stride = p::make_tuple(4,2) ; + np::dtype dt1 = np::dtype::get_builtin(); + + np::ndarray mul_data_ex = np::from_data(mul_data,dt1, p::make_tuple(3,4),p::make_tuple(4,1),p::object()); + mul_data_ex = np::from_data(mul_data,dt1, shape,stride,p::object()); + diff --git a/libs/numpy/doc/Reference/unary_ufunc.rst b/libs/numpy/doc/Reference/unary_ufunc.rst new file mode 100644 index 00000000..84771706 --- /dev/null +++ b/libs/numpy/doc/Reference/unary_ufunc.rst @@ -0,0 +1,87 @@ +unary_ufunc +=========== + +.. contents :: + +A ``unary_ufunc`` is a struct used as an intermediate step to broadcast a single argument so that a C++ function can be converted to a ufunc like function + + ```` contains the ``unary_ufunc`` structure definitions + + +synopsis +-------- + +:: + + namespace boost + { + namespace numpy + { + + template + struct unary_ufunc + { + + static python::object call(TUnaryFunctor & self, python::object const & input, python::object const & output) ; + + static python::object make(); + + } + } + } + + +constructors +------------ + +:: + + struct example_unary_ufunc + { + typedef any_valid_type argument_type; + typedef any_valid_type result_type; + }; + +:Requirements: The ``any_valid`` type must be defined using typedef as a valid C++ type in order to use the struct methods correctly + +:Note: The struct must be exposed as a Python class, and an instance of the class must be created to use the ``call`` method corresponding to the ``__call__`` attribute of the Python object + +accessors +--------- + +:: + + template + static python::object call(TUnaryFunctor & self, python::object const & input, python::object const & output) ; + +:Requires: Typenames ``TUnaryFunctor`` and optionally ``TArgument`` for argument type and ``TResult`` for result type + +:Effects: Passes a Python object to the underlying C++ functor after broadcasting its arguments + +:: + + template + static python::object make(); + +:Requires: Typenames ``TUnaryFunctor`` and optionally ``TArgument`` for argument type and ``TResult`` for result type + +:Returns: A Python function object to call the overloaded () operator in the struct (in typical usage) + + + +Example(s) +---------- + +:: + + struct UnarySquare + { + typedef double argument_type; + typedef double result_type; + double operator()(double r) const { return r * r;} + }; + + p::object ud = p::class_ >("UnarySquare").def("__call__", np::unary_ufunc::make()); + p::object inst = ud(); + std::cout << "Square of unary scalar 1.0 is " << p::extract (p::str(inst.attr("__call__")(1.0))) << std::endl ; +