/ 
AI-MXNet-1.33
River stage one • 2 direct dependents • 2 total dependents
/ AI::MXNet::NDArray

NAME

AI::MXNet::NDArray - Multidimensional tensor object of MXNet.

DESCRIPTION

AI::MXNet::NDArray - Imperative tensor operations on CPU/GPU
In AI::MXNet, NDArray is the core data structure for all mathematical computations.
An NDArray represents a multidimensional, fixed-size homogenous array.
If you're familiar with the PDL, you might notice some similarities.
However, NDArray is row-major, unlike the PDL that is column-major.
Like the PDL, MXNet’s NDArray enables imperative computation.

Some NDArray advandages compared to PDL:
MXNet's NDArray supports fast execution on a wide range of hardware configurations, including CPU, GPU, and multi-GPU machines.
MXNet also scales to distributed systems in the cloud.
MXNet's NDArray executes code lazily, allowing it to automatically parallelize multiple operations across the available hardware.

An NDArray is a multidimensional array of numbers with the same type.
We could represent the coordinates of a point in 3D space, e.g. [2, 1, 6] as a 1D array with shape (3).
Similarly, we could represent a 2D array.
Below, we present an array with length 2 along the first axis and length 3 along the second axis.

[[0, 1, 2]
 [3, 4, 5]]
Note that here the use of 'dimension' is overloaded. When we say a 2D array, we mean an array with 2 axes, not an array with two components.

Each NDArray supports some important attributes that you'll often want to query:

$ndarray->shape: The dimensions of the array.
It is an array ref of integers indicating the length of the array along each axis.
For a matrix with $n rows and $m columns, its shape will be [$n, $m].
$ndarray->dtype: A string describing the type of its elements.
Dtype (defined in AI::MXNet::Types) is one of (float32 float64 float16 uint8 int8 int32 int64)
$ndarray->size: The total number of components in the array - equal to the product of the components of its shape.
$ndarray->context: The device on which this array is stored, represented by an object of AI::MXNet::Context class, e.g. cpu() or gpu(1).

aspdl

Returns a copied PDL array of current array.

Returns
-------
array : PDL
    A copy of the array content.

asmpdl

Returns copied PDL::Matrix objectt of current array.

Requires caller to "use PDL::Matrix" in user space.

Returns
-------
array : PDL::Matrix
    A copy of array content.

_slice

Returns sliced NDArray that shares memory with the current one.

Parameters
----------
start : int
    Starting index of slice.
stop : int
    Finishing index of slice.

_at

Returns a sub NDArray that shares memory with current one.

Parameters
----------
idx : int
    index of the sub array.

reshape

Returns a **view** of this array with a new shape without altering any data.
One shape dimension can be -1. In this case, the value is inferred
from the length of the array and remaining dimensions.

Parameters
----------
$new_shape : Shape
    new shape of NDArray
:$reverse : bool, default 0
    If true then the special values are inferred from right to left.

ndim

Returns the number of dimensions of this array.

moveaxis

Moves the 'source' axis into the 'destination' position
while leaving the other axes in their original order

Parameters
----------
source : int
    Original position of the axes to move.
destination : int
    Destination position for each of the original axes.

Returns
-------
result :NDArray
Array with moved axes.

Examples
--------
> $X = mx->nd->array([[1, 2, 3],
                      [4, 5, 6]]);
> print Dumper($X->moveaxis(0, 1)->shape)
> [3, 2]

broadcast_to

Broadcasting the current NDArray into the given shape.

Parameters
---------
Shape $shape : the shape to broadcast

wait_to_read

Block until all pending write operations on the NDArray are finished.

This function will return when all the pending writes to the current
NDArray are finished. There can be pending reads going on when the
function returns.

shape

Get the shape of current NDArray.

Returns
-------
an array ref representing the shape of current ndarray

size

Number of elements in the array.

context

The context of the NDArray.

Returns
-------
$context : AI::MXNet::Context

dtype

The data type of current NDArray.

Returns
-------
a data type string ('float32', 'float64', 'float16', 'uint8', 'int32')
representing the data type of the ndarray.
'float32' is the default dtype for the ndarray class.

copyto

Copy the content of current array to another entity.

When another entity is the NDArray, the content is copied over.
When another entity is AI::MXNet::Context, a new NDArray in the context
will be created.

Parameters
----------
other : NDArray or Context
    Target NDArray or context we want to copy data to.

Returns
-------
dst : NDArray

copy

Makes a copy of the current ndarray in the same context

Returns
------
$copy : NDArray

T

Get transpose of the NDArray.
Works only on 2-D matrices.

astype

Returns copied ndarray of current array with the specified type.

Parameters
----------
$dtype : Dtype

Returns
-------
$array : ndarray
    A copy of the array content.

as_in_context

Returns an NDArray in the target context.
If the array is already in that context, self is returned. Otherwise, a copy is
made.

Parameters
----------
context : AI::MXNet::Context
    The target context we want the return value to live in.

Returns
-------
    A copy or self as an NDArray in the target context.

onehot_encode

One hot encoding indices into matrix out.

Parameters
----------
indices: NDArray
    An NDArray containing indices of the categorical features.

out: NDArray
    The result of the encoding.

Returns
-------
    $out: NDArray

empty

Creates an empty uninitialized NDArray, with the specified shape.

Parameters
----------
$shape : Shape
    shape of the NDArray.

:$ctx : AI::MXNet::Context, optional
    The context of the NDArray, defaults to current default context.

:$dtype : Dtype, optional
    The dtype of the NDArray, defaults to 'float32'.

:$stype: Stype, optional
    The stype of the NDArray, defaults to 'default'

Returns
-------
out: Array
    The created NDArray.

zeros

Creates a new NDArray filled with 0, with specified shape.

Parameters
----------
$shape : Shape
    shape of the NDArray.

:$ctx : AI::MXNet::Context, optional
    The context of the NDArray, defaults to current default context.

:$dtype : Dtype, optional
    The dtype of the NDArray, defaults to 'float32'.

:$stype: Stype, optional
    The stype of the NDArray, defaults to 'default'
Returns
-------
out: Array
    The created NDArray.

ones

Creates a new NDArray filled with 1, with specified shape.

Parameters
----------
$shape : Shape
    shape of the NDArray.

:$ctx : AI::MXNet::Context, optional
    The context of the NDArray, defaults to current default context.

:$dtype : Dtype, optional
    The dtype of the NDArray, defaults to 'float32'.

Returns
-------
out: Array
    The created NDArray.

full

Creates a new NDArray filled with given value, with specified shape.

Parameters
----------
$shape : Shape
    shape of the NDArray.

val : float or int
    The value to be filled with.

:$ctx : AI::MXNet::Context, optional
    The context of the NDArray, defaults to current default context.

:$dtype : Dtype, optional
    The dtype of the NDArray, defaults to 'float32'.

Returns
-------
out: Array
    The created NDArray.

array

Creates a new NDArray that is a copy of the source_array.

Parameters
----------
$source_array : AI::MXNet::NDArray PDL, PDL::Matrix, Array ref in PDL::pdl format
    Source data to create NDArray from.

:$ctx : AI::MXNet::Context, optional
    The context of the NDArray, defaults to current default context.

:$dtype : Dtype, optional
    The dtype of the NDArray, defaults to 'float32'.

Returns
-------
out: Array
    The created NDArray.

concatenate

Concatenates an array ref of NDArrays along the first dimension.

Parameters
----------
$arrays :  array ref of NDArrays
    Arrays to be concatenate. They must have identical shape except
    for the first dimension. They also must have the same data type.
:$axis=0 : int
    The axis along which to concatenate.
:$always_copy=1 : bool
    Default is 1. When not 1, if the arrays only contain one
    NDArray, that element will be returned directly, avoid copying.

Returns
-------
An NDArray in the same context as $arrays->[0]->context.

arange

Similar function in the MXNet ndarray as numpy.arange
See Also https://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html.

Parameters
----------
:$start=0 : number, optional
    Start of interval. The interval includes this value. The default start value is 0.
:$stop= : number, optional
    End of interval. The interval does not include this value.
:$step=1 : number, optional
    Spacing between the values
:$repeat=1 : number, optional
    The repeating time of all elements.
    E.g repeat=3, the element a will be repeated three times --> a, a, a.
:$ctx : Context, optional
    The context of the NDArray, defaultw to current default context.
:$dtype : data type, optional
    The value type of the NDArray, defaults to float32

Returns
-------
$out : NDArray
    The created NDArray

load

Loads ndarrays from a binary file.

You can also use Storable to do the job if you only work with Perl.
The advantage of load/save is the file is language agnostic.
This means the file saved using save can be loaded by other language binding of mxnet.
You also get the benefit being able to directly load/save from cloud storage(S3, HDFS)

Parameters
----------
fname : str
    The name of the file.Can be S3 or HDFS address (remember built with S3 support).
    Example of fname:

    - `s3://my-bucket/path/my-s3-ndarray`
    - `hdfs://my-bucket/path/my-hdfs-ndarray`
    - `/path-to/my-local-ndarray`

Returns
-------
$out : array ref of NDArrays or hash ref with NDArrays

load_frombuffer

Loads an array dictionary or list from a buffer

See more details in 'save'.

Parameters
----------
buf : str
    Binary string containing contents of a file.

Returns
-------
array ref of AI::MXNet::NDArray, AI::MXNet::NDArrayRowSparseNDArray or AI::MXNet::NDArray::CSR, or
hash ref of AI::MXNet::NDArray, AI::MXNet::NDArrayRowSparseNDArray or AI::MXNet::NDArray::CSR
    Loaded data.

save

Save array ref of NDArray or hash of str->NDArray to a binary file.

You can also use Storable to do the job if you only work with Perl.
The advantage of load/save is the file is language agnostic.
This means the file saved using save can be loaded by other language binding of mxnet.
You also get the benefit being able to directly load/save from cloud storage(S3, HDFS)

Parameters
----------
fname : str
    The name of the file.Can be S3 or HDFS address (remember built with S3 support).
    Example of fname:

    - `s3://my-bucket/path/my-s3-ndarray`
    - `hdfs://my-bucket/path/my-hdfs-ndarray`
    - `/path-to/my-local-ndarray`

$data : array ref of NDArrays or hash ref of NDArrays
    The data to be saved.

imdecode

Decode an image from string. Requires OpenCV to work.

Parameters
----------
$str_img : str
    binary image data
:$clip_rect : iterable of 4 int
    clip decoded image to rectangle (x0, y0, x1, y1)
:$out= : Maybe[NDArray]
    output buffer. can be 3 dimensional (c, h, w) or 4 dimensional (n, c, h, w)
:$index : int
    output decoded image to i-th slice of 4 dimensional buffer
:$channels=3 : int
    number of channels to output. Decode to grey scale when channels = 1.
$mean= : Maybe[NDArray]
    subtract mean from decode image before outputting.

_new_empty_handle

Returns a new empty handle.

Empty handle can be used to hold result

Returns
-------
    a new empty ndarray handle

_new_alloc_handle

Returns a new handle with specified shape and context.

Empty handle is only used to hold results

Returns
-------
a new empty ndarray handle

tostype

Return a copy of the array with chosen storage type.

Returns
-------
AI::MXNet::NDArray or AI::MXNet::NDArray::CSR or AI::MXNet::NDArray::RowSparse
    A copy of the array with the chosen storage stype

waitall

Wait for all async operations to finish in MXNet.
This function is used for benchmarks only.

_fresh_grad

Parameters:
----------
Maybe[Bool] $state=

Whether this array's corresponding gradient array
(registered via `autograd->mark_variables`) has been
updated by `autograd->backward` since last reset.

`_fresh_grad` need to be manually set to False
after consuming gradient (usually after updating this
array).

detach

Returns a new NDArray, detached from the current graph.

attach_grad

Attach a gradient buffer to this NDArray, so that `backward`
can compute gradient with respect to it.

Parameters
----------
GradReq :$grad_req='write' : {'write', 'add', 'null'}
    How gradient will be accumulated.
    - 'write': gradient will be overwritten on every backward.
    - 'add': gradient will be added to existing value on every backward.
    - 'null': do not compute gradient for this NDArray.
Maybe[Str] :$stype= : str, optional
    The storage type of the gradient array. Defaults to the same stype of this NDArray.

grad

Returns gradient buffer attached to this NDArray.

backward

Compute the gradients of this NDArray w.r.t variables.

Parameters
----------
:$out_grad= : NDArray, optional
    Gradient with respect to head.
:$retain_graph=0 : bool, optional
    Whether to retain the computaion graph for another backward
    pass on the same graph. By default the computaion history
    is cleared.
:$train_mode=1 : bool, optional
    Whether to compute gradient for training or inference.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 32:

Non-ASCII character seen before =encoding in 'MXNet’s'. Assuming UTF-8