Package ai.djl.ndarray

Interface NDManager

  • All Superinterfaces:
    java.lang.AutoCloseable
    All Known Implementing Classes:
    BaseNDManager
    public interface NDManager
extends java.lang.AutoCloseable
    NDArray managers are used to create NDArrays (n-dimensional array on native engine).

    NDManager is implemented in each deep learning Engine. NDArrays are resources that are allocated in each deep learning engine's native memory space. NDManager is the key class that manages these native resources.

    NDArray can only be created through NDManager. By default, NDArray's lifecycle is attached to the creator NDManager. NDManager itself implements AutoCloseable. When NDManager is closed, all the resource associated with it will be closed as well.

    A typical place to obtain NDManager is in PreProcessor.processInput(TranslatorContext, Object) or PostProcessor.processOutput(TranslatorContext, NDList).

    The following is an example of how to use NDManager: 

     public class MyTranslator implements Translator<FloatBuffer, String> {

     @Override
     public NDList processInput(TranslatorContext ctx, FloatBuffer input) {
         NDManager manager = ctx.getNDManager();
         NDArray array = manager.create(shape);
         array.set(input);
         return new NDList(array);
     } // NDArrays created in this method will be closed after method return.
 }

    NDManager has a hierarchical structure; it has a single parent NDManager and has child NDManagers. When the parent NDManager is closed, all children will be closed as well.

    The DJL engine manages NDManager's lifecycle by default. You only need to manage the user created child NDManager. The child NDManager becomes useful when you create a large number of temporary NDArrays and want to free the resources earlier than the parent NDManager's lifecycle.

    The following is an example of such a use case: 

     public class MyTranslator implements Translator<List<FloatBuffer>>, String> {

     @Override
     public NDList processInput(TranslatorContext ctx, List<FloatBuffer> input) {
         NDManager manager = ctx.getNDManager();
         NDArray array = manager.create(shape, dataType);
         for (int i = 0; i < input.size(); ++i) {
             try (NDManager childManager = manager.newSubManager()) {
                  NDArray tmp = childManager.create(itemShape);
                  tmp.put(input.get(i);
                  array.put(i, tmp);
             } // NDArray tmp will be closed here
         }
         return new NDList(array);
     }
 }

    You can also close an individual NDArray. NDManager won't close an NDArray that's already been closed. In certain use cases, you might want to return an NDArray outside of NDManager's scope.

    See Also:
    NDArray, Translator, TranslatorContext.getNDManager(), NDArray Memory Management Guide

    • Method Detail

      • newBaseManager

        static NDManager newBaseManager()
        Creates a new top-level NDManager.

        NDManager will inherit default Device.

        Returns:
        a new top-level NDManager

      • newBaseManager

        static NDManager newBaseManager​(Device device)
        Creates a new top-level NDManager with specified Device.
        Parameters:
        device - the default Device
        Returns:
        a new top-level NDManager

      • newBaseManager

        static NDManager newBaseManager​(Device device,
                                java.lang.String engineName)
        Creates a new top-level NDManager with specified Device and engine.
        Parameters:
        device - the default Device
        engineName - the name of the engine
        Returns:
        a new top-level NDManager

      • subManagerOf

        static NDManager subManagerOf​(NDResource resource)
        Creates a new manager based on the given resource.
        Parameters:
        resource - the resource to use
        Returns:
        a new memory scrope containing the array

      • defaultDevice

        Device defaultDevice()
        Returns the default context used in Engine.

        The default type is defined by whether the deep learning engine is recognizing GPUs available on your machine. If there is no GPU available, CPU will be used.

        Returns:
        a Device

      • allocateDirect

        java.nio.ByteBuffer allocateDirect​(int capacity)
        Allocates a new engine specific direct byte buffer.
        Parameters:
        capacity - the new buffer's capacity, in bytes
        Returns:
        the new byte buffer

      • from

        NDArray from​(NDArray array)
        Creates a new NDArray if the input NDArray is from an external engine.
        Parameters:
        array - the input NDArray
        Returns:
        a new NDArray if the input NDArray is from external engine

      • create

        default NDArray create​(java.lang.Number data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the Number that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(float data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the float that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(int data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the float data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(double data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the double data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(long data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the long data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(byte data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the byte data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(boolean data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the boolean data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(java.lang.String data)
        Creates and initializes a scalar NDArray.
        Parameters:
        data - the String data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(java.lang.String[] data)
        Creates and initializes 1D NDArray.
        Parameters:
        data - the String data that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(java.lang.String[] data,
                       java.nio.charset.Charset charset)
        Creates and initializes 1D NDArray.
        Parameters:
        data - the String data that needs to be set
        charset - the charset to decode the string
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(java.lang.String[] data,
                       Shape shape)
        Creates a String NDArray based on the provided shape.
        Parameters:
        data - the flattened String array
        shape - the shape of the String NDArray
        Returns:
        a new instance of NDArray

      • create

        NDArray create​(java.lang.String[] data,
               java.nio.charset.Charset charset,
               Shape shape)
        Creates a String NDArray based on the provided shape.
        Parameters:
        data - the flattened String array
        charset - the charset to decode the string
        shape - the shape of the String NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(float[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(int[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(double[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(long[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(byte[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(boolean[] data)
        Creates and initializes a 1D NDArray.
        Parameters:
        data - the bool array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(float[][] data)
        Creates and initializes a 2D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(int[][] data)
        Creates and initializes a 2D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(double[][] data)
        Creates and initializes a 2D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(long[][] data)
        Creates and initializes a 2-D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(byte[][] data)
        Creates and initializes a 2-D NDArray.
        Parameters:
        data - the float array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(boolean[][] data)
        Creates and initializes a 2-D NDArray.
        Parameters:
        data - the boolean array that needs to be set
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(java.nio.Buffer data,
                       Shape shape)
        Creates and initializes a NDArray with specified Shape.

        DataType of the NDArray will determined by type of Buffer.

        Parameters:
        data - the data to initialize the NDArray
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(float[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and float array.
        Parameters:
        data - the float array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(int[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and int array.
        Parameters:
        data - the float array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(double[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and double array.
        Parameters:
        data - the float array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(long[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and long array.
        Parameters:
        data - the float array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(byte[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and byte array.
        Parameters:
        data - the float array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • create

        default NDArray create​(boolean[] data,
                       Shape shape)
        Creates and initializes an instance of NDArray with specified Shape and boolean array.
        Parameters:
        data - the boolean array that needs to be set
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • createCSR

        default NDArray createCSR​(float[] data,
                          long[] indptr,
                          long[] indices,
                          Shape shape,
                          Device device)
        Creates a Compressed Sparse Row Storage (CSR) Format Matrix.
        Parameters:
        data - the data to set for the CSR Matrix
        indptr - the indptr array is what will help identify the rows where the data appears
        indices - the indices array stores the column index for each non-zero element in data
        shape - the Shape of the NDArray
        device - the Device of the NDArray
        Returns:
        a new instance of NDArray

      • createCSR

        default NDArray createCSR​(java.nio.Buffer data,
                          long[] indptr,
                          long[] indices,
                          Shape shape,
                          Device device)
        Creates a Compressed Sparse Row Storage (CSR) Format Matrix.
        Parameters:
        data - the data to set for the CSR Matrix
        indptr - the indptr array is what will help identify the rows where the data appears
        indices - the indices array stores the column index for each non-zero element in data
        shape - the Shape of the NDArray
        device - the Device of the NDArray
        Returns:
        a new instance of NDArray

      • createCSR

        NDArray createCSR​(java.nio.Buffer data,
                  long[] indptr,
                  long[] indices,
                  Shape shape)
        Creates a Compressed Sparse Row Storage (CSR) Format Matrix.
        Parameters:
        data - the data to set for the CSR Matrix
        indptr - the indptr array is what will help identify the rows where the data appears
        indices - the indices array stores the column index for each non-zero element in data
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • createRowSparse

        default NDArray createRowSparse​(java.nio.Buffer data,
                                Shape dataShape,
                                long[] indices,
                                Shape shape,
                                Device device)
        Stores the matrix in row sparse format.
        Parameters:
        data - the data to set for the Row Sparse NDArray
        dataShape - the Shape of the data NDArray
        indices - the indices to store the data
        shape - the Shape of the NDArray
        device - the Device of the NDArray
        Returns:
        a new instance of NDArray

      • createRowSparse

        NDArray createRowSparse​(java.nio.Buffer data,
                        Shape dataShape,
                        long[] indices,
                        Shape shape)
        Stores the matrix in row sparse format.
        Parameters:
        data - the data to set for the Row Sparse NDArray
        dataShape - the Shape of the data NDArray
        indices - the indices to store the data
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • createCoo

        NDArray createCoo​(java.nio.Buffer data,
                  long[][] indices,
                  Shape shape)
        Creates a Coordinate Format (COO) Matrix.
        Parameters:
        data - the data to set for the Coordinate format NDArray
        indices - the matrix represent indices
        shape - the Shape of the NDArray
        Returns:
        a new instance of NDArray

      • decode

        default NDArray decode​(byte[] bytes)
        Decodes NDArray through byte array.
        Parameters:
        bytes - byte array to load from
        Returns:
        NDArray

      • decode

        default NDArray decode​(java.io.InputStream is)
                throws java.io.IOException
        Decodes NDArray through DataInputStream.
        Parameters:
        is - input stream data to load from
        Returns:
        NDArray
        Throws:
        java.io.IOException - data is not readable

      • load

        NDList load​(java.nio.file.Path path)
        Loads the NDArrays saved to a file.
        Parameters:
        path - the path to the file
        Returns:
        the loaded arrays

      • load

        default NDList load​(java.nio.file.Path path,
                    Device device)
        Loads the NDArrays saved to a file.
        Parameters:
        path - the path to the file
        device - the device to use for the loaded arrays
        Returns:
        the loaded arrays

      • setName

        void setName​(java.lang.String name)
        Sets the name for the NDManager.
        Parameters:
        name - the name assigned to the manager

      • getName

        java.lang.String getName()
        Gets the name of the NDManager.
        Returns:
        name

      • full

        default NDArray full​(Shape shape,
                     int value)
        Return a new NDArray of given shape, filled with value.
        Parameters:
        shape - shape of a new NDArray
        value - fill value
        Returns:
        NDArray of fill value with the given shape

      • full

        default NDArray full​(Shape shape,
                     float value)
        Return a new NDArray of given shape, filled with value.
        Parameters:
        shape - shape of a new NDArray
        value - fill value
        Returns:
        NDArray of fill value with the given shape

      • full

        NDArray full​(Shape shape,
             float value,
             DataType dataType)
        Return a new NDArray of given shape, filled with value.
        Parameters:
        shape - shape of a new NDArray
        value - fill value
        dataType - the desired data-type for the NDArray
        Returns:
        NDArray of fill value with the given shape

      • full

        default NDArray full​(Shape shape,
                     float value,
                     DataType dataType,
                     Device device)
        Return a new NDArray of given shape, device, filled with value.
        Parameters:
        shape - shape of a new NDArray
        value - fill value
        dataType - the desired data-type for the NDArray
        device - the Device of the NDArray
        Returns:
        NDArray of fill value with the given shape

      • arange

        default NDArray arange​(int stop)
        Returns evenly spaced values starting from 0.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        stop - the end of the interval. The interval does not include this value
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(float stop)
        Returns evenly spaced values starting from 0.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        stop - the end of the interval. The interval does not include this value
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(int start,
                       int stop)
        Returns evenly spaced values within a given interval with step 1.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(float start,
                       float stop)
        Returns evenly spaced values within a given interval with step 1.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(int start,
                       int stop,
                       int step)
        Returns evenly spaced values within a given interval.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        step - the spacing between values
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(float start,
                       float stop,
                       float step)
        Returns evenly spaced values within a given interval.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        step - the spacing between values
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(int start,
                       int stop,
                       int step,
                       DataType dataType)
        Returns evenly spaced values within a given interval.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        step - the spacing between values
        dataType - the DataType of the NDArray
        Returns:
        a new instance of NDArray

      • arange

        NDArray arange​(float start,
               float stop,
               float step,
               DataType dataType)
        Returns evenly spaced values within a given interval.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        step - the spacing between values
        dataType - the DataType of the NDArray
        Returns:
        a new instance of NDArray

      • arange

        default NDArray arange​(float start,
                       float stop,
                       float step,
                       DataType dataType,
                       Device device)
        Returns evenly spaced values within a given interval.

        Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments, the function is equivalent to the Python built-in range function, but returns an instance of NDArray rather than a list.

        Parameters:
        start - the start of interval. The interval includes this value
        stop - the end of interval. The interval does not include this value
        step - the spacing between values
        dataType - the DataType of the NDArray
        device - the Device of the NDArray
        Returns:
        a new instance of NDArray

      • eye

        default NDArray eye​(int rows)
        Returns a 2-D array with ones on the diagonal and zeros elsewhere.
        Parameters:
        rows - the number of rows and cols in the output
        Returns:
        a NDArray where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one

      • eye

        default NDArray eye​(int rows,
                    int k)
        Returns a 2-D array with ones on the diagonal and zeros elsewhere.
        Parameters:
        rows - the number of rows and cols in the output
        k - the index of the diagonal: a positive value refers to an upper diagonal, and a negative value to a lower diagonal
        Returns:
        a NDArray where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one

      • eye

        default NDArray eye​(int rows,
                    int cols,
                    int k)
        Returns a 2-D array with ones on the diagonal and zeros elsewhere.
        Parameters:
        rows - the number of rows in the output
        cols - the number of columns in the output
        k - the index of the diagonal: a positive value refers to an upper diagonal, and a negative value to a lower diagonal
        Returns:
        a NDArray where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one

      • eye

        NDArray eye​(int rows,
            int cols,
            int k,
            DataType dataType)
        Returns a 2-D array with ones on the diagonal and zeros elsewhere.
        Parameters:
        rows - the number of rows int the output
        cols - the number of columns in the output
        k - the index of the diagonal: a positive value refers to an upper diagonal, and a negative value to a lower diagonal
        dataType - the DataType of the NDArray
        Returns:
        a NDArray where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one

      • eye

        default NDArray eye​(int rows,
                    int cols,
                    int k,
                    DataType dataType,
                    Device device)
        Returns a 2-D array with ones on the diagonal and zeros elsewhere.
        Parameters:
        rows - the number of rows int the output
        cols - the number of columns in the output
        k - the index of the diagonal: a positive value refers to an upper diagonal, and a negative value to a lower diagonal
        dataType - the DataType of the NDArray
        device - the Device of the NDArray
        Returns:
        a NDArray where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one

      • linspace

        default NDArray linspace​(int start,
                         int stop,
                         int num)
        Returns evenly spaced numbers over a specified interval.

        Returns num evenly spaced samples, calculated over the interval [start, stop].

        Parameters:
        start - the starting value of the sequence
        stop - the end value of the sequence
        num - the number of samples to generate
        Returns:
        a new instance of NDArray

      • linspace

        default NDArray linspace​(float start,
                         float stop,
                         int num)
        Returns evenly spaced numbers over a specified interval.

        Returns num evenly spaced samples, calculated over the interval [start, stop].

        Parameters:
        start - the starting value of the sequence
        stop - the end value of the sequence
        num - the number of samples to generate
        Returns:
        a new instance of NDArray

      • linspace

        default NDArray linspace​(int start,
                         int stop,
                         int num,
                         boolean endpoint)
        Returns evenly spaced numbers over a specified interval.

        Returns num evenly spaced samples, calculated over the interval [start, stop].The endpoint of the interval can optionally be excluded.

        Parameters:
        start - the starting value of the sequence
        stop - the end value of the sequence
        num - the number of samples to generate
        endpoint - if true, stop is the last sample, otherwise, it is not included
        Returns:
        a new instance of NDArray

      • linspace

        NDArray linspace​(float start,
                 float stop,
                 int num,
                 boolean endpoint)
        Returns evenly spaced numbers over a specified interval.

        Returns num evenly spaced samples, calculated over the interval [start, stop].The endpoint of the interval can optionally be excluded.

        Parameters:
        start - the starting value of the sequence
        stop - the end value of the sequence
        num - the number of samples to generate
        endpoint - if true, stop is the last sample, otherwise, it is not included
        Returns:
        a new instance of NDArray

      • linspace

        default NDArray linspace​(float start,
                         float stop,
                         int num,
                         boolean endpoint,
                         Device device)
        Returns evenly spaced numbers over a specified interval.

        Returns num evenly spaced samples, calculated over the interval [start, stop].The endpoint of the interval can optionally be excluded.

        Parameters:
        start - the starting value of the sequence
        stop - the end value of the sequence
        num - the number of samples to generate
        endpoint - if true, stop is the last sample, otherwise, it is not included
        device - the Device of the NDArray
        Returns:
        a new instance of NDArray

      • randomInteger

        NDArray randomInteger​(long low,
                      long high,
                      Shape shape,
                      DataType dataType)
        Returns random integer values from low (inclusive) to high (exclusive).
        Parameters:
        low - Lowest (signed) longs to be drawn from the distribution
        high - one above the largest (signed) long to be drawn from the distribution
        shape - the Shape of the NDArray
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • randomPermutation

        NDArray randomPermutation​(long n)
        Returns a random permutation of integers from 0 to n - 1.
        Parameters:
        n - (int) – the upper bound (exclusive)
        Returns:
        a random permutation of integers from 0 to n - 1.

      • randomUniform

        default NDArray randomUniform​(float low,
                              float high,
                              Shape shape)
        Draws samples from a uniform distribution.

        Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

        Parameters:
        low - the lower boundary of the output interval. All values generated will be greater than or equal to low.
        high - the upper boundary of the output interval. All values generated will be less than high.
        shape - the Shape of the NDArray
        Returns:
        the drawn samples NDArray

      • randomUniform

        NDArray randomUniform​(float low,
                      float high,
                      Shape shape,
                      DataType dataType)
        Draws samples from a uniform distribution.

        Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

        Parameters:
        low - the lower boundary of the output interval. All values generated will be greater than or equal to low.
        high - the upper boundary of the output interval. All values generated will be less than high.
        shape - the Shape of the NDArray
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • randomUniform

        default NDArray randomUniform​(float low,
                              float high,
                              Shape shape,
                              DataType dataType,
                              Device device)
        Draws samples from a uniform distribution.

        Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

        Parameters:
        low - the lower boundary of the output interval. All values generated will be greater than or equal to low.
        high - the upper boundary of the output interval. All values generated will be less than high.
        shape - the Shape of the NDArray
        dataType - the DataType of the NDArray
        device - the Device of the NDArray
        Returns:
        the drawn samples NDArray

      • randomNormal

        default NDArray randomNormal​(Shape shape)
        Draws random samples from a normal (Gaussian) distribution with mean 0 and standard deviation 1.

        Samples are distributed according to a normal distribution parametrized by mean = 0 and standard deviation = 1.

        Parameters:
        shape - the output Shape
        Returns:
        the drawn samples NDArray

      • randomNormal

        default NDArray randomNormal​(Shape shape,
                             DataType dataType)
        Draws random samples from a normal (Gaussian) distribution with mean 0 and standard deviation 1.
        Parameters:
        shape - the output Shape
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • randomNormal

        NDArray randomNormal​(float loc,
                     float scale,
                     Shape shape,
                     DataType dataType)
        Draws random samples from a normal (Gaussian) distribution.
        Parameters:
        loc - the mean (centre) of the distribution
        scale - the standard deviation (spread or "width") of the distribution
        shape - the output Shape
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • randomNormal

        default NDArray randomNormal​(float loc,
                             float scale,
                             Shape shape,
                             DataType dataType,
                             Device device)
        Draws random samples from a normal (Gaussian) distribution.
        Parameters:
        loc - the mean (centre) of the distribution
        scale - the standard deviation (spread or "width") of the distribution
        shape - the output Shape
        dataType - the DataType of the NDArray
        device - the Device of the NDArray
        Returns:
        the drawn samples NDArray

      • truncatedNormal

        default NDArray truncatedNormal​(Shape shape)
        Draws random samples from a normal (Gaussian) distribution with mean 0 and standard deviation 1, discarding and re-drawing any samples that are more than two standard deviations from the mean.

        Samples are distributed according to a normal distribution parametrized by mean = 0 and standard deviation = 1.

        Parameters:
        shape - the output Shape
        Returns:
        the drawn samples NDArray

      • truncatedNormal

        default NDArray truncatedNormal​(Shape shape,
                                DataType dataType)
        Draws random samples from a normal (Gaussian) distribution with mean 0 and standard deviation 1, discarding and re-drawing any samples that are more than two standard deviations from the mean.
        Parameters:
        shape - the output Shape
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • truncatedNormal

        NDArray truncatedNormal​(float loc,
                        float scale,
                        Shape shape,
                        DataType dataType)
        Draws random samples from a normal (Gaussian) distribution, discarding and re-drawing any samples that are more than two standard deviations from the mean.
        Parameters:
        loc - the mean (centre) of the distribution
        scale - the standard deviation (spread or "width") of the distribution
        shape - the output Shape
        dataType - the DataType of the NDArray
        Returns:
        the drawn samples NDArray

      • truncatedNormal

        default NDArray truncatedNormal​(float loc,
                                float scale,
                                Shape shape,
                                DataType dataType,
                                Device device)
        Draws random samples from a normal (Gaussian) distribution, discarding and re-drawing any samples that are more than two standard deviations from the mean.
        Parameters:
        loc - the mean (centre) of the distribution
        scale - the standard deviation (spread or "width") of the distribution
        shape - the output Shape
        dataType - the DataType of the NDArray
        device - the Device of the NDArray
        Returns:
        the drawn samples NDArray

      • randomMultinomial

        NDArray randomMultinomial​(int n,
                          NDArray pValues)
        Draw samples from a multinomial distribution.

        The multinomial distribution is a multivariate generalization of the binomial distribution. Take an experiment with one of p possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments. Its values, X_i = [X_0, X_1, ..., X_p], represent the number of times the outcome was i.

        Parameters:
        n - the number of experiments
        pValues - the probabilities of each of the p different outcomes. These should sum to 1 The last element is always assumed to account for the remaining probability, as long as pValues.sum().getFloat() <= 1)
        Returns:
        the drawn samples NDArray

      • randomMultinomial

        NDArray randomMultinomial​(int n,
                          NDArray pValues,
                          Shape shape)
        Draw samples from a multinomial distribution.

        The multinomial distribution is a multivariate generalization of the binomial distribution. Take an experiment with one of p possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments. Its values, X_i = [X_0, X_1, ..., X_p], represent the number of times the outcome was i.

        Parameters:
        n - the number of experiments
        pValues - the probabilities of each of the p different outcomes. These should sum to 1 The last element is always assumed to account for the remaining probability, as long as pValues.sum().getFloat() <= 1)
        shape - the output Shape
        Returns:
        the drawn samples NDArray

      • sampleNormal

        NDArray sampleNormal​(NDArray mu,
                     NDArray sigma)
        Concurrent sampling from multiple normal distributions with parameters *mu* (mean) and *sigma* (standard deviation).
        Parameters:
        mu - Means of the distributions
        sigma - Standard deviations of the distributions
        Returns:
        the drawn samples NDArray

      • sampleNormal

        NDArray sampleNormal​(NDArray mu,
                     NDArray sigma,
                     Shape shape)
        Concurrent sampling from multiple normal distributions with parameters *mu* (mean) and *sigma* (standard deviation).
        Parameters:
        mu - Means of the distributions
        sigma - Standard deviations of the distributions
        shape - Shape to be sampled from each random distribution
        Returns:
        the drawn samples NDArray

      • samplePoisson

        NDArray samplePoisson​(NDArray lam)
        Draw random samples from a Poisson distribution.

        Samples are distributed according to a Poisson distribution parametrized by *lambda* (rate). Samples will always be returned as a floating point data type.

        Parameters:
        lam - Lambda (rate) parameters of the distributions
        Returns:
        the drawn samples NDArray

      • samplePoisson

        NDArray samplePoisson​(NDArray lam,
                      Shape shape)
        Draw random samples from a Poisson distribution.

        Samples are distributed according to a Poisson distribution parametrized by *lambda* (rate). Samples will always be returned as a floating point data type.

        Parameters:
        lam - Lambda (rate) parameters of the distributions
        shape - Shape to be sampled from each random distribution
        Returns:
        the drawn samples NDArray

      • sampleGamma

        NDArray sampleGamma​(NDArray alpha,
                    NDArray beta)
        Draw random samples from a gamma distribution.

        Samples are distributed according to a gamma distribution parametrized by *alpha* (shape) and *beta* (scale).

        Parameters:
        alpha - The shape of the gamma distribution
        beta - The scale of the gamma distribution
        Returns:
        the drawn samples NDArray

      • sampleGamma

        NDArray sampleGamma​(NDArray alpha,
                    NDArray beta,
                    Shape shape)
        Draw random samples from a gamma distribution.

        Samples are distributed according to a gamma distribution parametrized by *alpha* (shape) and *beta* (scale).

        Parameters:
        alpha - The shape of the gamma distribution
        beta - The scale of the gamma distribution
        shape - Shape to be sampled from each random distribution
        Returns:
        the drawn samples NDArray

      • isOpen

        boolean isOpen()
        Check if the manager is still valid.
        Returns:
        the current status

      • cap

        void cap()
        Caps this manager to prevent unintentional attachment of resources. This is useful to detect memory leaks at an early point in time. The attachment of sub managers is still allowed after this method has been called.

      • getParentManager

        NDManager getParentManager()
        Returns the parent NDManager.
        Returns:
        the parent NDManager

      • newSubManager

        NDManager newSubManager()
        Creates a child NDManager.

        Child NDManager will inherit default Device from this NDManager.

        Returns:
        a child NDManager

      • newSubManager

        NDManager newSubManager​(Device device)
        Creates a child NDManager with specified default Device.
        Parameters:
        device - the default Device
        Returns:
        a child NDManager

      • getDevice

        Device getDevice()
        Returns the default Device of this NDManager.
        Returns:
        the default Device of this NDManager

      • getManagedArrays

        java.util.List<NDArray> getManagedArrays()
        Returns all NDArrays managed by this manager (including recursively).
        Returns:
        all NDArrays managed by this manager (including recursively)

      • attachInternal

        void attachInternal​(java.lang.String resourceId,
                    java.lang.AutoCloseable resource)
        Attaches a resource to this NDManager.

        The attached resource will be closed when this NDManager is closed.

        This attachment is internal. Many resources will internally track which manager they are attached to. In that case, you should call NDResource.attach(NDManager) instead and that should then call attachInternal.

        Parameters:
        resourceId - the unique resourceId
        resource - the AutoCloseable resource to be attached

      • attachUncappedInternal

        void attachUncappedInternal​(java.lang.String resourceId,
                            java.lang.AutoCloseable resource)
        Attaches a resource to this NDManager circumventing any cap protection.

        The attached resource will be closed when this NDManager is closed.

        This attachment is internal. Many resources will internally track which manager they are attached to. In that case, you should call NDResource.attach(NDManager) instead and that should then call attachInternal.

        Parameters:
        resourceId - the unique resourceId
        resource - the AutoCloseable resource to be attached

      • tempAttachInternal

        void tempAttachInternal​(NDManager originalManager,
                        java.lang.String resourceId,
                        NDResource resource)
        Temporarily attaches a resource to this NDManager to be returned when this is closed.

        The attached resource will be returned to it's original manager when this NDManager is closed.

        This attachment is internal. Many resources will internally track which manager they are attached to. In that case, you should call NDResource.attach(NDManager) instead and that should then call tempAttachInternal.

        Parameters:
        originalManager - the original manager to return the resource to
        resourceId - the unique resourceId
        resource - the AutoCloseable resource to be attached

      • detachInternal

        void detachInternal​(java.lang.String resourceId)
        Detaches a NDArray from this NDManager's lifecycle.

        The detached NDArray become un-managed, it's user's responsibility to close the resource. Failed to close the resource has to wait on GC to be freed, and might cause out of native memory.

        This detach is internal. Many resources will internally track which manager they are attached to. In that case, you should call NDResource.detach() instead and that should then call detachInternal.

        Parameters:
        resourceId - the resourceId to be removed from this NDManager's lifecycle

      • ret

        default <T extends NDResource> T ret​(T resource)
        Returns a value outside of this manager by attaching to this manager's parent.
        Type Parameters:
        T - the type of the resource
        Parameters:
        resource - the resource to return
        Returns:
        the passed in resource, after attaching to a new manager

      • attachAll

        default void attachAll​(NDResource... resources)
        Attaches all resources to this manager.
        Parameters:
        resources - the resources to attach
        See Also:
        NDResource.attach(NDManager)

      • tempAttachAll

        default void tempAttachAll​(NDResource... resources)
        Temporarily attaches all resources to this manager.
        Parameters:
        resources - the resources to attach
        See Also:
        NDResource.tempAttach(NDManager)

      • invoke

        void invoke​(java.lang.String operation,
            NDArray[] src,
            NDArray[] dest,
            ai.djl.util.PairList<java.lang.String,​?> params)
        An engine specific generic invocation to native operation.

        You should avoid using this function if possible. Since this function is engine specific, using this API may cause a portability issue. Native operation may not be compatible between each version.

        Parameters:
        operation - the native operation to perform
        src - the NDList of source NDArray
        dest - the NDList to save output to
        params - the parameters to be passed to the native operation
        Throws:
        java.lang.IllegalArgumentException - if operation is not supported by Engine
        EngineException - if operation failed in native engine

      • invoke

        NDList invoke​(java.lang.String operation,
              NDList src,
              ai.djl.util.PairList<java.lang.String,​?> params)
        An engine specific generic invocation to native operation.

        You should avoid using this function if possible. Since this function is engine specific, using this API may cause a portability issue. Native operation may not compatible between each version.

        Parameters:
        operation - the native operation to perform
        src - the NDList of source NDArray
        params - the parameters to be passed to the native operation
        Returns:
        the output array of NDArray
        Throws:
        java.lang.IllegalArgumentException - if operation is not supported by Engine
        EngineException - if operation failed in native engine

      • getEngine

        Engine getEngine()
        Returns the Engine associated with this manager.
        Returns:
        the Engine associated with this manager

      • close

        void close()
        Specified by:
        close in interface java.lang.AutoCloseable