Functionals

Module: pycsou.core.functional

Abstract classes for functionals.

Functional(dim[, data, is_differentiable, …])

Base class for functionals.

DifferentiableFunctional(dim[, data, …])

Base class for differentiable functionals.

ProximableFunctional(dim[, data, …])

Base class for proximable functionals.
class Functional(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_differentiable: bool = False, is_linear: bool = False)[source]

Bases: pycsou.core.map.Map

Base class for functionals.

Notes

Functionals are (real) single-valued nonlinear maps.

__init__(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_differentiable: bool = False, is_linear: bool = False)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

  • is_linear (bool) – Whether the functional is linear or not.

class DifferentiableFunctional(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_linear: bool = False, lipschitz_cst: float = inf, diff_lipschitz_cst: float = inf)[source]

Bases: pycsou.core.functional.Functional, pycsou.core.map.DifferentiableMap

Base class for differentiable functionals.

__init__(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_linear: bool = False, lipschitz_cst: float = inf, diff_lipschitz_cst: float = inf)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • lipschitz_cst (float) – Lispchitz constant of the differentiable map if it exists/is known. Default to \(+\infty\).

  • diff_lipschitz_cst (float) – Lispchitz constant of the derivative of the differentiable map if it exists/is known. Default to \(+\infty\).

abstract jacobianT(arg: Union[numbers.Number, numpy.ndarray]) → Union[numbers.Number, numpy.ndarray][source]

Transpose of the Jacobian matrix of the differentiable map evaluated at arg.

Parameters

arg (Union[Number, np.ndarray]) – Point at which the transposed Jacobian matrix is evaluated.

Returns

Linear operator associated to the transposed Jacobian matrix.

Return type

LinearOperator

class LinearFunctional(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, dtype: type = <class 'numpy.float64'>, is_explicit: bool = False, is_dense: bool = False, is_sparse: bool = False, is_dask: bool = False)[source]

Bases: pycsou.core.functional.Functional, pycsou.core.linop.LinearOperator

Base class for linear functionals.

__init__(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, dtype: type = <class 'numpy.float64'>, is_explicit: bool = False, is_dense: bool = False, is_sparse: bool = False, is_dask: bool = False)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

  • is_linear (bool) – Whether the functional is linear or not.

class ProximableFunctional(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_differentiable: bool = False, is_linear: bool = False)[source]

Bases: pycsou.core.functional.Functional

Base class for proximable functionals.

Any instance/subclass of this class must at least implement the abstract methods __call__ and prox.

Notes

A functional \(f:\mathbb{R}^N\to \mathbb{R}\) is said proximable is its proximity operator ([ProxAlg] Section 1.1)

\[\mathbf{\text{prox}}_{\tau f}(\mathbf{z}):=\arg\min_{\mathbf{x}\in\mathbb{R}^N} f(x)+\frac{1}{2\tau} \|\mathbf{x}-\mathbf{z}\|_2^2, \quad \forall \mathbf{z}\in\mathbb{R}^N,\]

admits a simple closed-form expression or can be evaluated efficiently and with high accuracy.

This class supports the following arithmetic operators +, -, *, @, ** and /, implemented with the class methods __add__/__radd__, __sub__/__neg__, __mul__/__rmul__, __matmul__, __pow__, __truediv__. Such arithmetic operators can be used to add, substract, scale, compose, exponentiate or evaluate LinearOperator instances. For the following basic operations moreover, the proximal operator is automatically updated according to the formula of [ProxAlg] Section 2.2.:

  • Postcomposition: \(g(\mathbf{x})=\alpha f(\mathbf{x})\),

  • Precomposition: \(g(\mathbf{x})= f(\alpha\mathbf{x}+b)\) or \(g(\mathbf{x})= f(U\mathbf{x})\) with \(U\) a unitary operator,

  • Affine Sum: \(g(\mathbf{x})= f(\mathbf{x})+\mathbf{a}^T\mathbf{x}.\)

Examples

>>> from pycsou.func.penalty import L1Norm
>>> func = L1Norm(dim=10)
>>> x = np.arange(10); tau=0.1
>>> np.allclose((2 * func).prox(x, tau), func.prox(x, 2 * tau))
True
>>> np.allclose((func * 2).prox(x, tau), func.prox(x * 2, 4 * tau)/2)
True
>>> np.allclose(func.shifter(x/2).prox(x, tau), func.prox(x+x/2, tau)-x/2)
True
__init__(dim: int, data: Union[None, numbers.Number, numpy.ndarray] = None, is_differentiable: bool = False, is_linear: bool = False)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

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

Evaluate the proximity operator of the tau-scaled functional at the point x.

Parameters

  • x (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • tau (Number) – Scale.

Returns

Evaluation of the proximity operator of the tau-scaled functional at the point x.

Return type

Union[Number, np.ndarray]

fenchel_prox(z: Union[numbers.Number, numpy.ndarray], sigma: numbers.Number) → Union[numbers.Number, numpy.ndarray][source]

Evaluate the proximity operator of the sigma-scaled Fenchel conjugate of the functional at a point z.

Parameters

  • z (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • sigma (Number) – Scale.

Returns

Result of the evaluation.

Return type

Union[Number, np.ndarray]

Notes

The Fenchel conjugate is defined as [FuncSphere] Chapter 7, Section 1:

\[f^\ast(\mathbf{z}):=\max_{\mathbf{x}\in\mathbb{R}^N} \langle \mathbf{x},\mathbf{z} \rangle - f(\mathbf{x}).\]

From Moreau’s identity, its proximal operator is given by:

\[\mathbf{\text{prox}}_{\sigma f^\ast}(\mathbf{z})= \mathbf{z}- \sigma \mathbf{\text{prox}}_{f/\sigma}(\mathbf{z}/\sigma).\]
shifter(shift: Union[numbers.Number, numpy.ndarray]) → pycsou.core.functional.ProxFuncPreComp[source]

Returns a shifted version of the functional.

Parameters

shift (Union[Number, np.ndarray]) – Shift vector.

Returns

Shifted map.

Return type

ProxFuncPreComp

class ProxFuncPostComp(prox_func: pycsou.core.functional.ProximableFunctional, scale: numbers.Number, shift: numbers.Number)[source]

Bases: pycsou.core.functional.ProximableFunctional

__init__(prox_func: pycsou.core.functional.ProximableFunctional, scale: numbers.Number, shift: numbers.Number)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

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

Evaluate the proximity operator of the tau-scaled functional at the point x.

Parameters

  • x (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • tau (Number) – Scale.

Returns

Evaluation of the proximity operator of the tau-scaled functional at the point x.

Return type

Union[Number, np.ndarray]

class ProxFuncAffineSum(prox_func: pycsou.core.functional.ProximableFunctional, linear_part: pycsou.core.functional.LinearFunctional, intercept: numbers.Number)[source]

Bases: pycsou.core.functional.ProximableFunctional

__init__(prox_func: pycsou.core.functional.ProximableFunctional, linear_part: pycsou.core.functional.LinearFunctional, intercept: numbers.Number)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

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

Evaluate the proximity operator of the tau-scaled functional at the point x.

Parameters

  • x (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • tau (Number) – Scale.

Returns

Evaluation of the proximity operator of the tau-scaled functional at the point x.

Return type

Union[Number, np.ndarray]

class ProxFuncPreComp(prox_func: pycsou.core.functional.ProximableFunctional, scale: Union[numbers.Number, numpy.ndarray], shift: Union[numbers.Number, numpy.ndarray])[source]

Bases: pycsou.core.functional.ProximableFunctional

__init__(prox_func: pycsou.core.functional.ProximableFunctional, scale: Union[numbers.Number, numpy.ndarray], shift: Union[numbers.Number, numpy.ndarray])[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

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

Evaluate the proximity operator of the tau-scaled functional at the point x.

Parameters

  • x (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • tau (Number) – Scale.

Returns

Evaluation of the proximity operator of the tau-scaled functional at the point x.

Return type

Union[Number, np.ndarray]

class ProxFuncPreCompUnitOp(prox_func: pycsou.core.functional.ProximableFunctional, unitary_op: pycsou.core.linop.UnitaryOperator)[source]

Bases: pycsou.core.functional.ProximableFunctional

__init__(prox_func: pycsou.core.functional.ProximableFunctional, unitary_op: pycsou.core.linop.UnitaryOperator)[source]
Parameters

  • dim (int,) – Dimension of the functional’s domain.

  • data (Union[None, Number, np.ndarray]) – Optional data vector.

  • is_linear (bool) – Whether the functional is linear or not.

  • is_differentiable (bool) – Whether the functional is differentiable or not.

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

Evaluate the proximity operator of the tau-scaled functional at the point x.

Parameters

  • x (Union[Number, np.ndarray]) – Point at which to perform the evaluation.

  • tau (Number) – Scale.

Returns

Evaluation of the proximity operator of the tau-scaled functional at the point x.

Return type

Union[Number, np.ndarray]