Skip to navigation

CuVSMatrix

View as Markdown

Java package: com.nvidia.cuvs

public interface CuVSMatrix extends AutoCloseable

This represents a wrapper for a dataset to be used for index construction. The purpose is to allow a caller to place the vectors into native memory directly, instead of requiring the caller to load all the vectors into the heap (e.g. with a float[][]).

Public Members

ofArray

static CuVSMatrix ofArray(float[][] vectors)

Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:47

ofArray

static CuVSMatrix ofArray(int[][] vectors)

Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:57

ofArray

static CuVSMatrix ofArray(byte[][] vectors)

Creates a dataset from an on-heap array of vectors. This method will allocate an additional MemorySegment to hold the graph data.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:67

addVector

void addVector(float[] vector)

Adds a single vector to the matrix.

Parameters

NameDescription
vectorA float array of as many elements as the dimensions

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:81

addVector

void addVector(byte[] vector)

Adds a single vector to the matrix.

Parameters

NameDescription
vectorA byte array of as many elements as the dimensions

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:88

addVector

void addVector(int[] vector)

Adds a single vector to the matrix.

Parameters

NameDescription
vectorAn int array of as many elements as the dimensions

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:95

addVector

void addVector(short[] vector)

Adds a single vector to the matrix. Each element is a raw float16 bit pattern stored in a short.

Parameters

NameDescription
vectorA short array of as many elements as the dimensions

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:102

build

T build()

Completes the matrix and transfers ownership to the caller.

If this method fails, callers should close the builder. Built-in builders then release matrix storage allocated during builder construction; providers that inherit the default no-op #close() implementation do not.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:111

close

@Override default void close()

Closes this builder. Built-in builders release matrix storage unless ownership was transferred by a successful #build().

The default implementation preserves compatibility with providers compiled before builders became closeable. Builders that allocate storage before #build() should override this method.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:121

hostBuilder

static Builder<CuVSHostMatrix> hostBuilder(long size, long columns, DataType dataType)

Returns a builder to create a new instance of a host-memory matrix

Parameters

NameDescription
sizeNumber of rows (e.g. vectors in a dataset)
columnsNumber of columns (e.g. dimension of each vector in the dataset)
dataTypeThe data type of the dataset elements

Returns

a builder for creating a CuVSHostMatrix

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:133

hostBuilder

static Builder<CuVSHostMatrix> hostBuilder( long size, long columns, int rowStride, int columnStride, DataType dataType)

Returns a builder to create a new instance of a host-memory matrix

Parameters

NameDescription
sizeNumber of rows (e.g. vectors in a dataset)
columnsNumber of columns (e.g. dimension of each vector in the dataset)
rowStrideThe stride (in number of elements) for each row. Must be -1 or > than columns
columnStrideThe stride for each column. Currently, it is not supported (must be -1)
dataTypeThe data type of the dataset elements

Returns

a builder for creating a CuVSDeviceMatrix

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:147

deviceBuilder

static Builder<CuVSDeviceMatrix> deviceBuilder( CuVSResources resources, long size, long columns, DataType dataType)

Returns a builder to create a new instance of a dataset

Parameters

NameDescription
resourcesCuVS resources used to allocate the device memory needed
sizeNumber of rows (e.g. vectors in a dataset)
columnsNumber of columns (e.g. dimension of each vector in the dataset)
dataTypeThe data type of the dataset elements

Returns

a builder for creating a CuVSDeviceMatrix

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:162

deviceBuilder

static Builder<CuVSDeviceMatrix> deviceBuilder( CuVSResources resources, long size, long columns, int rowStride, int columnStride, DataType dataType)

Returns a builder to create a new instance of a dataset

Parameters

NameDescription
resourcesCuVS resources used to allocate the device memory needed
sizeNumber of rows (e.g. vectors in a dataset)
columnsNumber of columns (e.g. dimension of each vector in the dataset)
rowStrideThe stride (in number of elements) for each row. Must be -1 or > than columns
columnStrideThe stride for each column. Currently, it is not supported (must be -1)
dataTypeThe data type of the dataset elements

Returns

a builder for creating a CuVSDeviceMatrix

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:178

size

long size()

Gets the size of the dataset

Returns

Size of the dataset

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:194

columns

long columns()

Gets the number of columns in the Dataset (e.g. the dimensions of the vectors in this dataset, or the graph degree for the graph represented as a list of neighbours

Returns

Dimensions of the vectors in the dataset

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:202

dataType

DataType dataType()

Gets the element type

Returns

a DataType describing the matrix element type

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:209

getRow

RowView getRow(long row)

Get a view (0-copy) of the row data, as a list of integers (32 bit)

Parameters

NameDescription
rowthe row for which to return the data

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:216

toArray

void toArray(int[][] array)

Copies the content of this dataset to an on-heap Java matrix (array of arrays).

Parameters

NameDescription
arraythe destination array. Must be of length CuVSMatrix#size() or bigger, and each element must be of length CuVSMatrix#columns() or bigger.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:224

toArray

void toArray(float[][] array)

Copies the content of this dataset to an on-heap Java matrix (array of arrays).

Parameters

NameDescription
arraythe destination array. Must be of length CuVSMatrix#size() or bigger, and each element must be of length CuVSMatrix#columns() or bigger.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:232

toArray

void toArray(byte[][] array)

Copies the content of this dataset to an on-heap Java matrix (array of arrays).

Parameters

NameDescription
arraythe destination array. Must be of length CuVSMatrix#size() or bigger, and each element must be of length CuVSMatrix#columns() or bigger.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:240

toHost

void toHost(CuVSHostMatrix hostMatrix)

Fills the provided, pre-allocated host matrix with data from this matrix. The content of the provided host matrix will be overwritten; the 2 matrices must have the same element type and dimension.

Parameters

NameDescription
hostMatrixthe host-memory-backed matrix to fill.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:249

toHost

CuVSHostMatrix toHost()

Returns a host matrix; if the matrix is already a host matrix, a “weak” reference to the same host memory is returned. If the matrix is a device matrix, a newly allocated matrix will be populated with data from the device matrix. The returned host matrix will need to be managed by the caller, which will be responsible to call CuVSMatrix#close() to free its resources when done.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:258

toDevice

void toDevice(CuVSDeviceMatrix deviceMatrix, CuVSResources cuVSResources)

Fills the provided, pre-allocated device matrix with data from this matrix. The content of the provided device matrix will be overwritten; the 2 matrices must have the same element type and dimension.

Parameters

NameDescription
deviceMatrixthe device-memory-backed matrix to fill.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:267

toDevice

CuVSDeviceMatrix toDevice(CuVSResources cuVSResources)

Returns a device matrix; if this matrix is already a device matrix, a “weak” reference to the same host memory is returned. If the matrix is a host matrix, a newly allocated matrix will be populated with data from the host matrix. The returned device matrix will need to be managed by the caller, which will be responsible to call CuVSMatrix#close() to free its resources when done.

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:276

Source: java/cuvs-java/src/main/java/com/nvidia/cuvs/CuVSMatrix.java:17