User Guide

You can build a new bob.blitz.array using one of two possible ways:

1. Use the array constructor:

   >>> bob.blitz.array((2,3), float)
   bob.blitz.array((2,3),'float64')
   

You should pass the array shape and a dtype convertible object that would identify the type of elements the array will contain. Arrays built this way are uninitialized:

>>> a = bob.blitz.array((2,), 'uint8')
>>> a[0] 
145

2. Use the bob.blitz.as_blitz() generic converter. This function takes any object that is convertible to a numpy.ndarray, convert it to a behaved (C-order, memory aligned and contiguous) numpy.ndarray and then shallow copy it as a new bob.blitz.array:

   >>> import bob.blitz
   >>> a = bob.blitz.as_blitz(range(5))
   >>> print(a)
   [0 1 2 3 4]
   >>> a.dtype
   dtype('int...')
   

   The shallow copied ndarray remains visible through the returned object’s base attribute:

   >>> a.base
   array([0, 1, 2, 3, 4])
   >>> type(a.base)
   <... 'numpy.ndarray'>
   

   Because this is a shallow copy, any modifications done in any of the two arrays will be reflected in the other:

   >>> a.base[3] = 67
   >>> print(a)
   [ 0  1  2 67  4]
   

You can get and set the individual values on bob.blitz.array objects, using the normal python indexing operatiors []:

>>> a = bob.blitz.array(2, 'float64')
>>> a[0] = 3.2
>>> a[1] = 6.14
>>> print(a)
[ 3.2   6.14]
>>> t = a[1]
>>> print(t)
6.14

You can convert bob.blitz.array objects into either (shallow) numpy.ndarray copies using bob.blitz.array.as_ndarray().

>>> a = bob.blitz.array(2, complex)
>>> a[0] = complex(3,4)
>>> a[1] = complex(2,2)
>>> npy = a.as_ndarray()
>>> print(npy)
[ 3.+4.j  2.+2.j]
>>> id(npy.base) == id(a)
True
>>> print(npy.flags.owndata)
False

You can detach the numpy.ndarray from the bob.blitz.array, by issuing a standard numpy copy:

>>> npy_copy = npy.copy()
>>> npy_copy.base is None
True
>>> print(npy_copy.flags.owndata)
True

You can use bob.blitz.array anywhere a numpy.ndarray is expected. In this case, numpy checks for the existence of an __array__ method on the passed object and if that is available, calls it to get an array representation for the object. For bob.blitz.array, the bob.blitz.array.__array__() method chooses the fastest possible conversion path to generate a numpy.ndarray.

>>> a = bob.blitz.array(2, float)
>>> a[0] = 3
>>> a[1] = 4
>>> print(numpy.mean(a))
3.5

Reference

This section includes information for using the pure Python API of bob.blitz.array. It is mainly intended as a test layer for the C and C++ API.

class bob.blitz.array

Bases: object

array(shape, dtype) -> new n-dimensional blitz::Array

An N-dimensional blitz::Array<T,N> pythonic representation

Constructor parameters:

shape

An iterable, indicating the shape of the array to be constructed

The implementation current supports a maximum of 4 dimensions. Building an array with more dimensions will raise a TypeError. There are no explicit limits for the size in each dimension, except for the machine’s maximum address size.

dtype

A numpy.dtype or dtype convertible object that specified the type of elements in this array.

The following numpy data types are supported by this library:

• numpy.bool_
• numpy.int8
• numpy.int16
• numpy.int32
• numpy.int64
• numpy.uint8
• numpy.uint16
• numpy.uint32
• numpy.uint64
• numpy.float32
• numpy.float64
• numpy.float128 (if this architecture suppports it)
• numpy.complex64
• numpy.complex128
• numpy.complex256 (if this architecture suppports it)

Objects of this class hold a pointer to C++ blitz::Array<T,N>. The C++ data type T is mapped to a numpy.dtype object, while the extents and number of dimensions N are mapped to a shape, similar to what is done for numpy.ndarray objects.

Objects of this class can be wrapped in numpy.ndarray quite efficiently, so that flexible numpy-like operations are possible on its contents. You can also deploy objects of this class wherever numpy.ndarray‘s may be input.

__array__([dtype]) → numpy.ndarray

x.as_ndarray([dtype]) -> numpy.ndarray

numpy.ndarray accessor (shallow wraps bob.blitz.array as numpy.ndarray). If dtype is given and the current data type is not the same, then forces the creation of a copy conforming to the require data type, if possible.

as_ndarray()

x.__array__([dtype]) -> numpy.ndarray x.as_ndarray([dtype]) -> numpy.ndarray

numpy.ndarray accessor (shallow wraps bob.blitz.array as numpy.ndarray). If dtype is given and the current data type is not the same, then forces the creation of a copy conforming to the require data type, if possible.

base

If the memory of this array is borrowed from some other object, this is it

cast(dtype) → blitz array

Casts an existing array into a (possibly) different data type, without changing its shape. If the data type matches the current array’s data type, then a new view to the same array is returned. Otherwise, a new array is allocated and returned.

dtype

The numpy.dtype for every element in this array

shape

A tuple indicating the shape of this array (in elements)

stride

A tuple indicating the strides of this array (in bytes)

writeable

A flag, indicating if this array is writeable

bob.blitz.as_blitz(x) → bob.blitz.array

Converts any compatible python object into a shallow bob.blitz.array

This function works by first converting the input object x into a numpy.ndarray and then shallow wrapping that ndarray into a new bob.blitz.array. You can access the converted ndarray using the returned value’s base attribute. If the ndarray cannot be shallow-wrapped, a ValueError is raised.

In the case the input object x is already a behaved (C-style, memory-aligned, contiguous) numpy.ndarray, then this function only shallow wrap’s it into a bob.blitz.array skin.