cntk.core module

Core numerical constructs.

class NDArrayView(shape, data_type, device=None)[source]

Bases: cntk.cntk_py.NDArrayView

Creates an empty dense internal data representation of a Value object. To create an NDArrayView from a NumPy array, use from_dense(). To create an NDArrayView from a sparse array, use from_csr().

Parameters:
  • shape (tuple) – shape of the data
  • data_type (np.float32, np.float64, np.float16) – data type of the data
  • device (DeviceDescriptor) – device this value should be put on
device

Retrieves the DeviceDescriptor instance.

dtype

NumPy data type of the instance

static from_csr(csr_array, device=None, read_only=False, borrow=False, shape=None)[source]

Create an NDArrayView instance from a SciPy sparse array in CSR format.

Parameters:
  • csr_array (scipy.sparse.csr_matrix) – SciPy sparse matrix in CSR format
  • device (DeviceDescriptor) – device this value should be put on
  • read_only (bool, optional) – whether the data can be modified or not (default False)
  • borrow (bool, default False) – whether nd_array memory can be borrowed internally to speed up the data creation
  • shape (tuple, default None) – shape of the created NDArrayView. If unspecified, the created NDArrayView has the same shape as the csr_matrix. Otherwise, an NDArrayView object of specified shape is created using csr_data. The total size and number of rows of csr_data must match specified NDArrayView shape.
Returns:

NDArrayView instance
static from_data(data, device=None, read_only=False, borrow=False)[source]

Create an NDArrayView instance from a NumPy or SciPy sparse array in CSR format.

Parameters:
  • data (numpy.ndarray or scipy.sparse.csr_matrix) – data
  • device (DeviceDescriptor) – device this value should be put on
  • read_only (bool, optional) – whether the data can be modified or not (default False)
  • borrow (bool, default False) – whether nd_array memory can be borrowed internally to speed up the data creation
Returns:

NDArrayView instance
static from_dense(np_array, device=None, read_only=False, borrow=False)[source]

Create an NDArrayView instance from a NumPy array.

Parameters:
  • np_array (numpy.ndarray) – NumPy array
  • device (DeviceDescriptor) – device this value should be put on
  • borrow (bool, default False) – whether nd_array memory can be borrowed internally to speed up the data creation
  • read_only (bool, optional) – whether the data can be modified or not (default False)
Returns:

NDArrayView instance
is_read_only

Whether the data is read-only

is_sparse

Whether the data is sparse or dense

shape

The shape of this instance.

slice_view(start_offset, extent, read_only=True)[source]

Returns a sliced view of the instance.

Example

>>> # Creating an array of shape (1, 1, 2, 3)
>>> np_array = np.asarray([[[[10, 20, 30], [40, 50, 60]]]],                                       dtype=np.float32)
>>> nd = NDArrayView.from_dense(np_array)
>>> sliced = nd.slice_view([0, 0, 0, 0], [2, 3])
>>> np_sliced = sliced.asarray()
>>> # Result is an array of shape (2, 3)
>>> print(np_sliced)
[[10. 20. 30.]
 [40. 50. 60.]]
Parameters:
  • start_offset (tuple or list) – shape of the same rank as this Value instance that denotes the start of the slicing
  • extent (tuple or list) – shape of the right-aligned extent to keep
  • read_only (bool) – whether the returned slice is read only or not
class Value(batch, seq_starts=None, device=None)[source]

Bases: cntk.cntk_py.Value

Internal representation of minibatch data.

Parameters:
  • batch –

    batch input for var. It can be:

    • a pure Python structure (list of lists, ...),
    • a list of NumPy arrays or SciPy sparse CSR matrices
    • a Value object (e.g. returned by one_hot())
  • seq_starts (list of bools or None) – if None, every sequence is treated as a new sequence. Otherwise, it is interpreted as a list of Booleans that tell whether a sequence is a new sequence (True) or a continuation of the sequence in the same slot of the previous minibatch (False)
  • device (DeviceDescriptor) – device this value should be put on
ONE_HOT_SKIP = 4294967295
as_sequences(variable=None)[source]

Convert a Value to a sequence of NumPy arrays that have their masked entries removed.

Returns:If variable contains more dynamic axes than the batch axis, a list of NumPy arrays (if dense) or a SciPy CSR array (if sparse) will be returned. Otherwise, the arrays will be returned directly.
static create(var, data, seq_starts=None, device=None, read_only=False)[source]

Creates a Value object.

Parameters:
  • var (Variable) – variable into which data is passed
  • data –

    data for var. It can be:

    • a single NumPy array denoting the full minibatch
    • a list of NumPy arrays or SciPy sparse CSR matrices
    • a single NumPy array denoting one parameter or constant
  • seq_starts (list of bools or None) – if None, every sequence is treated as a new sequence. Otherwise, it is interpreted as a list of Booleans that tell whether a sequence is a new sequence (True) or a continuation of the sequence in the same slot of the previous minibatch (False)
  • device (DeviceDescriptor, default None) – device this value should be put on
  • read_only (bool, default False) – whether the data is read only
Returns:

Value object.
data

Retrieves the underlying NDArrayView instance.

device

Retrieves the DeviceDescriptor instance.

dtype

NumPy data type of the instance

is_read_only

Whether the data is read-only

is_sparse

Whether the data is sparse or dense

is_valid

Whether the value is valid or has been invalidated by another forward and/or backward pass

mask

The mask matrix of this value. Each row denotes a sequence with its elements describing the mask of the element:

  • 2: beginning of sequence (e.g. an LSTM would be reset)
  • 1: valid element
  • 0: invalid element

Example

A mask of [[2, 1, 1], [1, 1, 0]] describes a batch of two sequences. The first has three elements, of which the first element (2) signals the beginning of a sequence. The second sequence has two elements (last element marked ‘invalid’ by ‘0’). As it starts with (1), it is a continuation of the 2nd sequence in the previous minibatch.

static one_hot(batch, num_classes, dtype=None, device=None)[source]

Converts batch into a Value object of dtype such that the integer data in batch is interpreted as the indices representing one-hot vectors. Use Value.ONE_HOT_SKIP for a zero vector

Example

>>> num_classes = 6
>>> sparse_indices = [[1,C.Value.ONE_HOT_SKIP,5],[4]]
>>> i0 = C.sequence.input_variable(shape=num_classes, is_sparse=True)
>>> z = C.times(i0, np.eye(num_classes))
>>> value = C.Value.one_hot(sparse_indices, num_classes)
>>> z.eval({i0: value})
[array([[0., 1., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0., 1.]], dtype=float32), array([[0., 0., 0., 0., 1., 0.]], dtype=float32)]
>>> num_classes = 6
>>> sample_shape = (2, num_classes)
>>> sparse_indices = [[1,5,3,2],[4,1]]
>>> i0 = C.sequence.input_variable(shape=sample_shape, is_sparse=True)
>>> z = C.times(i0, np.eye(num_classes))
>>> value = C.Value.one_hot(sparse_indices, sample_shape)
>>> z.eval({i0: value})
[array([[[ 0.,  1.,  0.,  0.,  0.,  0.],
         [ 0.,  0.,  0.,  0.,  0.,  1.]],
        [[ 0.,  0.,  0.,  1.,  0.,  0.],
         [ 0.,  0.,  1.,  0.,  0.,  0.]]], dtype=float32),
 array([[[ 0.,  0.,  0.,  0.,  1.,  0.],
         [ 0.,  1.,  0.,  0.,  0.,  0.]]], dtype=float32)]
>>> # this example has no sequence axis:
>>> num_classes = 6
>>> sample_shape = (num_classes,)
>>> sparse_indices = [1,5,3,2]
>>> i0 = C.input_variable(shape=sample_shape, is_sparse=True)
>>> z = C.times(i0, np.eye(num_classes))
>>> value = C.Value.one_hot(sparse_indices, sample_shape)
>>> z.eval({i0: value})
array([[ 0.,  1.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  1.],
       [ 0.,  0.,  0.,  1.,  0.,  0.],
       [ 0.,  0.,  1.,  0.,  0.,  0.]], dtype=float32)
Parameters:
  • batch (list of lists of integers) – batch input data of indices
  • sample_shape (int or tuple) – number of classes or shape of each sample whose trailing axis is one_hot
  • dtype (np.float32, np.float64, np.float16, default None) – data type
  • device (DeviceDescriptor, default None) – device this value should be put on
Returns:

batch converted into a Value object that can be passed to the forward or eval function.
shape

The rectangular shape of this value. I.e., if this value has sequences of varying lengths, the shape will have the max sequence length in the sequence dimension.

asarray(value, dtype=None)[source]

Converts a Value object to a sequence of NumPy arrays (if dense) or CSR arrays (if sparse).

asvalue(variable, data_array)[source]

Converts a sequence of NumPy arrays or CSR arrays to a Value object.

user_function(user_func)[source]

Wraps the passed Function to create a composite representing the composite Function graph rooted at the passed root Function.