Skip to main content
Version: 2.8.0

Vector Operations

Overview​

Icicle exposes a number of vector operations which a user can use:

  • The VecOps API provides efficient vector operations such as addition, subtraction, and multiplication.
  • MatrixTranspose API allows a user to perform a transpose on a vector representation of a matrix

VecOps API Documentation​

Example​

Vector addition​

package main

import (
	"github.com/ingonyama-zk/icicle/v2/wrappers/golang/core"
	cr "github.com/ingonyama-zk/icicle/v2/wrappers/golang/cuda_runtime"
	bn254 "github.com/ingonyama-zk/icicle/v2/wrappers/golang/curves/bn254"
)

func main() {
	testSize := 1 << 12
	a := bn254.GenerateScalars(testSize)
	b := bn254.GenerateScalars(testSize)
	out := make(core.HostSlice[bn254.ScalarField], testSize)
	cfg := core.DefaultVecOpsConfig()

	// Perform vector multiplication
	err := bn254.VecOp(a, b, out, cfg, core.Add)
	if err != cr.CudaSuccess {
		panic("Vector addition failed")
	}
}

Vector Subtraction​

package main

import (
	"github.com/ingonyama-zk/icicle/v2/wrappers/golang/core"
	cr "github.com/ingonyama-zk/icicle/v2/wrappers/golang/cuda_runtime"
	bn254 "github.com/ingonyama-zk/icicle/v2/wrappers/golang/curves/bn254"
)

func main() {
	testSize := 1 << 12
	a := bn254.GenerateScalars(testSize)
	b := bn254.GenerateScalars(testSize)
	out := make(core.HostSlice[bn254.ScalarField], testSize)
	cfg := core.DefaultVecOpsConfig()

	// Perform vector multiplication
	err := bn254.VecOp(a, b, out, cfg, core.Sub)
	if err != cr.CudaSuccess {
		panic("Vector subtraction failed")
	}
}

Vector Multiplication​

package main

import (
	"github.com/ingonyama-zk/icicle/v2/wrappers/golang/core"
	cr "github.com/ingonyama-zk/icicle/v2/wrappers/golang/cuda_runtime"
	bn254 "github.com/ingonyama-zk/icicle/v2/wrappers/golang/curves/bn254"
)

func main() {
	testSize := 1 << 12
	a := bn254.GenerateScalars(testSize)
	b := bn254.GenerateScalars(testSize)
	out := make(core.HostSlice[bn254.ScalarField], testSize)
	cfg := core.DefaultVecOpsConfig()

	// Perform vector multiplication
	err := bn254.VecOp(a, b, out, cfg, core.Mul)
	if err != cr.CudaSuccess {
		panic("Vector multiplication failed")
	}
}

VecOps Method​

func VecOp(a, b, out core.HostOrDeviceSlice, config core.VecOpsConfig, op core.VecOps) (ret cr.CudaError)

Parameters​

  • a: The first input vector.
  • b: The second input vector.
  • out: The output vector where the result of the operation will be stored.
  • config: A VecOpsConfig object containing various configuration options for the vector operations.
  • op: The operation to perform, specified as one of the constants (Sub, Add, Mul) from the VecOps type.

Return Value​

  • CudaError: Returns a CUDA error code indicating the success or failure of the vector operation.

VecOpsConfig​

The VecOpsConfig structure holds configuration parameters for the vector operations, allowing customization of its behavior.

type VecOpsConfig struct {
    Ctx cr.DeviceContext
    isAOnDevice bool
    isBOnDevice bool
    isResultOnDevice bool
    IsAsync bool
}

Fields​

  • Ctx: Device context containing details like device ID and stream ID.
  • isAOnDevice: Indicates if vector a is located on the device.
  • isBOnDevice: Indicates if vector b is located on the device.
  • isResultOnDevice: Specifies where the result vector should be stored (device or host memory).
  • IsAsync: Controls whether the vector operation runs asynchronously.

Default Configuration​

Use DefaultVecOpsConfig to obtain a default configuration, customizable as needed.

func DefaultVecOpsConfig() VecOpsConfig

MatrixTranspose API Documentation​

This section describes the functionality of the TransposeMatrix function used for matrix transposition.

The function takes a matrix represented as a 1D slice and transposes it, storing the result in another 1D slice.

Function​

func TransposeMatrix(in, out core.HostOrDeviceSlice, columnSize, rowSize int, ctx cr.DeviceContext, onDevice, isAsync bool) (ret core.IcicleError)

Parameters​

  • in: The input matrix is a core.HostOrDeviceSlice, stored as a 1D slice.
  • out: The output matrix is a core.HostOrDeviceSlice, which will be the transpose of the input matrix, stored as a 1D slice.
  • columnSize: The number of columns in the input matrix.
  • rowSize: The number of rows in the input matrix.
  • ctx: The device context cr.DeviceContext to be used for the matrix transpose operation.
  • onDevice: Indicates whether the input and output slices are stored on the device (GPU) or the host (CPU).
  • isAsync: Indicates whether the matrix transpose operation should be executed asynchronously.

Return Value​

The function returns a core.IcicleError value, which represents the result of the matrix transpose operation. If the operation is successful, the returned value will be 0.

Example Usage​

var input = make(core.HostSlice[ScalarField], 20)
var output = make(core.HostSlice[ScalarField], 20)

// Populate the input matrix
// ...

// Get device context
ctx, _ := cr.GetDefaultDeviceContext()

// Transpose the matrix
err := TransposeMatrix(input, output, 5, 4, ctx, false, false)
if err.IcicleErrorCode != core.IcicleErrorCode(0) {
    // Handle the error
}

// Use the transposed matrix
// ...

In this example, the TransposeMatrix function is used to transpose a 5x4 matrix stored in a 1D slice. The input and output slices are stored on the host (CPU), and the operation is executed synchronously.