Package ai.djl.ndarray

Interface NDManager

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
BaseNDManager
public interface NDManager extends 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:

  • Field Details

    • UID_GENERATOR

      static final AtomicLong UID_GENERATOR

  • Method Details

    • nextUid

      static String nextUid()
      Returns a low-cost unique ID.
      Returns:
      a string UID.

    • 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(String engineName)
      Creates a new top-level NDManager with specified engine.
      Parameters:
      engineName - the name of the engine
      Returns:
      a new top-level NDManager

    • newBaseManager

      static NDManager newBaseManager(Device device, 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

      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(Shape shape)
      Creates an uninitialized instance of DataType.FLOAT32 NDArray with specified Shape.
      Parameters:
      shape - the Shape of the NDArray
      Returns:
      a new instance of NDArray

    • create

      default NDArray create(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(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(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(String[] data, 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(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(String[] data, 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(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

      NDArray create(Shape shape, DataType dataType)
      Creates an uninitialized instance of NDArray with specified Shape, and DataType.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      Returns:
      a new instance of NDArray

    • create

      default NDArray create(Buffer data, Shape shape, DataType dataType)
      Creates and initializes an instance of NDArray with specified Shape and DataType.
      Parameters:
      data - the data to initialize the NDArray
      shape - the Shape of the NDArray
      dataType - the DataType 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

    • create

      default NDArray create(Shape shape, DataType dataType, Device device)
      Creates an uninitialized instance of NDArray with specified Shape, DataType and Device.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      device - the Device 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(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(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(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(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(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(InputStream is) throws IOException
      Decodes NDArray through DataInputStream.
      Parameters:
      is - input stream data to load from
      Returns:
      NDArray
      Throws:
      IOException - data is not readable

    • load

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

    • load

      default NDList load(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(String name)
      Sets the name for the NDManager.
      Parameters:
      name - the name assigned to the manager

    • getName

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

    • zeros

      default NDArray zeros(Shape shape)
      Creates an instance of NDArray with specified Shape filled with zeros.
      Parameters:
      shape - the Shape of the NDArray
      Returns:
      a new instance of NDArray
      See Also:

    • zeros

      default NDArray zeros(Shape shape, DataType dataType)
      Creates an instance of NDArray with specified Shape filled with zeros.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      Returns:
      a new instance of NDArray
      See Also:

    • zeros

      default NDArray zeros(Shape shape, DataType dataType, Device device)
      Creates an instance of NDArray with specified Device, Shape, and DataType filled with zeros.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      device - the Device of the NDArray
      Returns:
      a new instance of NDArray

    • ones

      default NDArray ones(Shape shape, DataType dataType)
      Creates an instance of NDArray with specified Shape filled with ones.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      Returns:
      a new instance of NDArray

    • ones

      default NDArray ones(Shape shape)
      Creates an instance of NDArray with specified Shape filled with ones.
      Parameters:
      shape - the Shape of the NDArray
      Returns:
      a new instance of NDArray

    • ones

      default NDArray ones(Shape shape, DataType dataType, Device device)
      Creates an instance of NDArray with specified Device, Shape, and DataType filled with ones.
      Parameters:
      shape - the Shape of the NDArray
      dataType - the DataType of the NDArray
      device - the Device of the NDArray
      Returns:
      a new instance of NDArray

    • 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

    • hanningWindow

      default NDArray hanningWindow(long numPoints)
      Builds the Hanning Window.

      The Hanning was named for Julius von Hann, an Austrian meteorologist. It is also known as the Cosine Bell. Some authors prefer that it be called a Hann window, to help avoid confusion with the very similar Hamming window.

      Parameters:
      numPoints - Number of points in the output window.
      Returns:
      the window

    • 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

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

    • attachInternal

      void attachInternal(String resourceId, 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(String resourceId, 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, 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(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:

    • tempAttachAll

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

    • invoke

      void invoke(String operation, NDArray[] src, NDArray[] dest, ai.djl.util.PairList<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:
      IllegalArgumentException - if operation is not supported by Engine
      EngineException - if operation failed in native engine

    • invoke

      NDList invoke(String operation, NDList src, ai.djl.util.PairList<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:
      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 AutoCloseable