GPUObject (SystemML 0.15.0 API)

java.lang.Object
- org.apache.sysml.runtime.instructions.gpu.context.GPUObject

```
public class GPUObject
extends Object
```
Handle to a matrix block on the GPU

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`dirty` whether the block attached to this `GPUContext` is dirty on the device and needs to be copied back to host
`protected boolean`	`isSparse` Whether this block is in sparse format
`protected AtomicLong`	`locks` number of read/write locks on this object (this GPUObject is being used in a current instruction)
`protected org.apache.sysml.runtime.controlprogram.caching.MatrixObject`	`mat` Enclosing `MatrixObject` instance

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`acquireDeviceModifyDense()`
`boolean`	`acquireDeviceModifySparse()`
`boolean`	`acquireDeviceRead()`
`boolean`	`acquireHostRead()` if the data is allocated on the GPU and is dirty, it is copied back to the host memory
`void`	`addLock()`
`void`	`allocateAndFillDense(double v)` Allocates a dense matrix of size obtained from the attached matrix metadata and fills it up with a single value
`void`	`allocateSparseAndEmpty()` Allocates a sparse and empty `GPUObject` This is the result of operations that are both non zero matrices.
`jcuda.jcudnn.cudnnTensorDescriptor`	`allocateTensorDescriptor(int N, int C, int H, int W)` Returns a previously allocated or allocates and returns a tensor descriptor
`void`	`clearData()` lazily clears the data associated with this `GPUObject` instance
`void`	`clearData(boolean eager)` Clears the data associated with this `GPUObject` instance
`Object`	`clone()`
`static CSRPointer`	`columnMajorDenseToRowMajorSparse(GPUContext gCtx, jcuda.jcusparse.cusparseHandle cusparseHandle, jcuda.Pointer densePtr, int rows, int cols)` Convenience method to convert a CSR matrix to a dense matrix on the GPU Since the allocated matrix is temporary, bookkeeping is not updated.
`protected void`	`copyFromDeviceToHost()`
`static String`	`debugString(jcuda.Pointer A, long rows, long cols)` Gets the double array from GPU memory onto host memory and returns string.
`void`	`denseColumnMajorToRowMajor()` Convenience method.
`void`	`denseRowMajorToColumnMajor()` Convenience method.
`void`	`denseToSparse()` Converts this GPUObject from dense to sparse format.
`jcuda.Pointer`	`getJcudaDenseMatrixPtr()` Pointer to dense matrix
`CSRPointer`	`getJcudaSparseMatrixPtr()` Pointer to sparse matrix
`protected long`	`getSizeOnDevice()`
`CSRPointer`	`getSparseMatrixCudaPointer()` Convenience method to directly examine the Sparse matrix on GPU
`jcuda.jcudnn.cudnnTensorDescriptor`	`getTensorDescriptor()` Returns a previously allocated tensor descriptor or null
`int[]`	`getTensorShape()` Returns a previously allocated tensor shape or null
`boolean`	`isAllocated()`
`boolean`	`isDirty()` Whether this block is dirty on the GPU
`boolean`	`isInputAllocated()`
`boolean`	`isSparse()`
`boolean`	`isSparseAndEmpty()` If this `GPUObject` is sparse and empty Being allocated is a prerequisite to being sparse and empty.
`void`	`releaseInput()` Releases input allocated on GPU
`void`	`releaseOutput()` releases output allocated on GPU
`void`	`setDenseMatrixCudaPointer(jcuda.Pointer densePtr)` Convenience method to directly set the dense matrix pointer on GPU
`void`	`setSparseMatrixCudaPointer(CSRPointer sparseMatrixPtr)` Convenience method to directly set the sparse matrix on GPU Needed for operations like `JCusparse.cusparseDcsrgemm(cusparseHandle, int, int, int, int, int, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, Pointer, Pointer, Pointer)`
`void`	`sparseToColumnMajorDense()` More efficient method to convert sparse to dense but returns dense in column major format
`void`	`sparseToDense()` Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format)
`void`	`sparseToDense(String instructionName)` Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format) Also records per instruction invokation of sparseToDense.
`static int`	`toIntExact(long l)`
`String`	`toString()`
`static jcuda.Pointer`	`transpose(GPUContext gCtx, jcuda.Pointer densePtr, int m, int n, int lda, int ldc)` Transposes a dense matrix on the GPU by calling the cublasDgeam operation

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - dirty
```
protected boolean dirty
```
    whether the block attached to this GPUContext is dirty on the device and needs to be copied back to host
  - locks
```
protected AtomicLong locks
```
    number of read/write locks on this object (this GPUObject is being used in a current instruction)
  - isSparse
```
protected boolean isSparse
```
    Whether this block is in sparse format
  - mat
```
protected org.apache.sysml.runtime.controlprogram.caching.MatrixObject mat
```
    Enclosing MatrixObject instance
- Method Detail
  - clone
```
public Object clone()
```
    Overrides:
    
    clone in class Object
  - transpose
```
public static jcuda.Pointer transpose(GPUContext gCtx,
                                      jcuda.Pointer densePtr,
                                      int m,
                                      int n,
                                      int lda,
                                      int ldc)
                               throws DMLRuntimeException
```
    Transposes a dense matrix on the GPU by calling the cublasDgeam operation
    
    Parameters:
    
    gCtx - a valid GPUContext
    
    densePtr - Pointer to dense matrix on the GPU
    
    m - rows in ouput matrix
    
    n - columns in output matrix
    
    lda - rows in input matrix
    
    ldc - columns in output matrix
    
    Returns:
    
    transposed matrix
    
    Throws:
    
    DMLRuntimeException - if operation failed
  - columnMajorDenseToRowMajorSparse
```
public static CSRPointer columnMajorDenseToRowMajorSparse(GPUContext gCtx,
                                                          jcuda.jcusparse.cusparseHandle cusparseHandle,
                                                          jcuda.Pointer densePtr,
                                                          int rows,
                                                          int cols)
                                                   throws DMLRuntimeException
```
    Convenience method to convert a CSR matrix to a dense matrix on the GPU Since the allocated matrix is temporary, bookkeeping is not updated. Also note that the input dense matrix is expected to be in COLUMN MAJOR FORMAT Caller is responsible for deallocating memory on GPU.
    
    Parameters:
    
    gCtx - a valid GPUContext
    
    cusparseHandle - handle to cusparse library
    
    densePtr - [in] dense matrix pointer on the GPU in row major
    
    rows - number of rows
    
    cols - number of columns
    
    Returns:
    
    CSR (compressed sparse row) pointer
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - debugString
```
public static String debugString(jcuda.Pointer A,
                                 long rows,
                                 long cols)
                          throws DMLRuntimeException
```
    Gets the double array from GPU memory onto host memory and returns string.
    
    Parameters:
    
    A - Pointer to memory on device (GPU), assumed to point to a double array
    
    rows - rows in matrix A
    
    cols - columns in matrix A
    
    Returns:
    
    the debug string
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - getSparseMatrixCudaPointer
```
public CSRPointer getSparseMatrixCudaPointer()
```
    Convenience method to directly examine the Sparse matrix on GPU
    
    Returns:
    
    CSR (compressed sparse row) pointer
  - setSparseMatrixCudaPointer
```
public void setSparseMatrixCudaPointer(CSRPointer sparseMatrixPtr)
                                throws DMLRuntimeException
```
    Convenience method to directly set the sparse matrix on GPU Needed for operations like JCusparse.cusparseDcsrgemm(cusparseHandle, int, int, int, int, int, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, int, Pointer, Pointer, Pointer, cusparseMatDescr, Pointer, Pointer, Pointer)
    
    Parameters:
    
    sparseMatrixPtr - CSR (compressed sparse row) pointer
    
    Throws:
    
    DMLRuntimeException - ?
  - setDenseMatrixCudaPointer
```
public void setDenseMatrixCudaPointer(jcuda.Pointer densePtr)
                               throws DMLRuntimeException
```
    Convenience method to directly set the dense matrix pointer on GPU
    
    Parameters:
    
    densePtr - dense pointer
    
    Throws:
    
    DMLRuntimeException - ?
  - denseToSparse
```
public void denseToSparse()
                   throws DMLRuntimeException
```
    Converts this GPUObject from dense to sparse format.
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - denseRowMajorToColumnMajor
```
public void denseRowMajorToColumnMajor()
                                throws DMLRuntimeException
```
    Convenience method. Converts Row Major Dense Matrix to Column Major Dense Matrix
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - denseColumnMajorToRowMajor
```
public void denseColumnMajorToRowMajor()
                                throws DMLRuntimeException
```
    Convenience method. Converts Column Major Dense Matrix to Row Major Dense Matrix
    
    Throws:
    
    DMLRuntimeException - if error
  - sparseToDense
```
public void sparseToDense()
                   throws DMLRuntimeException
```
    Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format)
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - sparseToDense
```
public void sparseToDense(String instructionName)
                   throws DMLRuntimeException
```
    Convert sparse to dense (Performs transpose, use sparseToColumnMajorDense if the kernel can deal with column major format) Also records per instruction invokation of sparseToDense.
    
    Parameters:
    
    instructionName - Name of the instruction for which statistics are recorded in GPUStatistics
    
    Throws:
    
    DMLRuntimeException - ?
  - sparseToColumnMajorDense
```
public void sparseToColumnMajorDense()
                              throws DMLRuntimeException
```
    More efficient method to convert sparse to dense but returns dense in column major format
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - isSparse
```
public boolean isSparse()
```
  - getTensorShape
```
public int[] getTensorShape()
```
    Returns a previously allocated tensor shape or null
    
    Returns:
    
    int array of four elements or null
  - getTensorDescriptor
```
public jcuda.jcudnn.cudnnTensorDescriptor getTensorDescriptor()
```
    Returns a previously allocated tensor descriptor or null
    
    Returns:
    
    cudnn tensor descriptor
  - allocateTensorDescriptor
```
public jcuda.jcudnn.cudnnTensorDescriptor allocateTensorDescriptor(int N,
                                                                   int C,
                                                                   int H,
                                                                   int W)
```
    Returns a previously allocated or allocates and returns a tensor descriptor
    
    Parameters:
    
    N - number of images
    
    C - number of channels
    
    H - height
    
    W - width
    
    Returns:
    
    cudnn tensor descriptor
  - isAllocated
```
public boolean isAllocated()
```
  - isInputAllocated
```
public boolean isInputAllocated()
```
  - allocateSparseAndEmpty
```
public void allocateSparseAndEmpty()
                            throws DMLRuntimeException
```
    Allocates a sparse and empty GPUObject This is the result of operations that are both non zero matrices.
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - allocateAndFillDense
```
public void allocateAndFillDense(double v)
                          throws DMLRuntimeException
```
    Allocates a dense matrix of size obtained from the attached matrix metadata and fills it up with a single value
    
    Parameters:
    
    v - value to fill up the dense matrix
    
    Throws:
    
    DMLRuntimeException - if DMLRuntimeException occurs
  - isSparseAndEmpty
```
public boolean isSparseAndEmpty()
                         throws DMLRuntimeException
```
    If this GPUObject is sparse and empty Being allocated is a prerequisite to being sparse and empty.
    
    Returns:
    
    true if sparse and empty
    
    Throws:
    
    DMLRuntimeException - if error
  - acquireDeviceRead
```
public boolean acquireDeviceRead()
                          throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - acquireDeviceModifyDense
```
public boolean acquireDeviceModifyDense()
                                 throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - acquireDeviceModifySparse
```
public boolean acquireDeviceModifySparse()
                                  throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - addLock
```
public void addLock()
```
  - acquireHostRead
```
public boolean acquireHostRead()
                        throws org.apache.sysml.runtime.controlprogram.caching.CacheException
```
    if the data is allocated on the GPU and is dirty, it is copied back to the host memory
    
    Returns:
    
    true if a copy to host happened, false otherwise
    
    Throws:
    
    org.apache.sysml.runtime.controlprogram.caching.CacheException - ?
  - releaseInput
```
public void releaseInput()
                  throws DMLRuntimeException
```
    Releases input allocated on GPU
    
    Throws:
    
    DMLRuntimeException - if data is not allocated or if there is no locked GPU Object or if could not obtain a GPUContext
  - releaseOutput
```
public void releaseOutput()
                   throws DMLRuntimeException
```
    releases output allocated on GPU
    
    Throws:
    
    DMLRuntimeException - if data is not allocated or if there is no locked GPU Object or if could not obtain a GPUContext
  - getSizeOnDevice
```
protected long getSizeOnDevice()
                        throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - toIntExact
```
public static int toIntExact(long l)
                      throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - copyFromDeviceToHost
```
protected void copyFromDeviceToHost()
                             throws DMLRuntimeException
```
    Throws:
    
    DMLRuntimeException
  - clearData
```
public void clearData()
               throws DMLRuntimeException
```
    lazily clears the data associated with this GPUObject instance
    
    Throws:
    
    org.apache.sysml.runtime.controlprogram.caching.CacheException - ?
    
    DMLRuntimeException
  - clearData
```
public void clearData(boolean eager)
               throws DMLRuntimeException
```
    Clears the data associated with this GPUObject instance
    
    Parameters:
    
    eager - whether to be done synchronously or asynchronously
    
    Throws:
    
    org.apache.sysml.runtime.controlprogram.caching.CacheException - ?
    
    DMLRuntimeException
  - getJcudaDenseMatrixPtr
```
public jcuda.Pointer getJcudaDenseMatrixPtr()
```
    Pointer to dense matrix
    
    Returns:
    
    ?
  - getJcudaSparseMatrixPtr
```
public CSRPointer getJcudaSparseMatrixPtr()
```
    Pointer to sparse matrix
    
    Returns:
    
    ?
  - isDirty
```
public boolean isDirty()
```
    Whether this block is dirty on the GPU
    
    Returns:
    
    ?
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Methods inherited from class java.lang.Object

dirty

locks

isSparse

mat

clone

transpose

columnMajorDenseToRowMajorSparse

debugString

getSparseMatrixCudaPointer

setSparseMatrixCudaPointer

setDenseMatrixCudaPointer

denseToSparse

denseRowMajorToColumnMajor

denseColumnMajorToRowMajor

sparseToDense

sparseToDense

sparseToColumnMajorDense

isSparse

getTensorShape

getTensorDescriptor

allocateTensorDescriptor

isAllocated

isInputAllocated

allocateSparseAndEmpty

allocateAndFillDense

isSparseAndEmpty

acquireDeviceRead

acquireDeviceModifyDense

acquireDeviceModifySparse

addLock

acquireHostRead

releaseInput

releaseOutput

getSizeOnDevice

toIntExact

copyFromDeviceToHost

clearData

clearData

getJcudaDenseMatrixPtr

getJcudaSparseMatrixPtr

isDirty

toString