AnvlArray

The main array object. Its type is determined by a data type and a shape.

Usage

nv_array(
  data,
  dtype = NULL,
  device = NULL,
  shape = NULL,
  ambiguous = NULL,
  backend = NULL
)

nv_scalar(data, dtype = NULL, device = NULL, ambiguous = NULL, backend = NULL)

nv_empty(dtype, shape, device = NULL, ambiguous = FALSE)

nv_array_like(
  like,
  data,
  dtype = NULL,
  device = NULL,
  shape = NULL,
  ambiguous = NULL,
  backend = NULL
)

nv_scalar_like(
  like,
  data,
  dtype = NULL,
  device = NULL,
  ambiguous = NULL,
  backend = NULL
)

nv_empty_like(
  like,
  dtype = NULL,
  shape = NULL,
  device = NULL,
  ambiguous = NULL
)

Arguments

data: (any)
integer(), double(), or logical() scalar, vector, or array.
dtype: (NULL | character(1) | tengen::DataType)
One of bool, i8, i16, i32, i64, ui8, ui16, ui32, ui64, f32, f64 or a tengen::DataType. The default (NULL) uses the current backend's default dtype: f32 for numeric data on "xla", f64 for numeric data on "quickr", i32 for integer data, and bool for logical data.
device: (NULL | character(1) | PJRTDevice)
The device for the array ("cpu", "cuda"). Default is to use the CPU for new arrays. This can be changed by setting the PJRT_PLATFORM environment variable.
shape: (NULL | integer())
The output shape of the array. The default (NULL) is to infer it from the data if possible. Note that nv_array interprets length 1 vectors as having shape (1). To create a "scalar" with dimension (), use nv_scalar or explicitly specify shape = c().
ambiguous: (NULL | logical(1))
Whether the dtype should be marked as ambiguous. Defaults to FALSE for new arrays.
backend: (NULL | character(1))
Backend to use ("xla" or "quickr"). Defaults to default_backend(). Must not be specified inside jit().
like: (AnvlArray)
An existing array. Any of dtype, device, shape, ambiguous, and backend that are NULL (the default) are taken from like.

Value

(AnvlArray)

Extractors

The following generic functions can be used to extract information from an AnvlArray:

dtype(): Get the data type of the array.
shape(): Get the shape (dimensions) of the array.
ndims(): Get the number of dimensions.
device(): Get the device of the array.
platform(): Get the platform (e.g. "cpu", "cuda").
ambiguous(): Get whether the dtype is ambiguous.

Serialization

Arrays can be serialized to and from the safetensors format:

nv_save() / nv_read(): Save/load arrays to/from a file.
nv_serialize() / nv_unserialize(): Serialize/deserialize arrays to/from raw vectors.

Examples

# A 1-d array (vector) with shape (4). Default type for integers is `i32`
nv_array(1:4)
#> AnvlArray
#>  1
#>  2
#>  3
#>  4
#> [ CPUi32{4} ] 

# Specify a dtype
nv_array(c(1.5, 2.5, 3.5), dtype = "f64")
#> AnvlArray
#>  1.5000
#>  2.5000
#>  3.5000
#> [ CPUf64{3} ] 

# A 2x3 matrix
nv_array(1:6, shape = c(2L, 3L))
#> AnvlArray
#>  1 3 5
#>  2 4 6
#> [ CPUi32{2,3} ] 

# A scalar array.
nv_scalar(3.14)
#> AnvlArray
#>  3.1400
#> [ CPUf32{} ] 

# A 0x3 array
nv_empty("f32", shape = c(0L, 3L))
#> AnvlArray
#> [ CPUf32{0,3} ] 

# --- Extractors ---
x <- nv_array(1:6, shape = c(2L, 3L))
dtype(x)
#> <i32>
shape(x)
#> [1] 2 3
ndims(x)
#> [1] 2
device(x)
#> <CpuDevice(id=0)>
platform(x)
#> [1] "cpu"
ambiguous(x)
#> [1] FALSE

# --- Transforming arrays with jit ---
add_one <- jit(function(x) x + 1)
add_one(nv_array(1:4))
#> AnvlArray
#>  2
#>  3
#>  4
#>  5
#> [ CPUf32?{4} ] 

# --- Eager mode (calling operations directly) ---
nv_add(nv_array(1:3), nv_array(4:6))
#> AnvlArray
#>  5
#>  7
#>  9
#> [ CPUi32{3} ]