pyfaust.proj module

The module for pyfaust proximal operators.

class pyfaust.proj.anticirc(shape, normalized=True, pos=False)

Functor for the anticirculant projector.

Example:

>>> from pyfaust.proj import circ
>>> import numpy as np
>>> from numpy.random import rand, seed
>>> seed(43) # for reproducibility
>>> M = (rand(5, 5)*10).astype('int').astype('double')
>>> M
array([[1., 6., 1., 2., 3.],
       [8., 6., 5., 0., 7.],
       [3., 8., 2., 0., 8.],
       [2., 4., 3., 0., 8.],
       [8., 9., 3., 9., 4.]])
>>> p = anticirc(M.shape, normalized=False)
>>> p(M)
array([[4. , 5. , 5.4, 4.2, 3.4],
       [5. , 5.4, 4.2, 3.4, 4. ],
       [5.4, 4.2, 3.4, 4. , 5. ],
       [4.2, 3.4, 4. , 5. , 5.4],
       [3.4, 4. , 5. , 5.4, 4.2]])

__init__(shape, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): the size of the input matrix.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.blockdiag(shape, block_shapes, normalized=True, pos=False)

Functor for the BLOCKDIAG projector. It sets all values to zero except for the diagonal blocks of the support defined by block_shapes. The i-th diagonal block starts at the row and column indices (block_shapes[i-1][0], block_shapes[i-1][1]) or (0,0) if i == 0 and ends at the row and columns indices (block_shapes[i][0]-1, block_shapes[i][1]-1) or (shape[0], shape[1]) if i == len(block_shapes)-1.

Example:

>>> from pyfaust.proj import blockdiag
>>> import numpy as np
>>> M = np.ones((12,12))
>>> p = blockdiag(M.shape, [(1, 1), (4, 4), (7, 7)], normalized=False)
>>> M_ = p(M)
>>> M_
array([[1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
       [0., 1., 1., 1., 1., 0., 0., 0., 0., 0., 0., 0.],
       [0., 1., 1., 1., 1., 0., 0., 0., 0., 0., 0., 0.],
       [0., 1., 1., 1., 1., 0., 0., 0., 0., 0., 0., 0.],
       [0., 1., 1., 1., 1., 0., 0., 0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.],
       [0., 0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1.]])

__call__(M): Implements the functor.

__init__(shape, block_shapes, normalized=True, pos=False)

Constructor.

Args:

shape: (tuple(int,int)): the size of the input matrix.
block_shapes: (list[tuple]): the list of tuples defining the lower right corner of successive diagonal blocks (see class description and example).
normalized: (bool): True to normalize the projection image matrix.
pos: (bool): True to ignore negative values (replaced by 0).

class pyfaust.proj.circ(shape, normalized=True, pos=False)

Functor for the CIRC(ulant) projector.

Example:

>>> from pyfaust.proj import circ
>>> import numpy as np
>>> from numpy.random import rand, seed
>>> seed(43) # for reproducibility
>>> M = (rand(5, 5)*10).astype('int').astype('double')
>>> M
array([[1., 6., 1., 2., 3.],
       [8., 6., 5., 0., 7.],
       [3., 8., 2., 0., 8.],
       [2., 4., 3., 0., 8.],
       [8., 9., 3., 9., 4.]])
>>> p = circ(M.shape, normalized=False)
>>> p(M)
array([[2.6, 5.4, 4. , 3.8, 6.2],
       [6.2, 2.6, 5.4, 4. , 3.8],
       [3.8, 6.2, 2.6, 5.4, 4. ],
       [4. , 3.8, 6.2, 2.6, 5.4],
       [5.4, 4. , 3.8, 6.2, 2.6]])

__init__(shape, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): the size of the input matrix.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.const(C, normalized=False)

Functor for the CONST projector. A, the image matrix, is such that A == C.

Example:

>>> from pyfaust.proj import const
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> C = np.round(rand(5,5), decimals=2)
>>> p = const(C)
>>> C
array([[0.79, 0.2 , 0.51, 0.59, 0.05],
       [0.61, 0.17, 0.07, 0.95, 0.97],
       [0.81, 0.3 , 0.1 , 0.68, 0.44],
       [0.12, 0.5 , 0.03, 0.91, 0.26],
       [0.66, 0.31, 0.52, 0.55, 0.18]])
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p(M)
array([[0.79, 0.2 , 0.51, 0.59, 0.05],
       [0.61, 0.17, 0.07, 0.95, 0.97],
       [0.81, 0.3 , 0.1 , 0.68, 0.44],
       [0.12, 0.5 , 0.03, 0.91, 0.26],
       [0.66, 0.31, 0.52, 0.55, 0.18]])

__init__(C, normalized=False)

Args:

C: (np.ndarray): the constant matrix.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.hankel(shape, normalized=True, pos=False)

Functor for the HANKEL projector.

Example:

>>> from pyfaust.proj import hankel
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = hankel(M.shape)
>>> p(M)
array([[0.1613085 , 0.24196275, 0.11771161, 0.28555964, 0.21798446],
       [0.24196275, 0.11771161, 0.28555964, 0.21798446, 0.17220772],
       [0.11771161, 0.28555964, 0.21798446, 0.17220772, 0.13079068],
       [0.28555964, 0.21798446, 0.17220772, 0.13079068, 0.14386974],
       [0.21798446, 0.17220772, 0.13079068, 0.14386974, 0.2005457 ]])

__init__(shape, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): the size of the input matrix.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.normcol(shape, s=1)

Functor for the NORMCOL projector. A, the image matrix, is defined by $\forall j \in \{0,...,shape[1]-1\}$ the j-th column $A_{,j}$ is such that $| A_{,j}|_2 = s$.

Example:

>>> from pyfaust.proj import normcol
>>> from numpy.random import rand, seed
>>> from numpy.linalg import norm
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = normcol(M.shape, .01)
>>> norm(p(M)[:,0], 2)
0.009999999999999998

__init__(shape, s=1)

Args:

shape: (tuple(int,int)): the input matrix shape.
s: (float): the column 2-norm (default to 1).

class pyfaust.proj.normlin(shape, s=1)

Functor for the NORMLIN projector. A, the image matrix, is defined by $\forall i \in \{0,...,shape[0]-1\}$ the i-th row $A_{i,*}$ is such that $\| A_{i,*} \|_2 = s$.

Example:

>>> from pyfaust.proj import normlin
>>> from numpy.random import rand, seed
>>> from numpy.linalg import norm
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = normlin(M.shape, .01)
>>> p(M)
array([[0.00264427, 0.00678935, 0.00521708, 0.00428801, 0.00114347],
       [0.00124552, 0.00046707, 0.00677253, 0.00467071, 0.00552701],
       [0.00015309, 0.00742494, 0.0063533 , 0.00160746, 0.00137782],
       [0.00221263, 0.00368772, 0.00639205, 0.00528573, 0.0035648 ],
       [0.00671873, 0.001542  , 0.00319415, 0.0040753 , 0.00506658]])

__init__(shape, s=1)

Args:

shape: (tuple(int,int)): the input matrix shape.
s: (float): the row 2-norm (default to 1).

class pyfaust.proj.proj_gen(shape)

The parent abstract class to represent projectors (as functors).

__call__(M): Call self as a function.

abstract __init__(shape)

__weakref__: list of weak references to the object (if defined)

class pyfaust.proj.proj_id(shape)

Functor for the identity projector.

This projector simply returns the same array as the one passed as argument.

It’s not useless for example in PALM4MSA (pyfaust.fact.palm4msa, pyfaust.fact.hierarchical) it might serve to avoid any constraint on a factor.

Example:

>>> from pyfaust.proj import proj_id
>>> from numpy import allclose
>>> from numpy.random import rand
>>> M = rand(5,5)
>>> p = proj_id(M.shape)
>>> allclose(p(M), M)
True

__init__(shape)

Args:

shape: (tuple(int,int)): the size of the input matrix.

class pyfaust.proj.skperm(shape, k, normalized=True, pos=False)

Functor for the SKPERM projector.

Example:

>>> from pyfaust.proj import skperm
>>> import numpy as np
>>> from numpy import array
>>> k = 2
>>> M = array([[-0.04440802, -0.17569296, -0.02557815, -0.15559154],                        [-0.0083095,  -3.38725936, -0.78484126, -0.4883618 ],                        [-1.48942563, -1.71787215, -0.84000212, -3.71752454],                        [-0.88957883, -0.19107863, -5.92900636, -6.51064175]])
>>> p = skperm(M.shape, k, normalized=False)
>>> p(M)
array([[-0.04440802,  0.        , -0.02557815,  0.        ],
       [-0.0083095 , -3.38725936,  0.        ,  0.        ],
       [ 0.        , -1.71787215,  0.        , -3.71752454],
       [ 0.        ,  0.        , -5.92900636, -6.51064175]])

Reference:

[1] Quoc-Tung Le, Rémi Gribonval. Structured Support Exploration For Multilayer Sparse Matrix Fac- torization. ICASSP 2021 - IEEE International Conference on Acoustics, Speech and Signal Processing, Jun 2021, Toronto, Ontario, Canada. pp.1-5 hal-03132013.

__init__(shape, k, normalized=True, pos=False)

Projector constructor.

Args:

shape: (tuple(int,int)): the size of the input matrix.
k: (int): the integer sparsity (number of nonzeros) targeted per-row and per-column.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.

pos: (bool) True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.sp(shape, k, normalized=True, pos=False)

Functor for the SP projector.

A, the image matrix, is such that $ | A |_0 = k, | A|_F = 1 $ (if normalized == True).

Example:

>>> from pyfaust.proj import sp
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = sp(M.shape, 3, normalized=False)
>>> p(M)
array([[0.  , 0.95, 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.87, 0.  , 0.  ],
       [0.  , 0.97, 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ]])

__init__(shape, k, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): the size of the input matrix.
k: (int): the number of nonzeros of the projection image.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.spcol(shape, k, normalized=True, pos=False)

Functor for the SPCOL projector.

A, the image matrix, is defined by $\forall j \in \{0,...,shape[1]-1\}$ the j-th column $A_{\star,j}$ is such that $\| A_{\star,j}\|_0 = k, \| A\|_F = 1$ (if normalized == True)

Example:

>>> from numpy.random import rand, seed
>>> from pyfaust.proj import spcol
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = spcol(M.shape, 3, normalized=False)
>>> p(M)
array([[0.37, 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.  , 0.  ],
       [0.18, 0.3 , 0.  , 0.43, 0.29],
       [0.61, 0.  , 0.  , 0.  , 0.46]])

__init__(shape, k, normalized=True, pos=False)

Args:

shape: (tuple(int, int)): shape of the input array.
S: (np.ndarray): the support matrix.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.splin(shape, k, normalized=True, pos=False)

Functor for the SPLIN projector.

A, the image matrix, is defined by $\forall i \in \{0, \ldots,shape[0]-1\}$ the i-th row $A_{i,*}$ is such that $\| A_{i,*}\|_0 = k, \| A\|_F = 1$ (if normalized == True).

Example:

>>> from pyfaust.proj import splin
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = splin(M.shape, 3, normalized=False)
>>> p(M)
array([[0.  , 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.21, 0.  ],
       [0.  , 0.3 , 0.52, 0.43, 0.  ],
       [0.61, 0.  , 0.  , 0.37, 0.46]])

__init__(shape, k, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): shape of the input array.
k: (int): the number of nonzeros of the projection image.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.splincol(shape, k, normalized=True, pos=False)

Functor for the SPLINCOL projector.

It’s the union of SPLIN and SPCOL projectors.

Example:

>>> from pyfaust.proj import splincol, splin, spcol
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p1 = splin(M.shape, 3, normalized=False)
>>> p2 = spcol(M.shape, 3, normalized=False)
>>> p = splincol(M.shape, 3, normalized=False)
>>> p1(M)
array([[0.  , 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.21, 0.  ],
       [0.  , 0.3 , 0.52, 0.43, 0.  ],
       [0.61, 0.  , 0.  , 0.37, 0.46]])
>>> p2(M)
array([[0.37, 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.  , 0.  ],
       [0.18, 0.3 , 0.  , 0.43, 0.29],
       [0.61, 0.  , 0.  , 0.  , 0.46]])
>>> p(M)
array([[0.37, 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.21, 0.  ],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.  , 0.  , 0.37, 0.46]])
>>> p1M = p1(M)
>>> p2M = p2(M)
>>> p1M[p1M == p2M] = 0
>>> p1M+p2M
array([[0.37, 0.95, 0.73, 0.6 , 0.  ],
       [0.  , 0.  , 0.87, 0.6 , 0.71],
       [0.  , 0.97, 0.83, 0.21, 0.  ],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.  , 0.  , 0.37, 0.46]])
>>> (p1M+p2M == p(M)).all()
True

__init__(shape, k, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): shape of the input array.
k: (int): the integer sparsity (number of nonzeros) targeted per-row and per-column.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.spsymm(shape, k, normalized=True, pos=False)

Functor for the SYMM SP projector.

A, the image matrix of M, is such that A is symmetric and $k \le \| A \|_0 \le k + 1, \| A\|_F = 1 $ (if normalized == True), assuming that $\| M \|_0 >= k$.

Example:

>>> from pyfaust.proj import spsymm
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = spsymm(M.shape, 3, normalized=False)
>>> p(M)
array([[0.  , 0.95, 0.  , 0.  , 0.  ],
       [0.95, 0.  , 0.97, 0.  , 0.  ],
       [0.  , 0.97, 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ]])
>>> np.linalg.norm(p(M) - p(M).T) == 0
True
>>> np.count_nonzero(p(M)) == 4
True

__init__(shape, k, normalized=True, pos=False)

Args:

shape: (tuple(int,int)): the size of the input matrix.
k: (int): the number of nonzeros of the projection image. The result might be k+1 nonzeros in case of an odd number of nonzeros on the diagonal.
normalized: (bool): True to normalize the projection image according to its Frobenius norm.
pos: (bool): True to skip negative values (replaced by zero) of the matrix to project.

class pyfaust.proj.sptril(shape, k, normalized=True, pos=False)

Functor for the SPTRIL projector.

A, the image matrix, is such that the upper triangular part is 0 and $\| A \|_0 = k, \| A\|_F = 1$ (if normalized == True).

Example:

>>> from pyfaust.proj import sptril
>>> from numpy.random import rand, seed
>>> import numpy as np
>>> seed(42) # just for reproducibility
>>> M = np.round(rand(5,5), decimals=2)
>>> M
array([[0.37, 0.95, 0.73, 0.6 , 0.16],
       [0.16, 0.06, 0.87, 0.6 , 0.71],
       [0.02, 0.97, 0.83, 0.21, 0.18],
       [0.18, 0.3 , 0.52, 0.43, 0.29],
       [0.61, 0.14, 0.29, 0.37, 0.46]])
>>> p = sptril(M.shape, 3, normalized=False)
>>> p(M)
array([[0.  , 0.  , 0.  , 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ],
       [0.  , 0.97, 0.83, 0.  , 0.  ],
       [0.  , 0.  , 0.  , 0.  , 0.  ],
       [0.61, 0.  , 0.  , 0.  , 0.  ]])
>>> np.linalg.norm(np.triu(p(M), 1)) == 0
True
>>> np.count_nonzero(p(M)) == 3
True