Build and return a LazyTensor object.

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)

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).

Value

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

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.

Author

Joan Glaunes, Chloe Serre-Combe, Amelie Vernay

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'

}