Package ai.djl.ndarray

Class BaseNDManager

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

    • Field Detail

      • alternativeManager

        protected NDManager alternativeManager

      • uid

        protected java.lang.String uid

      • name

        protected java.lang.String name

      • device

        protected Device device

      • resources

        protected java.util.concurrent.ConcurrentHashMap<java.lang.String,​java.lang.AutoCloseable> resources

      • closed

        protected java.util.concurrent.atomic.AtomicBoolean closed

      • capped

        protected java.util.concurrent.atomic.AtomicBoolean capped

    • Constructor Detail

      • BaseNDManager

        protected BaseNDManager​(NDManager parent,
                        Device device)

    • Method Detail

      • 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​(java.lang.String[] data,
                      java.nio.charset.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

      • createCSR

        public NDArray createCSR​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.file.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​(java.lang.String name)
        Sets the name for the NDManager.
        Specified by:
        setName in interface NDManager
        Parameters:
        name - the name assigned to the manager

      • getName

        public java.lang.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 java.util.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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • attachInternal

        public void attachInternal​(java.lang.String resourceId,
                           java.lang.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​(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.

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

      • tempAttachInternal

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

        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​(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.

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

      • invoke

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

        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​(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.

        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 java.lang.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​(java.nio.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:
        java.lang.IllegalArgumentException - if buffer size is invalid

      • copyBuffer

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