Document matfaust/pyfaust.lazilinop kron and LazyLinearOpKron.

gen_doc/CMakeLists.txt

@@ -31,7 +31,7 @@ if(BUILD_DOCUMENTATION)
 			string(CONCAT DOXYGEN_FILE_PATTERNS "*.cpp *.hpp *.h *.cu *.hu")
 		endif()
 		if(BUILD_WRAPPER_MATLAB)
-			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " Faust.m FaustMulMode.m StoppingCriterion.m ConstraintGeneric.m ConstraintMat.m ConstraintReal.m ConstraintInt.m ConstraintName.m ParamsFact.m ParamsHierarchical.m ParamsPalm4MSA.m FaustFactory.m hadamard.m quickstart.m fft.m bsl.m runtimecmp.m runall.m version.m faust_fact.m ParamsHierarchicalSquareMat.m ParamsHierarchicalRectMat.m license.m omp.m wht.m dft.m eye.m rand.m rand_bsr.m eigtj.m hierarchical.m fact.m palm4msa.m fgft_givens.m fgft_palm.m svdtj.m splin.m spcol.m proj_gen.m sp.m const.m supp.m hankel.m toeplitz.m circ.m normcol.m normlin.m splincol.m blockdiag.m skperm.m enable_gpu_mod.m is_gpu_mod_enabled.m isFaust.m poly.m basis.m next.m expm_multiply.m FaustPoly.m MHTPParams.m palm4msa_mhtp.m hierarchical_mhtp.m butterfly.m ParamsHierarchicalDFT.m create_bsr.m ParamsPalm4msaWHT.m proj_id.m ParamsHierarchicalNoResCons.m ParamsHierarchicalWHTNoResCons.m ParamsHierarchicalRectMatNoResCons.m circ.m anticirc.m toeplitz.m dct.m dst.m rand_butterfly.m opt_butterfly_faust.m bitrev_perm.m LazyLinearOp.m asLazyLinearOp.m isLazyLinearOp.m ") # warning: the space on the end matters
+			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} " Faust.m FaustMulMode.m StoppingCriterion.m ConstraintGeneric.m ConstraintMat.m ConstraintReal.m ConstraintInt.m ConstraintName.m ParamsFact.m ParamsHierarchical.m ParamsPalm4MSA.m FaustFactory.m hadamard.m quickstart.m fft.m bsl.m runtimecmp.m runall.m version.m faust_fact.m ParamsHierarchicalSquareMat.m ParamsHierarchicalRectMat.m license.m omp.m wht.m dft.m eye.m rand.m rand_bsr.m eigtj.m hierarchical.m fact.m palm4msa.m fgft_givens.m fgft_palm.m svdtj.m splin.m spcol.m proj_gen.m sp.m const.m supp.m hankel.m toeplitz.m circ.m normcol.m normlin.m splincol.m blockdiag.m skperm.m enable_gpu_mod.m is_gpu_mod_enabled.m isFaust.m poly.m basis.m next.m expm_multiply.m FaustPoly.m MHTPParams.m palm4msa_mhtp.m hierarchical_mhtp.m butterfly.m ParamsHierarchicalDFT.m create_bsr.m ParamsPalm4msaWHT.m proj_id.m ParamsHierarchicalNoResCons.m ParamsHierarchicalWHTNoResCons.m ParamsHierarchicalRectMatNoResCons.m circ.m anticirc.m toeplitz.m dct.m dst.m rand_butterfly.m opt_butterfly_faust.m bitrev_perm.m LazyLinearOp.m asLazyLinearOp.m isLazyLinearOp.m LazyLinearOpKron.m kron.m ") # warning: the space on the end matters
 		endif()
 		if(BUILD_WRAPPER_PYTHON)
 			string(CONCAT DOXYGEN_FILE_PATTERNS ${DOXYGEN_FILE_PATTERNS} "__init__.py factparams.py demo.py tools.py fact.py proj.py poly.py lazylinop.py")

wrapper/matlab/+matfaust/+lazylinop/@LazyLinearOpKron/LazyLinearOpKron.m

+% ================================
+%> @brief This class implements a specialization of LazyLinearOp dedicated to the
+%> Kronecker product of two linear operators.
+%>
+%> @b See @b also: matfaust.lazylinop.kron.
+% ================================
 classdef LazyLinearOpKron < matfaust.lazylinop.LazyLinearOp
 	properties (SetAccess = private, Hidden = true)
 		A;
 		B;
 	end
 	methods
+		%================================
+		%> Constructor for the A x B Kronecker product.
+		%================================
 		function LK = LazyLinearOpKron(A, B)
 
 			shape = [size(A, 1) * size(B, 1), size(A, 2) * size(B, 2)];
@@ -12,21 +21,39 @@ classdef LazyLinearOpKron < matfaust.lazylinop.LazyLinearOp
 			LK.B = B;
 		end
 
+		%================================
+		%> Returns the LazyLinearOpKron conjugate.
+		%================================
 		function CLK = conj(LK)
 			import matfaust.lazylinop.*
 			CLK = LazyLinearOpKron(conj(asLazyLinearOp(LK.A)), conj(asLazyLinearOp(LK.B)));
 		end
 
+		%================================
+		%> Returns the LazyLinearOpKron transpose.
+		%================================
 		function CLK = transpose(LK)
 			import matfaust.lazylinop.*
 			CLK = LazyLinearOpKron(transpose(asLazyLinearOp(LK.A)), transpose(asLazyLinearOp((LK.B))));
 		end
 
+		%================================
+		%> Returns the LazyLinearOpKron adjoint/transconjugate.
+		%================================
 		function CTLK = ctranspose(LK)
 			import matfaust.lazylinop.*
 			CTLK = LazyLinearOpKron(ctranspose(asLazyLinearOp(LK.A)), ctranspose(asLazyLinearOp((LK.B))));
 		end
 
+		%=============================================================
+		%> @brief Returns the LazyLinearOp for the multiplication self * op
+		%> or if op is a full matrix it returns the full matrix (self * op).
+		%>
+		%> @note this specialization is particularly optimized for multiplying the
+		%> operator by a vector.
+		%>
+		%> @param op: an object compatible with self for this binary operation.
+		%=============================================================
 		function LmK = mtimes(LK, op)
 			import matfaust.lazylinop.LazyLinearOp
 			if isscalar(LK) && LazyLinearOp.isLazyLinearOp(op)
@@ -57,8 +84,10 @@ classdef LazyLinearOpKron < matfaust.lazylinop.LazyLinearOp
 			end
 		end
 
+		%================================
+		%> See LazyLinearOp.eval.
+		%================================
 		function E = eval(LK)
-
 			A = LK.A;
 			B = LK.B;
 			if any(ismember(methods(A), 'full'))

wrapper/matlab/+matfaust/+lazylinop/kron.m

+%=============================================================
+%> @brief Returns the LazyLinearOp for the Kronecker product A x B.
+%>
+%>
+%> @note this specialization is particularly optimized for applying the operator self to a vector.
+%>
+%> @param A: LinearOperator (scaling factor),
+%> @param B: LinearOperator (block factor).
+%>
+%> @b Example:
+%> @code
+%>>> A = rand(100, 100);
+%> >> B = rand(100, 100);
+%> >> AxB = kron(A, B);
+%> >> lAxB = matfaust.lazylinop.kron(A, B)
+%>
+%> lAxB =
+%>
+%>   10000x10000 LazyLinearOpKron array with no properties.
+%>
+%> >> x = rand(size(AxB, 2), 1);
+%> >> timeit(@() AxB * x)
+%>
+%> ans =
+%>
+%>     0.0400
+%>
+%> >> timeit(@() lAxB * x)
+%>
+%> ans =
+%>
+%>    7.8475e-04
+%>
+%> >> norm(AxB * x - lAxB * x) < 1e-9
+%>
+%> ans =
+%>
+%>   logical
+%>
+%>    1
+%> @endcode
+%>
+%> @b See @b also: LazyLinearOpKron, kron matlab built-in.
+%=============================================================
 function KL = kron(A, B)
     import matfaust.lazylinop.LazyLinearOpKron
-    KL = LazyLinearOpKron(A, B); 
+    KL = LazyLinearOpKron(A, B);
 end

wrapper/python/pyfaust/lazylinop.py

@@ -741,28 +741,86 @@ def vstack(tup):
         raise TypeError('lop must be a LazyLinearOp')
 
 def kron(A, B):
+    """
+    Returns the LazyLinearOp(Kron) for the Kronecker product A x B.
+
+    Note: this specialization is particularly optimized for multiplying the
+    operator by a vector.
+
+    Args:
+        A: LinearOperator (scaling factor),
+        B: LinearOperator (block factor).
+
+    Example:
+        >>> from pyfaust.lazylinop import kron as lkron
+        >>> import numpy as np
+        >>> from pyfaust import rand
+        >>> A = np.random.rand(100, 100)
+        >>> B = np.random.rand(100, 100)
+        >>> AxB = np.kron(A,B)
+        >>> lAxB = lkron(A, B)
+        >>> x = np.random.rand(AxB.shape[1], 1)
+        >>> print(np.allclose(AxB@x, lAxB@x))
+        True
+        >>> from timeit import timeit
+        >>> timeit(lambda: AxB @ x, number=10)
+        0.4692082800902426
+        >>> timeit(lambda: lAxB @ x, number=10)
+        0.03464869409799576
+
+    <b>See also:</b> LazyLinearOpKron, numpy.kron.
+    """
     return LazyLinearOpKron(A, B)
 
 class LazyLinearOpKron(LazyLinearOp):
+    """
+    This class implements a specialization of LazyLinearOp dedicated to the
+    Kronecker product of two linear operators.
+
+    <b>See also:</b> pyfaust.lazylinop.kron.
+    """
 
     def __init__(self, A, B):
+        """
+        Constructor for the A x B Kronecker product.
+        """
         self.A = A
         self.B = B
         shape = (A.shape[0] * B.shape[0], A.shape[1] * B.shape[1])
         super(LazyLinearOpKron, self).__init__(lambda: A, shape, A)
 
     def conj(self):
+        """
+        Returns the LazyLinearOpKron conjugate.
+        """
         return LazyLinearOpKron(asLazyLinearOp(self.A).conj(),
                                 asLazyLinearOp(self.B).conj())
 
     def transpose(self):
+        """
+        Returns the LazyLinearOpKron transpose.
+        """
         return LazyLinearOpKron(asLazyLinearOp(self.A).T, asLazyLinearOp(self.B).T)
 
     def getH(self):
+        """
+        Returns the LazyLinearOpKron adjoint/transconjugate.
+        """
         return LazyLinearOpKron(asLazyLinearOp(self.A).getH(), asLazyLinearOp(self.B).getH())
 
     def __matmul__(self, op):
-        #TODO: refactor with parent function
+        """
+        Returns the LazyLinearOpKron for the multiplication self @ op or if op is a np.ndarray it returns the np.ndarray (self @ op).
+
+        Note: this specialization is particularly optimized for multiplying the
+        operator by a vector.
+
+        Args:
+            op: an object compatible with self for this binary operation.
+
+        <b>See also:</b> pyfaust.lazylinop.kron.
+        """
+
         self._sanitize_matmul(op)
         if hasattr(op, 'reshape') and hasattr(op, '__matmul__') and hasattr(op,
                                                                             '__getitem__'):