mxnet
Classes | Public Member Functions | Static Public Member Functions | Friends | List of all members
mxnet::NDArray Class Reference

ndarray interface More...

#include <ndarray.h>

Collaboration diagram for mxnet::NDArray:
Collaboration graph

Public Member Functions

 NDArray ()
 default constructor More...
 
 NDArray (const mxnet::TShape &shape, Context ctx, bool delay_alloc=false, int dtype=mshadow::default_type_flag)
 constructs a new dynamic NDArray More...
 
 NDArray (const NDArrayStorageType stype, const mxnet::TShape &shape, Context ctx, bool delay_alloc=true, int dtype=mshadow::default_type_flag, std::vector< int > aux_types={}, mxnet::ShapeVector aux_shapes={}, mxnet::TShape storage_shape=mxnet::TShape(mshadow::Shape1(0)))
 constructor for NDArray with storage type More...
 
 NDArray (Context ctx, int dtype=mshadow::default_type_flag)
 constructs a new dynamic NDArray whose shape is unknown, hence the NDArray is inherently lazily created More...
 
 NDArray (const TBlob &data, int dev_id)
 constructing a static NDArray that shares data with TBlob Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray More...
 
 NDArray (const TBlob &data, int dev_id, const std::function< void()> &deleter)
 constructing a static NDArray that shares data with TBlob which is with deleter Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray More...
 
 NDArray (int shared_pid, int shared_id, const mxnet::TShape &shape, int dtype)
 create ndarray from shared memory More...
 
 NDArray (const NDArrayStorageType stype, const mxnet::TShape &shape, const TBlob &data, const std::vector< TBlob > &aux_data, int dev_id)
 constructing a static NDArray of non-default storage that shares data with TBlob Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray More...
 
void Init (const mxnet::TShape &shape)
 initialize the NDArray, assuming it is not assigned a meaningful shape before More...
 
void SetShapeFromChunk ()
 set the correct shape of NDArray directly from the storage_shape of its own chunk. More...
 
bool IsView () const
 
bool IsSame (const NDArray &other) const
 
const mxnet::TShapeshape () const
 
const mxnet::TShapestorage_shape () const
 
const mxnet::TShapeaux_shape (size_t index) const
 get the shape of aux_data(index) More...
 
const mxnet::ShapeVectoraux_shapes () const
 
const std::vector< int > & aux_types () const
 
void set_aux_shape (size_t index, const mxnet::TShape &shape) const
 For a sparse operation on a csr matrix for example, the size of the column index array is an estimated value in the beginning for allocating enough capacity for the final result. After the operation is done, the exact size of the shape is known and need to be reset using this function. More...
 
const TBlobdata () const
 
NDArray grad () const
 
TBlob aux_data (size_t i) const
 
Context ctx () const
 
int dtype () const
 
int aux_type (size_t i) const
 
NDArrayStorageType storage_type () const
 
bool is_none () const
 
bool fresh_out_grad () const
 
void set_fresh_out_grad (bool state) const
 
bool storage_initialized () const
 Returns true if a sparse ndarray's aux_data and storage are initialized Throws an exception if the indices array shape is inconsistent Returns false if the indices array is empty(nnz = 0) for csr/row_sparse. More...
 
Storage::Handle storage_handle () const
 get storage handle More...
 
void WaitToRead () const
 Block until all the pending write operations with respect to current NDArray are finished, and read can be performed. More...
 
void WaitToWrite () const
 Block until all the pending read/write operations with respect to current NDArray are finished, and write can be performed. More...
 
Engine::VarHandle var () const
 
size_t byte_offset () const
 
size_t version () const
 return var version of the NDArray More...
 
void Save (dmlc::Stream *strm) const
 save the content into binary stream More...
 
bool LegacyLoad (dmlc::Stream *strm, const uint32_t magic)
 load ndarrays before supporting sparse ndarrays More...
 
bool Load (dmlc::Stream *strm)
 load the content from binary stream More...
 
NDArrayoperator= (real_t scalar)
 set all the elements in ndarray to be scalar More...
 
NDArrayoperator+= (const NDArray &src)
 elementwise add to current space this mutate the current NDArray More...
 
NDArrayoperator+= (const real_t &src)
 elementwise add to current space this mutate the current NDArray More...
 
NDArrayoperator-= (const NDArray &src)
 elementwise subtract from current ndarray this mutate the current NDArray More...
 
NDArrayoperator-= (const real_t &src)
 elementwise subtract from current ndarray this mutate the current NDArray More...
 
NDArrayoperator*= (const NDArray &src)
 elementwise multiplication to current ndarray this mutate the current NDArray More...
 
NDArrayoperator*= (const real_t &src)
 elementwise multiplication to current ndarray this mutate the current NDArray More...
 
NDArrayoperator/= (const NDArray &src)
 elementwise division from current ndarray this mutate the current NDArray More...
 
NDArrayoperator/= (const real_t &src)
 elementwise division from current ndarray this mutate the current NDArray More...
 
NDArray Copy (Context ctx) const
 return a new copy this NDArray More...
 
void SyncCopyFromCPU (const void *data, size_t size) const
 Do a synchronize copy from a continugous CPU memory region. More...
 
void SyncCopyFromNDArray (const NDArray &src, int i=-1, int j=-1)
 Copy from src.data()/aux_data(i) to this->data()/aux_data(j) More...
 
void SyncCopyToCPU (void *data, size_t size) const
 Do a synchronize copy to a continugous CPU memory region. More...
 
void SyncCheckFormat (const bool full_check) const
 check whether the NDArray format is valid More...
 
NDArray Slice (index_t begin, index_t end) const
 Slice a NDArray. More...
 
NDArray SliceWithRecord (index_t begin, index_t end)
 Slice a NDArray. Supports recording with autograd. More...
 
NDArray At (index_t idx) const
 Index a NDArray. More...
 
NDArray AtWithRecord (index_t idx)
 Index a NDArray. More...
 
NDArray aux_ndarray (size_t i) const
 Generate a deep copy of aux_data(i) returned as a default storage type NDArray. More...
 
NDArray data_ndarray () const
 Generate a deep copy of data() returned as a default storage type NDArray. More...
 
NDArray AsArray (const mxnet::TShape &shape, int dtype) const
 Create a NDArray that shares memory with current one The new array must have smaller memory size than the current array. More...
 
DLManagedTensor * ToDLPack () const
 Create a reference view of NDArray that represents as DLManagedTensor. More...
 
void SparseUpdateChunk (const NDArray &arr) const
 Update ndarray chunk storage handles using existing ndarray storage handles Also update the aux_handle, aux_shapes and aux_types. This is specifically used for custom op to update the inputs and outputs from the temporary ndarray which stores intermediate custom op results. Should be used with caution elsewhere. Supports only CSR and RSP formats. More...
 
NDArray Reshape (const mxnet::TShape &shape) const
 Get an reshaped NDArray. More...
 
NDArray ReshapeWithRecord (const mxnet::TShape &shape)
 Get an reshaped NDArray. Supports autograd recording. More...
 
NDArray Detach () const
 Return a copy of this NDArray without autograd history. More...
 
nnvm::Symbol get_autograd_symbol () const
 
void CheckAndAlloc () const
 Allocate the space if it is delayed allocated. This is an internal function used by system that normal user should not use. More...
 
void ReshapeAndAlloc (const mxnet::TShape &shape)
 Allocate the space if the allocation has been delayed or the requested size is bigger than the available one. This function can only be called by ndarray of default storage type and effectively changes the ndarray's shape_. Note: This function is named as this to avoid overload conflict with CheckAndAlloc(const mxnet::ShapeVector &aux_shapes), since mxnet::TShape tmp = some_shape is equivalent to mxnet::TShape tmp = {some_shape}. More...
 
void CheckAndAlloc (const mxnet::ShapeVector &aux_shapes) const
 
void CheckAndAllocData (const mxnet::TShape &storage_shape) const
 
void CheckAndAllocAuxData (size_t i, const mxnet::TShape &aux_shape) const
 

Static Public Member Functions

static NDArray FromDLPack (const DLManagedTensor *tensor, bool transient_handle)
 Create a NDArray backed by a dlpack tensor. More...
 
static void Save (dmlc::Stream *fo, const std::vector< NDArray > &data, const std::vector< std::string > &names)
 Save list of ndarray into the Stream.x. More...
 
static void Load (dmlc::Stream *fi, std::vector< NDArray > *data, std::vector< std::string > *keys)
 Load list of ndarray into from the stream. More...
 

Friends

class Imperative
 

Detailed Description

ndarray interface

Constructor & Destructor Documentation

mxnet::NDArray::NDArray ( )
inline

default constructor

mxnet::NDArray::NDArray ( const mxnet::TShape shape,
Context  ctx,
bool  delay_alloc = false,
int  dtype = mshadow::default_type_flag 
)
inline

constructs a new dynamic NDArray

Parameters
shapethe shape of array
ctxcontext of NDArray
delay_allocwhether delay the allocation
dtypedata type of this ndarray
mxnet::NDArray::NDArray ( const NDArrayStorageType  stype,
const mxnet::TShape shape,
Context  ctx,
bool  delay_alloc = true,
int  dtype = mshadow::default_type_flag,
std::vector< int >  aux_types = {},
mxnet::ShapeVector  aux_shapes = {},
mxnet::TShape  storage_shape = mxnet::TShape(mshadow::Shape1(0)) 
)

constructor for NDArray with storage type

mxnet::NDArray::NDArray ( Context  ctx,
int  dtype = mshadow::default_type_flag 
)
inlineexplicit

constructs a new dynamic NDArray whose shape is unknown, hence the NDArray is inherently lazily created

Parameters
ctxcontext of NDArray
dtypedata type of this ndarray
mxnet::NDArray::NDArray ( const TBlob data,
int  dev_id 
)
inline

constructing a static NDArray that shares data with TBlob Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray

Parameters
datathe memory content of static data
dev_idthe device id this tensor sits at
mxnet::NDArray::NDArray ( const TBlob data,
int  dev_id,
const std::function< void()> &  deleter 
)
inline

constructing a static NDArray that shares data with TBlob which is with deleter Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray

Parameters
datathe memory content of static data
dev_idthe device id this tensor sits at
deleterthe function pointer of custom deleter
mxnet::NDArray::NDArray ( int  shared_pid,
int  shared_id,
const mxnet::TShape shape,
int  dtype 
)
inline

create ndarray from shared memory

mxnet::NDArray::NDArray ( const NDArrayStorageType  stype,
const mxnet::TShape shape,
const TBlob data,
const std::vector< TBlob > &  aux_data,
int  dev_id 
)
inline

constructing a static NDArray of non-default storage that shares data with TBlob Use with caution: allocate ONLY ONE NDArray for each TBlob, make sure the memory region is available through out the life of NDArray

Parameters
stypethe storage type of NDArray
shapethe shape of NDArray
datathe memory content of static data
aux_datathe memory content of static aux data
dev_idthe device id this tensor sits at

Member Function Documentation

NDArray mxnet::NDArray::AsArray ( const mxnet::TShape shape,
int  dtype 
) const
inline

Create a NDArray that shares memory with current one The new array must have smaller memory size than the current array.

Parameters
shapenew shape
dtypeThe data type.
Returns
NDArray in new shape and type.
NDArray mxnet::NDArray::At ( index_t  idx) const

Index a NDArray.

Parameters
idxthe index
Returns
idx-th sub array NDArray
NDArray mxnet::NDArray::AtWithRecord ( index_t  idx)

Index a NDArray.

Parameters
idxthe index
Returns
idx-th sub array NDArray
TBlob mxnet::NDArray::aux_data ( size_t  i) const
inline
Returns
the aux TBlob
NDArray mxnet::NDArray::aux_ndarray ( size_t  i) const

Generate a deep copy of aux_data(i) returned as a default storage type NDArray.

const mxnet::TShape& mxnet::NDArray::aux_shape ( size_t  index) const
inline

get the shape of aux_data(index)

Parameters
indexthe index of the aux data
Returns
the shape of aux data at given index
const mxnet::ShapeVector& mxnet::NDArray::aux_shapes ( ) const
inline
int mxnet::NDArray::aux_type ( size_t  i) const
inline
const std::vector<int>& mxnet::NDArray::aux_types ( ) const
inline

returns the dtypes of all aux data

size_t mxnet::NDArray::byte_offset ( ) const
inline
Returns
byte offset in chunk of the ndarray
void mxnet::NDArray::CheckAndAlloc ( ) const
inline

Allocate the space if it is delayed allocated. This is an internal function used by system that normal user should not use.

void mxnet::NDArray::CheckAndAlloc ( const mxnet::ShapeVector aux_shapes) const
inline
void mxnet::NDArray::CheckAndAllocAuxData ( size_t  i,
const mxnet::TShape aux_shape 
) const
inline
void mxnet::NDArray::CheckAndAllocData ( const mxnet::TShape storage_shape) const
inline
NDArray mxnet::NDArray::Copy ( Context  ctx) const

return a new copy this NDArray

Parameters
ctxthe new context of this NDArray
Returns
the new copy
Context mxnet::NDArray::ctx ( ) const
inline
Returns
the context of NDArray, this function is only valid when the NDArray is not empty
const TBlob& mxnet::NDArray::data ( ) const
inline
Returns
the data TBlob
NDArray mxnet::NDArray::data_ndarray ( ) const

Generate a deep copy of data() returned as a default storage type NDArray.

NDArray mxnet::NDArray::Detach ( ) const
inline

Return a copy of this NDArray without autograd history.

int mxnet::NDArray::dtype ( ) const
inline
Returns
the data type of NDArray, this function is only valid when the NDArray is not empty
bool mxnet::NDArray::fresh_out_grad ( ) const
Returns
updated grad state in entry_
static NDArray mxnet::NDArray::FromDLPack ( const DLManagedTensor *  tensor,
bool  transient_handle 
)
static

Create a NDArray backed by a dlpack tensor.

This allows us to create a NDArray using the memory allocated by an external deep learning framework that is DLPack compatible.

The memory is retained until the NDArray went out of scope.

Returns
The created NDArray view.
nnvm::Symbol mxnet::NDArray::get_autograd_symbol ( ) const
NDArray mxnet::NDArray::grad ( ) const
Returns
the gradient ndarray.
void mxnet::NDArray::Init ( const mxnet::TShape shape)
inline

initialize the NDArray, assuming it is not assigned a meaningful shape before

Parameters
shapethe shape of the NDArray
bool mxnet::NDArray::is_none ( ) const
inline
Returns
whether this ndarray is not initialized
bool mxnet::NDArray::IsSame ( const NDArray other) const
inline
bool mxnet::NDArray::IsView ( ) const
inline
bool mxnet::NDArray::LegacyLoad ( dmlc::Stream *  strm,
const uint32_t  magic 
)

load ndarrays before supporting sparse ndarrays

Parameters
strmthe output stream
magicthe magic number used for version control
bool mxnet::NDArray::Load ( dmlc::Stream *  strm)

load the content from binary stream

Parameters
strmthe output stream
Returns
whether the load is successful
static void mxnet::NDArray::Load ( dmlc::Stream *  fi,
std::vector< NDArray > *  data,
std::vector< std::string > *  keys 
)
static

Load list of ndarray into from the stream.

Parameters
fiThe stream of the input file.
datathe NDArrays to be loaded
keysthe name of the NDArray, if saved in the file.
NDArray& mxnet::NDArray::operator*= ( const NDArray src)

elementwise multiplication to current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator*= ( const real_t src)

elementwise multiplication to current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator+= ( const NDArray src)

elementwise add to current space this mutate the current NDArray

Parameters
srcthe data to add
Returns
reference of self
NDArray& mxnet::NDArray::operator+= ( const real_t src)

elementwise add to current space this mutate the current NDArray

Parameters
srcthe data to add
Returns
reference of self
NDArray& mxnet::NDArray::operator-= ( const NDArray src)

elementwise subtract from current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator-= ( const real_t src)

elementwise subtract from current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator/= ( const NDArray src)

elementwise division from current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator/= ( const real_t src)

elementwise division from current ndarray this mutate the current NDArray

Parameters
srcthe data to subtract
Returns
reference of self
NDArray& mxnet::NDArray::operator= ( real_t  scalar)

set all the elements in ndarray to be scalar

Parameters
scalarthe scalar to set
Returns
reference of self
NDArray mxnet::NDArray::Reshape ( const mxnet::TShape shape) const

Get an reshaped NDArray.

Parameters
shapenew shape
Returns
NDArray in new shape
void mxnet::NDArray::ReshapeAndAlloc ( const mxnet::TShape shape)
inline

Allocate the space if the allocation has been delayed or the requested size is bigger than the available one. This function can only be called by ndarray of default storage type and effectively changes the ndarray's shape_. Note: This function is named as this to avoid overload conflict with CheckAndAlloc(const mxnet::ShapeVector &aux_shapes), since mxnet::TShape tmp = some_shape is equivalent to mxnet::TShape tmp = {some_shape}.

NDArray mxnet::NDArray::ReshapeWithRecord ( const mxnet::TShape shape)

Get an reshaped NDArray. Supports autograd recording.

Parameters
shapenew shape
Returns
NDArray in new shape
void mxnet::NDArray::Save ( dmlc::Stream *  strm) const

save the content into binary stream

Parameters
strmthe output stream
static void mxnet::NDArray::Save ( dmlc::Stream *  fo,
const std::vector< NDArray > &  data,
const std::vector< std::string > &  names 
)
static

Save list of ndarray into the Stream.x.

Parameters
foThe stream of output.
datathe NDArrays to be saved.
namesthe name of the NDArray, optional, can be zero length.
void mxnet::NDArray::set_aux_shape ( size_t  index,
const mxnet::TShape shape 
) const
inline

For a sparse operation on a csr matrix for example, the size of the column index array is an estimated value in the beginning for allocating enough capacity for the final result. After the operation is done, the exact size of the shape is known and need to be reset using this function.

void mxnet::NDArray::set_fresh_out_grad ( bool  state) const
Returns
updated grad state in entry_
void mxnet::NDArray::SetShapeFromChunk ( )
inline

set the correct shape of NDArray directly from the storage_shape of its own chunk.

const mxnet::TShape& mxnet::NDArray::shape ( ) const
inline
Returns
the shape of current NDArray.
NDArray mxnet::NDArray::Slice ( index_t  begin,
index_t  end 
) const

Slice a NDArray.

Parameters
beginbegin index in first dim (inclusive)
endend index in first dim (exclusive)
Returns
sliced NDArray
NDArray mxnet::NDArray::SliceWithRecord ( index_t  begin,
index_t  end 
)

Slice a NDArray. Supports recording with autograd.

Parameters
beginbegin index in first dim (inclusive)
endend index in first dim (exclusive)
Returns
sliced NDArray
void mxnet::NDArray::SparseUpdateChunk ( const NDArray arr) const
inline

Update ndarray chunk storage handles using existing ndarray storage handles Also update the aux_handle, aux_shapes and aux_types. This is specifically used for custom op to update the inputs and outputs from the temporary ndarray which stores intermediate custom op results. Should be used with caution elsewhere. Supports only CSR and RSP formats.

Storage::Handle mxnet::NDArray::storage_handle ( ) const
inline

get storage handle

bool mxnet::NDArray::storage_initialized ( ) const
inline

Returns true if a sparse ndarray's aux_data and storage are initialized Throws an exception if the indices array shape is inconsistent Returns false if the indices array is empty(nnz = 0) for csr/row_sparse.

const mxnet::TShape& mxnet::NDArray::storage_shape ( ) const
inline
Returns
the shape of underlying chunk which stores the NDArray data/value. It is only intended for non-default storage. For row-sparse storage, it is the shape of the tensor which stores the non-zero values.
NDArrayStorageType mxnet::NDArray::storage_type ( ) const
inline
void mxnet::NDArray::SyncCheckFormat ( const bool  full_check) const

check whether the NDArray format is valid

Parameters
full_checkif True, rigorous check, O(N) operations Otherwise basic check, O(1) operations
void mxnet::NDArray::SyncCopyFromCPU ( const void *  data,
size_t  size 
) const

Do a synchronize copy from a continugous CPU memory region.

This function will call WaitToWrite before the copy is performed. This is useful to copy data from existing memory region that are not wrapped by NDArray(thus dependency not being tracked).

Parameters
datathe data source to copy from.
sizethe size of the source array, in sizeof(DType) not raw btyes.
void mxnet::NDArray::SyncCopyFromNDArray ( const NDArray src,
int  i = -1,
int  j = -1 
)

Copy from src.data()/aux_data(i) to this->data()/aux_data(j)

void mxnet::NDArray::SyncCopyToCPU ( void *  data,
size_t  size 
) const

Do a synchronize copy to a continugous CPU memory region.

This function will call WaitToRead before the copy is performed. This is useful to copy data from existing memory region that are not wrapped by NDArray(thus dependency not being tracked).

Parameters
datathe data source to copyinto.
sizethe memory size we want to copy into, in sizeof(DType) not raw btyes.
DLManagedTensor* mxnet::NDArray::ToDLPack ( ) const

Create a reference view of NDArray that represents as DLManagedTensor.

Returns
A DLManagedTensor
Engine::VarHandle mxnet::NDArray::var ( ) const
inline
Returns
the associated variable of the ndarray.
size_t mxnet::NDArray::version ( ) const
inline

return var version of the NDArray

void mxnet::NDArray::WaitToRead ( ) const
inline

Block until all the pending write operations with respect to current NDArray are finished, and read can be performed.

void mxnet::NDArray::WaitToWrite ( ) const
inline

Block until all the pending read/write operations with respect to current NDArray are finished, and write can be performed.

Push an empty mutable function to flush all preceding reads to the variable.

Friends And Related Function Documentation

friend class Imperative
friend

The documentation for this class was generated from the following file: