Package ai.djl.ndarray

Class BaseNDManager

java.lang.Object
ai.djl.ndarray.BaseNDManager
All Implemented Interfaces:
NDManager, AutoCloseable
public abstract class BaseNDManager extends Object implements NDManager
BaseNDManager is the default implementation of NDManager.

  • Field Details

  • Constructor Details

    • BaseNDManager

      protected BaseNDManager(NDManager parent, Device device)

  • Method Details

    • defaultDevice

      public final 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.

      Specified by:
      defaultDevice in interface NDManager
      Returns:
      a Device

    • create

      public NDArray create(String[] data, Charset charset, Shape shape)
      Creates a String NDArray based on the provided shape.
      Specified by:
      create in interface NDManager
      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

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

    • createCSR

      public NDArray createCSR(Buffer data, long[] indptr, long[] indices, Shape shape)
      Creates a Compressed Sparse Row Storage (CSR) Format Matrix.
      Specified by:
      createCSR in interface NDManager
      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

      public NDArray createRowSparse(Buffer data, Shape dataShape, long[] indices, Shape shape)
      Stores the matrix in row sparse format.
      Specified by:
      createRowSparse in interface NDManager
      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

      public NDArray createCoo(Buffer data, long[][] indices, Shape shape)
      Creates a Coordinate Format (COO) Matrix.
      Specified by:
      createCoo in interface NDManager
      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

    • load

      public NDList load(Path path)
      Loads the NDArrays saved to a file.
      Specified by:
      load in interface NDManager
      Parameters:
      path - the path to the file
      Returns:
      the loaded arrays

    • setName

      public void setName(String name)
      Sets the name for the NDManager.
      Specified by:
      setName in interface NDManager
      Parameters:
      name - the name assigned to the manager

    • getName

      public String getName()
      Gets the name of the NDManager.
      Specified by:
      getName in interface NDManager
      Returns:
      name

    • full

      public NDArray full(Shape shape, float value, DataType dataType)
      Return a new NDArray of given shape, filled with value.
      Specified by:
      full in interface NDManager
      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

    • arange

      public 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.

      Specified by:
      arange in interface NDManager
      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

    • eye

      public NDArray eye(int rows, int cols, int k, DataType dataType)
      Returns a 2-D array with ones on the diagonal and zeros elsewhere.
      Specified by:
      eye in interface NDManager
      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

    • linspace

      public 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.

      Specified by:
      linspace in interface NDManager
      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

    • randomInteger

      public NDArray randomInteger(long low, long high, Shape shape, DataType dataType)
      Returns random integer values from low (inclusive) to high (exclusive).
      Specified by:
      randomInteger in interface NDManager
      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

      public NDArray randomPermutation(long n)
      Returns a random permutation of integers from 0 to n - 1.
      Specified by:
      randomPermutation in interface NDManager
      Parameters:
      n - (int) – the upper bound (exclusive)
      Returns:
      a random permutation of integers from 0 to n - 1.

    • randomUniform

      public 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.

      Specified by:
      randomUniform in interface NDManager
      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

    • randomNormal

      public NDArray randomNormal(float loc, float scale, Shape shape, DataType dataType)
      Draws random samples from a normal (Gaussian) distribution.
      Specified by:
      randomNormal in interface NDManager
      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

      public 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.
      Specified by:
      truncatedNormal in interface NDManager
      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

    • randomMultinomial

      public 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.

      Specified by:
      randomMultinomial in interface NDManager
      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

      public 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.

      Specified by:
      randomMultinomial in interface NDManager
      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

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

    • sampleNormal

      public NDArray sampleNormal(NDArray mu, NDArray sigma, Shape shape)
      Concurrent sampling from multiple normal distributions with parameters *mu* (mean) and *sigma* (standard deviation).
      Specified by:
      sampleNormal in interface NDManager
      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

      public 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.

      Specified by:
      samplePoisson in interface NDManager
      Parameters:
      lam - Lambda (rate) parameters of the distributions
      Returns:
      the drawn samples NDArray

    • samplePoisson

      public 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.

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

    • sampleGamma

      public 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).

      Specified by:
      sampleGamma in interface NDManager
      Parameters:
      alpha - The shape of the gamma distribution
      beta - The scale of the gamma distribution
      Returns:
      the drawn samples NDArray

    • sampleGamma

      public 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).

      Specified by:
      sampleGamma in interface NDManager
      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

      public boolean isOpen()
      Check if the manager is still valid.
      Specified by:
      isOpen in interface NDManager
      Returns:
      the current status

    • cap

      public 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.
      Specified by:
      cap in interface NDManager

    • getParentManager

      public NDManager getParentManager()
      Returns the parent NDManager.
      Specified by:
      getParentManager in interface NDManager
      Returns:
      the parent NDManager

    • newSubManager

      public NDManager newSubManager()
      Creates a child NDManager.

      Child NDManager will inherit default Device from this NDManager.

      Specified by:
      newSubManager in interface NDManager
      Returns:
      a child NDManager

    • getDevice

      public Device getDevice()
      Returns the default Device of this NDManager.
      Specified by:
      getDevice in interface NDManager
      Returns:
      the default Device of this NDManager

    • getManagedArrays

      public List<NDArray> getManagedArrays()
      Returns all NDArrays managed by this manager (including recursively).
      Specified by:
      getManagedArrays in interface NDManager
      Returns:
      all NDArrays managed by this manager (including recursively)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • attachInternal

      public void attachInternal(String resourceId, AutoCloseable... resources)
      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.

      Specified by:
      attachInternal in interface NDManager
      Parameters:
      resourceId - the unique resourceId
      resources - the AutoCloseable resource to be attached

    • attachUncappedInternal

      public 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.

      Specified by:
      attachUncappedInternal in interface NDManager
      Parameters:
      resourceId - the unique resourceId
      resource - the AutoCloseable resource to be attached

    • tempAttachInternal

      public 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.

      Specified by:
      tempAttachInternal in interface NDManager
      Parameters:
      originalManager - the original manager to return the resource to
      resourceId - the unique resourceId
      resource - the AutoCloseable resource to be attached

    • detachInternal

      public 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.

      Specified by:
      detachInternal in interface NDManager
      Parameters:
      resourceId - the resourceId to be removed from this NDManager's lifecycle

    • invoke

      public 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.

      Specified by:
      invoke in interface NDManager
      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

    • invoke

      public 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.

      Specified by:
      invoke in interface NDManager
      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

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface NDManager

    • debugDump

      public void debugDump(int level)
      Prints information about this NDManager and all sub-managers to the console.
      Parameters:
      level - the level of this NDManager in the hierarchy

    • validateBuffer

      public static void validateBuffer(Buffer buffer, DataType dataType, int expected)
      Checks if the input buffer size is match expected data type.
      Parameters:
      buffer - the input buffer
      dataType - the desired DataType
      expected - the expected size
      Throws:
      IllegalArgumentException - if buffer size is invalid

    • copyBuffer

      public static void copyBuffer(Buffer src, ByteBuffer target)
      Copies data from the source Buffer to the target ByteBuffer.
      Parameters:
      src - the source Buffer
      target - the target ByteBuffer