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 c3s2i@free.fr

_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)
        

