Add the wrapper pyfaust.opt_butterfly_faust to optimize any butterfly Faust...

Add the wrapper pyfaust.opt_butterfly_faust to optimize any butterfly Faust (in addition to the DFT).

#275.

wrapper/python/pyfaust.py

@@ -3800,8 +3800,8 @@ def rand_bsr(num_rows, num_cols, bnrows, bncols, num_factors=None, density=.1,
 
     Example:
         >>> from pyfaust import rand_bsr
-        >>> rand_bsr(100,100, 20, 10, num_factors=6) 
-        Faust size 100x100, density 0.6, nnz_sum 6000, 6 factor(s): 
+        >>> rand_bsr(100,100, 20, 10, num_factors=6)
+        Faust size 100x100, density 0.6, nnz_sum 6000, 6 factor(s):
             - FACTOR 0 (double) BSR, size 100x100, density 0.1, nnz 1000
             - FACTOR 1 (double) BSR, size 100x100, density 0.1, nnz 1000
             - FACTOR 2 (double) BSR, size 100x100, density 0.1, nnz 1000
@@ -4102,6 +4102,28 @@ def rand_butterfly(n, dtype='float64', dev='cpu'):
         RB_factors.append(rb)
     return Faust(RB_factors)
 
+def opt_butterfly_faust(F):
+    """
+    Optimizes any Faust composed of butterfly factors.
+
+    The returned Faust will be more efficient if multiplied by a vector or a
+    matrix.
+    This optimization is based on the diagonals of each butterfly factor.
+    Multiplying a butterfly factor B by a vector x (y = B@x) is equivalent to forming
+    two diagonals D1 and D2 from B and compute y' = D1@x + D2 @ x[I] where I is
+    set in the proper order to obtain y' = y.
+
+    Args:
+        F: The Faust to optimize. If the factors of F are not set according to
+        a butterfly structure, the result is not defined.
+
+    Returns:
+        The optimized Faust.
+
+    <b>See also</b>: pyfaust.fact.butterfly, pyfaust.dft, pyfaust.rand_butterfly.
+    """
+    oF = Faust(core_obj=F.m_faust.optimizeButterfly())
+    return oF
 
 def enable_gpu_mod(libpaths=None, backend='cuda', silent=False, fatal=False):
     """

wrapper/python/src/FaustCoreCpp.h

@@ -175,6 +175,7 @@ class FaustCoreCpp
     FPP get_item(unsigned long int i, unsigned long int j);
     void colSliceMultiply(unsigned long int j1, unsigned long int j2, const FPP* data, unsigned long int data_ncols, FPP* out) const;
     void indexMultiply(unsigned long int* d0_ids, size_t d0_ids_len, unsigned long int* d1_ids, size_t d1_ids_len, const FPP* mat_data, int mat_ncols, FPP* mat_out) const;
+    FaustCoreCpp<FPP,DEV>* optimizeButterfly() const;
     ~FaustCoreCpp();
     static FaustCoreCpp<FPP,DEV>* randFaust(unsigned int t,
             unsigned int min_num_factors, unsigned int max_num_factors,

wrapper/python/src/FaustCoreCpp.hpp

@@ -568,6 +568,15 @@ template<typename FPP, FDevice DEV>
       return core;
 }
 
+template<typename FPP, FDevice DEV>
+  FaustCoreCpp<FPP,DEV>* FaustCoreCpp<FPP,DEV>::optimizeButterfly() const
+{
+      Faust::TransformHelper<FPP,DEV>* th = Faust::TransformHelperButterfly<FPP,DEV>::optFaust(this->transform);
+      if(!th) return NULL;
+      FaustCoreCpp<FPP,DEV>* core = new FaustCoreCpp<FPP,DEV>(th);
+      return core;
+}
+
 template<typename FPP, FDevice DEV>
   FaustCoreCpp<FPP,DEV>* FaustCoreCpp<FPP,DEV>::eyeFaust(unsigned int n, unsigned int m)
 {

wrapper/python/src/FaustCoreGenCy.pxd.in

@@ -125,6 +125,7 @@ cdef extern from "FaustCoreCpp.h":
 
         @staticmethod
         @CPP_CORE_CLASS@[FPP]* hadamardFaust(unsigned int n, const bool norma)
+        @CPP_CORE_CLASS@[FPP]* optimizeButterfly()
         @staticmethod
         @CPP_CORE_CLASS@[FPP]* polyBasis(unsigned int L_nrows, unsigned int
                                      L_ncols, int* L_rowptr, int* L_colind,

wrapper/python/src/_FaustCoreGen.pyx.in

@@ -820,6 +820,12 @@ cdef class FaustCoreGen@TYPE_NAME@@PROC@:
     def get_item(self, i, j):
         return self.@CORE_OBJ@.get_item(i,j)
 
+    def optimizeButterfly(F):
+        core = @CORE_CLASS@(core=True)
+        core.@CORE_OBJ@ = \
+                F.@CORE_OBJ@.optimizeButterfly()
+        return core
+
     def __dealloc__(self):
         del self.@CORE_OBJ@