Proximal Operators¶

Module: pycsou.math.prox

Common proximal/projection operators.

Functions

`sign`(x)	Sign function.
`soft`(x, tau)	Soft thresholding operator.

Projections

`proj_l1_ball`(x, radius)	Orthogonal projection onto the \(\ell_1\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \\|\mathbf{x}\\|_1\leq \text{radius}\}\).
`proj_l2_ball`(x, radius)	Orthogonal projection onto the \(\ell_2\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \\|\mathbf{x}\\|_2\leq \text{radius}\}\).
`proj_linfty_ball`(x, radius)	Orthogonal projection onto the \(\ell_\infty\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \\|\mathbf{x}\\|_\infty\leq \text{radius}\}\).
`proj_nonnegative_orthant`(x)	Orthogonal projection on the non negative orthant.
`proj_segment`(x[, a, b])	Orthogonal projection into a real segment.

sign(x: Union[numpy.ndarray, numbers.Number]) → Union[numpy.ndarray, numbers.Number][source]¶

Sign function.

The sign function is defined as:

\[\begin{split}sign(x)=\begin{cases} \frac{\bar{x}}{|x|} & x\in\mathbb{C}\backslash\{0\},\\ 0 & \text{if} \,x=0. \end{cases}\end{split}\]

We have in particular: \(sign(x)x=|x|.\)

Parameters: x (Union[np.ndarray, Number]) – Input array.
Returns: An array whose entries are given by the signs of the entries of x.
Return type: Union[np.ndarray, Number]

Examples

>>> x = np.linspace(-1, 1, 5)
>>> sign(x)
array([-1., -1.,  0.,  1.,  1.])
>>> np.allclose(sign(x) * x, np.abs(x))
True
>>> x = x + 1j
>>> np.allclose(sign(x) * x, np.abs(x))
True

soft(x: Union[numpy.ndarray, numbers.Number], tau: numbers.Number) → Union[numpy.ndarray, numbers.Number][source]¶

Soft thresholding operator.

The soft thresholding operator is defined as:

\[\text{soft}_\tau(x)(x)=\max\{|x|-\tau, 0\} \text{sign}(x), \quad x\in\mathbb{C},\]

where \(\tau\geq 0\) and \(sign:\mathbb{C}\rightarrow \{-1,1,0\}\) is the sign function (see sign()).

Parameters

x (Union[np.ndarray, Number]) – Input array.
tau (Number) – Threshold value.

Returns

Array x with element-wise soft thresholded entries.

Return type

Union[np.ndarray, Number]

Examples

>>> x = np.linspace(-1, 1, 5)
>>> soft(x, tau=0.5)
array([-0.5, -0. ,  0. ,  0. ,  0.5])
>>> x = 3 + 1j
>>> soft(x, tau=0.1)
(2.905131670194949-0.9683772233983162j)

Notes

The soft thresholding operator is the proximal operator of the \(\ell_1\) norm. See L1Norm.

proj_l1_ball(x: numpy.ndarray, radius: numbers.Number) → numpy.ndarray[source]¶

Orthogonal projection onto the \(\ell_1\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \|\mathbf{x}\|_1\leq \text{radius}\}\).

Parameters

x (np.ndarray) – Vector to be projected.
radius (Number) – Radius of the \(\ell_1\)-ball.

Returns

Projection of x onto the \(\ell_1\)-ball.

Return type

np.ndarray

Examples

>>> x = np.linspace(-1, 1, 5)
>>> proj_l1_ball(x, radius=2)
array([-0.75, -0.25,  0.  ,  0.25,  0.75])
>>> np.linalg.norm(proj_l1_ball(x, radius=2), ord=1)
2.0

Notes

The projection onto the \(\ell_1\)-ball is described in [ProxAlg] Section 6.5.2. Note that this is also the proximal operator of the \(\ell_1\)-ball functional L1Ball().

proj_l2_ball(x: numpy.ndarray, radius: numbers.Number) → numpy.ndarray[source]¶

Orthogonal projection onto the \(\ell_2\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \|\mathbf{x}\|_2\leq \text{radius}\}\).

Parameters

x (np.ndarray) – Vector to be projected.
radius (Number) – Radius of the \(\ell_2\)-ball.

Returns

Projection of x onto the \(\ell_2\)-ball.

Return type

np.ndarray

Examples

>>> x = np.linspace(-2, 2, 5)
>>> np.allclose(proj_l2_ball(x, radius=1), x/np.linalg.norm(x))
True
>>> np.linalg.norm(proj_l2_ball(x, radius=1), ord=2)
1.0

Notes

Note that this is also the proximal operator of the \(\ell_2\)-ball functional L2Ball().

proj_linfty_ball(x: numpy.ndarray, radius: numbers.Number) → numpy.ndarray[source]¶

Orthogonal projection onto the \(\ell_\infty\)-ball \(\{\mathbf{x}\in\mathbb{R}^N: \|\mathbf{x}\|_\infty\leq \text{radius}\}\).

Parameters

x (np.ndarray) – Vector to be projected.
radius (Number) – Radius of the \(\ell_\infty\)-ball.

Returns

Projection of x onto the \(\ell_\infty\)-ball.

Return type

np.ndarray

Examples

>>> x = np.linspace(-2, 2, 5)
>>> proj_linfty_ball(x, radius=2)
array([-2., -1.,  0.,  1.,  2.])
>>> np.linalg.norm(proj_linfty_ball(x, radius=2), ord=np.inf)
2.0

Notes

Note that this is also the proximal operator of the \(\ell_\infty\)-ball functional LInftyBall().

proj_nonnegative_orthant(x: numpy.ndarray) → numpy.ndarray[source]¶

Orthogonal projection on the non negative orthant.

Parameters: x (np.ndarray) – Vector to be projected.

Examples

>>> x = np.linspace(-1, 1, 2)
>>> proj_nonnegative_orthant(x)
array([0., 1.])

Returns: Projection onto non negative orthant: negative entries of x are set to zero.
Return type: np.ndarray

Notes

This is also the proximal operator of the indicator functional NonNegativeOrthant().

proj_segment(x: numpy.ndarray, a: numbers.Number = 0, b: numbers.Number = 1) → numpy.ndarray[source]¶

Orthogonal projection into a real segment.

Parameters

x (np.ndarray) – Vector to be projected.
a (Number) – Left endpoint of the segement.
b (Number) – Right endpoint of the segment.

Examples

>>> x = np.linspace(-3, 3, 5)
>>> proj_segment(x, a=-2,b=1)
array([-2. , -1.5,  0. ,  1. ,  1. ])

Returns: Projection onto non negative orthant: negative entries of x are set to zero.
Return type: np.ndarray

Notes

This is also the proximal operator of the indicator functional Segment().