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
: AVecOpsConfig
object containing various configuration options for the vector operations.op
: The operation to perform, specified as one of the constants (Sub
,Add
,Mul
) from theVecOps
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 acore.HostOrDeviceSlice
, stored as a 1D slice.out
: The output matrix is acore.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 contextcr.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.