rkeops (version 2.2.2)

LazyTensor: Build and return a LazyTensor object.

Description

LazyTensor objects are wrappers around R matrices or vectors that are used to create symbolic formulas for the KeOps reduction operations.

Usage

LazyTensor(x, index = NA, is_complex = FALSE)

Value

An object of class "LazyTensor" or "ComplexLazyTensor".

Arguments

x

A matrix or a vector of numeric values, or a scalar value

index

A text string that should be either "i" or "j", or an NA value (the default), to specify whether the x variable is indexed by i (rows), by j (columns), or is a fixed parameter across indices. If x is a matrix, index must be "i" or "j".

is_complex

A boolean (default is FALSE). Whether we want to create a ComplexLazyTensor (is_complex = TRUE) or a LazyTensor (is_complex = FALSE).

Author

Joan Glaunes, Chloe Serre-Combe, Amelie Vernay

Details

The LazyTensor() function builds a LazyTensor, which is a list containing the following elements:

• formula: a string defining the mathematical operation to be computed by the KeOps routine - each variable is encoded with the pointer address of its argument, suffixed by 'i', 'j', or 'NA', to give it a unique identifier;

• args: a vector of arguments containing a unique identifier associated to the type of the argument:

  • Vi(n): vector indexed by i of dim n

  • Vj(n): vector indexed by j of dim n

  • Pm(n): fixed parameter of dim n

• data: A list of R matrices which will be the inputs of the KeOps routine;

• dimres: An integer corresponding to the inner dimension of the LazyTensor. dimres is used when creating new LazyTensors that result from operations, to keep track of the dimension.

Note 1

Setting the argument is_complex to TRUE will build a ComplexLazyTensor, which is also a LazyTensor. Run browseVignettes("rkeops") and see "RKeOps LazyTensor" vignette for further details on how ComplexLazyTensors are built.

Note 2

If x is an integer, LazyTensor(x) builds a LazyTensor whose formula is simply IntCst(x) and contains all the necessary information; args and data remain empty to avoid useless storage.

Alternatives

• LazyTensor(x, "i") is equivalent to Vi(x) (see Vi() function)

• LazyTensor(x, "j") is equivalent to Vi(x) (see Vj() function)

• LazyTensor(x) is equivalent to Pm(x) (see Pm()function)

Run browseVignettes("rkeops") to access the vignettes and see how to use LazyTensors.

Examples

if (FALSE) {
# Data
nx <- 100
ny <- 150
x <- matrix(runif(nx * 3), nrow = nx, ncol = 3) # arbitrary R matrix representing 
                                                # 100 data points in R^3
y <- matrix(runif(ny * 3), nrow = ny, ncol = 3) # arbitrary R matrix representing 
                                                # 150 data points in R^3
s <- 0.1                                        # scale parameter

# Turn our Tensors into KeOps symbolic variables:
x_i <- LazyTensor(x, "i")   # symbolic object representing an arbitrary row of x, 
                            # indexed by the letter "i"
y_j <- LazyTensor(y, "j")   # symbolic object representing an arbitrary row of y, 
                            # indexed by the letter "j"

# Perform large-scale computations, without memory overflows:
D_ij <- sum((x_i - y_j)^2)    # symbolic matrix of pairwise squared distances, 
                              # with 100 rows and 150 columns
K_ij <- exp(- D_ij / s^2)     # symbolic matrix, 100 rows and 150 columns
res <- sum(K_ij, index = "i") # actual R matrix (in fact a row vector of 
                              # length 150 here)
                              # containing the column sums of K_ij
                              # (i.e. the sums over the "i" index, for each 
                              # "j" index)


# Example : create ComplexLazyTensor:
z <- matrix(1i^ (-6:5), nrow = 4)                     # create a complex 4x3 matrix
z_i <- LazyTensor(z, index = 'i', is_complex = TRUE)  # create a ComplexLazyTensor, 
                                                      # indexed by 'i'

}