CONTRACTION               package:PTAk               R Documentation

_C_o_n_t_r_a_c_t_i_o_n _o_f _t_w_o _t_e_n_s_o_r_s

_D_e_s_c_r_i_p_t_i_o_n:

     Computes the contraction product of two tensors as a
     generalisation of matrix product.

_U_s_a_g_e:

      CONTRACTION(X,z, Xwiz=NULL,zwiX=NULL,rezwiX=FALSE,usetensor=TRUE)
      CONTRACTION.list((X,zlist,moins=1,zwiX=NULL,usetensor=TRUE,withapply=FALSE)

_A_r_g_u_m_e_n_t_s:

       X: a tensor(as an array) of any order

       z: another tensor  (with at least one space in common)

   zlist: a list of lists like a `solution.PTAk' at least with `v' for
          every list(here `v' can be any array) 

    Xwiz: `Xwiz' is to specify the entries of `X' to contract with
          entries of `z' specified by `zwiX', if `Xwiz' `NULL'
          `dim(z)[zwiX]' matching `dim(X)' will do without ambiguity
          (taking all `z' dimensions if `zwiX' is `NULL'). In
          `CONTRACTION.list' it is not set as one supposes the
          contractions in the list to operate follow the dimensions of
          X

    zwiX: idem as `Xwiz'. If both `Xwiz' and `zwiX' are `NULL' `zwiX'is
          replaced by full possibilities (`1:length(dimz)') then `Xwiz'
          is looked for. In `CONTRACTION.list' it is the vector for
          dimensions in the `v' to contract with X. Only 1-way
          dimension for each `v'.

   moins: the elements in `zlist' to skip (see also `TENSELE')

  rezwiX: logical if `TRUE' (and zwiX is `NULL') rematches the
          dimensions in for `zwiX': useful only if the dimensions of z
          were not following the Xwiz order and are not equals.

usetensor: if `TRUE' uses `tensor' (add-on package)

withapply: if `TRUE' (only for vectors in `zlist' uses `apply'

_D_e_t_a_i_l_s:

     Like two matrices contract according to the appropriate dimensions
     (columns matching rows) when one performs a matrix product, this
     operation does pretty much the same thing for tensors(array) and
     specified contraction dimensions given by `Xwiz' and `zwiX' which
     should match. The function is actually written like: transforms
     both tensors as matrices with the ``matching tensor product" of
     their contraction dimensions in columns (for higher order tensor)
     and rows (the other one), performs the matrix product and rebuild
     the result as a tensor(array). Without using `tensor', if `Xwiz'
     and/or `zwiX' are not specified the functions tries to match all
     `z' dimensions onto the dimensions of X where X is the higher
     order tensor (if it is not the case in the arguments the function
     swaps them).

_V_a_l_u_e:

     A tensor of dimension `c(dim(X)[-Xwiz],dim(z)[-zwiX])' if `X' has
     got a bigger order than `z'.

_N_o_t_e:

     This operation generalises the matrix product to the contracted
     product of any two tensors(arrays), and should theoretically
     perform the tensor product if no matching (no contraction) but has
     not been implemented. I recently put the option of using `tensor'
     which does exactly the same thing faster as well as it is from
     `C'. When using `tensor' if `Xwiz' or `zwiX' are `NULL' they are
     replaced by the full possibilities.

_A_u_t_h_o_r(_s):

     Didier Leibovici didier@fmrib.ox.ac.uk

_R_e_f_e_r_e_n_c_e_s:

     Leibovici D and Sabatier R (1998) A Singular Value Decomposition
     of a k-ways array for a Principal Component Analysis of multi-way
     data, the PTA-k. Linear Algebra and its Applications, 269:307-329.

     Schwartz L (1975) Les Tenseurs. Herman, Paris.

_S_e_e _A_l_s_o:

     `PTAk',  `APSOLUk'

_E_x_a_m_p_l_e_s:

      library(tensor)
        z <-  array(1:12,c(2,3,2))
        X <- array(1:48,c(3,4,2,2))
        Xcz <- CONTRACTION(X,z,Xwiz=c(1,3,4),zwiX=c(2,3,1))
        dim(Xcz)   # 4
        Xcz1 <- CONTRACTION(X,z,Xwiz=c(3,4),zwiX=c(1,3))
        dim(Xcz1) # 3,4,3
        Xcz2 <- CONTRACTION(X,z,Xwiz=c(3,4),zwiX=c(3,1))
        Xcz1[,,1]
        Xcz2[,,1]
        #######
        sval0 <- list(list(v=c(1,2,3,4)),list(v=rep(1,3)),list(v=c(1,3)))
        tew <- array(1:24,c(4,3,2))
         CONTRACTION.list(tew,sval0,moins=1)
            #this is equivalent to the following which may be too expensive for big datasets
         CONTRACTION(tew,TENSELE(sval0,moins=1),Xwiz=c(2,3))
        ##
          CONTRACTION.list(tew,sval0,moins=c(1,2)) #must be equal to
          CONTRACTION(tew,sval0[[3]]$v,Xwiz=3)


