regpy.functionals.base

Classes

AbstractFunctional	An abstract functional that can be called on a vector space to get the corresponding
Functional	Base class for implementation of functionals. Subclasses should at least implement the
LinearFunctional	Linear functionals
SquaredNorm	Functionals of the form
LinearCombination	Linear combination of functionals.
VerticalShift	Shifting a functional by some offset. Should not be used directly but rather by adding some scalar to the functional.
HorizontalShiftDilation	Implements a horizontal shift and/or a horizontal translation of the graph of a functional \(F\), i.e. replaces
Composed	Composition of an operator with a functional \(F\circ O\). This should not be called
FunctionalOnDirectSum	Helper to define Functionals with respective prox-operators on sum spaces (vecsps.DirectSum objects).

Functions

as_functional(→ Functional)

Convert func to Functional instance on vecsp.

Module Contents

class regpy.functionals.base.AbstractFunctional(name)

Bases: AbstractFunctionalBase

An abstract functional that can be called on a vector space to get the corresponding concrete implementation.

AbstractFunctionals provides two kinds of functionality:

• A decorator method register(vecsp_type) that can be used to declare some class or function as the concrete implementation of this abstract functional for vector spaces of type vecsp_type or subclasses thereof, e.g.:

• AbstractFunctionals are callable. Calling them on a vector space and arbitrary optional keyword arguments finds the corresponding concrete regpy.functionals.Functional among all registered implementations. If there are implementations for multiple base classes of the vector space type, the most specific one will be chosen. The chosen implementation will then be called with the vector space and the keyword arguments, and the result will be returned.

@TV.register(vecsps.UniformGridFcts)
class TVUniformGridFcts(HilbertSpace):
    ...

If called without a vector space as positional argument, it returns a new abstract functional with all passed keyword arguments remembered as defaults.

Parameters:

name (str) – A name for this abstract functional. Currently, this is only used in error messages, when no implementation was found for some vector space.

name

args

register(vecsp_type, impl=None)

Register an implementation for a vector-space class.

When impl is omitted, return a decorator that performs the registration.

Parameters:

• vecsp_type (regpy.vecsps.VectorSpaceBase) – Vector Space on which the functional should be registered.

• impl (regpy.functionals.Functional, optional) – Concrete implementation to register. Defaults to None.

Returns:

None for direct registration; otherwise, a registration decorator.

Return type:

None or callable

class regpy.functionals.base.Functional(domain: regpy.vecsps.VectorSpaceBase, h_domain: regpy.hilbert.HilbertSpace = None, is_linear: bool = False, is_quadratic: bool = False, conj_is_quadratic: bool | None = None, is_separable: bool = False, is_convex: bool = True, convexity_param: float = 0.0, Lipschitz: float = inf, dom_l=None, dom_u=None, conj_dom_l=None, conj_dom_u=None, methods: set[str] | None = set(), conj_methods: set[str] | None = set(), is_data_func: bool = False)

Base class for implementation of functionals. Subclasses should at least implement the

_eval : evaluating the functional

and

_subgradient or _linearize : returning a subgradient at x.

The evaluation of a specific functional on some element of the domain can be done by simply calling the functional on that element.

Functionals can be added by taking LinearCombination of them. The domain has to be the same for each functional.

They can also be multiplied by scalars or vector of their respective domain`or multiplied by `regpy.operators.Operator. This leads to a functional that is composed with the operator \(F\circ O\) where \(F\) is the functional and \(O\) some operator. Multiplying by a scalar results in a composition with the PtwMultiplication operator.

Parameters:

• domain (regpy.vecsps.VectorSpaceBase) – The underlying vector space for the function space on which it is defined.

• h_domain (regpy.hilbert.HilbertSpace (default: None)) – The underlying Hilbert space. The proximal mapping, the parameter of strong convexity, and the Lipschitz constant are defined with respect to this Hilbert space. In the default case L2(domain) is used.

• is_convex (bool [default: True]) – If true, the functional should be convex.

• is_linear (bool [default: False]) – If true, the functional should be linear.

• is_quadratic (bool [default: False]) – If true, the functional should be quadratic.

• conj_is_quadratic (bool or None [default: None]) – The corresponding boolean attribute indicates if the conjugate functional is quadratic. If None, the same value as is_quadratic will be used.

• is_separable (bool [default: False]) – If true, the functional should be the sum of functionals acting on only one component of the input vector. In this case, the parameters

• dom_u (self.domain [default:None]) – should not be None, and they should specify the essential domain of the functional by \(\{x in domain: dom_l<=x<=dom_u}\), and the essential domain of the conjugate functional (which is then also separable) by \(\{xstar in domain: conj_dom_l<=xstar <= conj_dom_u\}\). In case of open domains, the boundaries should be shifted in the order of machine precision.

• dom_l (self.domain [default:None]) – should not be None, and they should specify the essential domain of the functional by \(\{x in domain: dom_l<=x<=dom_u}\), and the essential domain of the conjugate functional (which is then also separable) by \(\{xstar in domain: conj_dom_l<=xstar <= conj_dom_u\}\). In case of open domains, the boundaries should be shifted in the order of machine precision.

• conj_dom_u (self.domain [default:None]) – should not be None, and they should specify the essential domain of the functional by \(\{x in domain: dom_l<=x<=dom_u}\), and the essential domain of the conjugate functional (which is then also separable) by \(\{xstar in domain: conj_dom_l<=xstar <= conj_dom_u\}\). In case of open domains, the boundaries should be shifted in the order of machine precision.

• conj_dom_l (self.domain [default:None]) – should not be None, and they should specify the essential domain of the functional by \(\{x in domain: dom_l<=x<=dom_u}\), and the essential domain of the conjugate functional (which is then also separable) by \(\{xstar in domain: conj_dom_l<=xstar <= conj_dom_u\}\). In case of open domains, the boundaries should be shifted in the order of machine precision.

• convexity_param (float [default: 0]) – parameter of strong convexity of the functional. 0 if the functional is not strongly convex.

• Lipschitz (float [default: math.inf]) – Lipschitz continuity constant of the gradient. math.inf the gradient is not Lipschitz continuous.

• methods (set [default: set()]) – names of the methods implemented by a given Functional instance. Subset of {‘eval’, ‘subgradient’, ‘hessian’, ‘proximal’, ‘dist_subdiff’}

• [default (conj_methods set) – names of the methods implemented by the conjugate of a given Functional instance. Subset of {‘eval’, ‘subgradient’, ‘hessian’, ‘proximal’, ‘dist_subdiff’}

• is_data_func (bool [default: False]) – If true, the functional acts as a data functional. In this case it must have a data property with a corresponding setter.

log

domain

The underlying vector space.

h_domain

The underlying Hilbert space.

is_data_func = False

linearize(x)

Bounds the functional from below by a linear functional at x given by the value at that point and a subgradient v such that

\[F(x+ h) \geq F(x) + vdot(v,h) for all h\]

Requires the implementation of either _subgradient or _linearize.

Parameters:

x (in self.domain) – Element at which will be linearized

Returns:

• y – Value of \(F(x)\).

• grad (in self.domain) – Subgradient of \(F\) at \(x\).

subgradient(x, out=None, **subgradient_par)

Return a subgradient of the functional at x.

If out is supplied, the result is written into that vector and the same object is returned. out may coincide with x.

dist_subdiff(vstar, x)

Returns the distance of a vector \(v^*\) to the subdifferential \(\partial F(x)\) at x with respect to the dual norm. Needs to be re-implemented for functionals which are not Gateaux differentiable.

Parameters:

• vstar (in self.domain) – Vector of which the distance is to be determined.

• x (in self.domain) – Point at which the subdifferential is evaluated

hessian(x, recursion_safeguard: bool = False)

The hessian of the functional at x as an regpy.operators.Operator mapping form the functionals domain to it self. It is defined by

\[F(x+h) = F(x) + (\nabla F)(x)^T h + \frac{1}{2} h^T Hess F(x) h + \mathcal{o}(\|h\|^2)\]

Require either the implementation of _hessian or of _hessian_conj and _subgradient

Parameters:

x (self.domain) – Point in domain at which to compute the hessian.

Returns:

`h` – Hessian operator at the point x.

Return type:

regpy.operators.Operator

conj_subgradient(xstar, out=None, **subgradient_par)

Return a subgradient of the conjugate functional.

If out is supplied, the result is written into that vector and the same object is returned. out may coincide with xstar.

conj_hessian(xstar, recursion_safeguard=False)

The hessian of the functional. Should not be called directly, but via self.conj.hessian.

conj_linearize(xstar)

Linearizes the conjugate functional \(F^*\). Should not be called directly, but via self.conj.linearize

proximal(x, tau, recursion_safeguard=False, out=None, **proximal_par)

Proximal operator

\[\mathrm{prox}_{\tau F}(x)=\arg \min _{v\in {\mathcal {X}}}(F(v)+{\frac{1}{2\tau}}\Vert v-x\Vert_{\mathcal {X}}^{2}).\]

Requires either an implementation of _proximal or of _subgradient and _conj_proximal.

Parameters:

• x (array-like) – Vector in the respective domain. Point at which to compute proximal.

• tau (scalar) – Regularization parameter for the proximal.

• out (array-like or None) – If supplied, the result is written into that vector and the same object is returned. out may coincide with x

Returns:

proximal – the computed proximal at \(x\) with parameter \(\tau\).

Return type:

self.domain

conj_proximal(xstar, tau, recursion_safeguard=False, out=None, **proximal_par)

Evaluate the proximal mapping of the conjugate functional.

If out is supplied, the result is written into that vector and the same object is returned. out may coincide with xstar.

as_data_func(data)

shift(v=None, data_shift=None)

Returns the functional \(x\mapsto F(x-v-data)\)

dilation(a)

Returns the functional \(x\mapsto F(ax)\)

property Lipschitz: float

The Lipschitz constant of the derivative of the functional.

property convexity_param: float

The convexity parameter of the functional.

property is_convex: bool

Flag if the functional is convex.

property is_linear: bool

Flag if the functional is linear.

property is_quadratic: bool

Flag if the functional is quadratic.

property conj_is_quadratic: bool

Flag if the conjugate functional is quadratic.

property is_separable: bool

Flag if the functional is separable, i.e. \(F(x)=sum_i f_i(x_i)\)

property dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain.

property dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

property methods

Set of strings of the names of the methods are available for a given Functional instance.

conj()

For linear operators, this is the adjoint as a linear regpy.operators.Operator instance. Will only be computed on demand and saved for subsequent invocations.

Returns:

The adjoint as an regpy.operators.Operator instance.

Return type:

Adjoint

class regpy.functionals.base.LinearFunctional(gradient, domain: regpy.vecsps.VectorSpaceBase = None, h_domain: regpy.hilbert.HilbertSpace = None, gradient_in_dual_space=False)

Bases: Functional

Linear functionals Linear functional given by

\[F(x) = \langel a, x\rangle\]

The operators __add__ , __iadd__ , __mul__ , __imul__ with LinearFunctionals and scalars as other arguments, rsp, are overwritten to yield the expected LinearFunctionals.

Parameters:

• gradient (domain) – The gradient of the linear functional. \(a=gradient\) if gradient_in_dual_space == True

• domain (regpy.vecsps.VectorSpaceBase, optional) – The regpy.vecsps.VectorSpaceBase on which the functional is defined

• h_domain (regpy.hilbert.HilbertSpace (default: L2(domain))) – Hilbert space for proximity operator

• gradient_in_dual_space (bool (default: False)) – If false, the argument gradient is considered as an element of the primal space, and \(a = h_domain.gram(gradient)\).

property gradient

dilation(a)

Returns the functional \(x\mapsto F(ax)\)

shift(v=None, data_shift=None)

Returns the functional \(x\mapsto F(x-v-data)\)

class regpy.functionals.base.SquaredNorm(h_space, a: float = 1.0, b=None, c: float = 0.0, shift=None, data=None)

Bases: Functional

Functionals of the form

\[\mathcal{F}(x) = \frac{a}{2}\|x\|_X^2 +\langle b,x\rangle_X + c\]

Here the linear term represents an inner product in the Hilbert space, not a pairing with the dual space.

The operators __add__ , __iadd__ , __mul__ , __imul__ with SquaredNorms, LinearFunctionals and scalars as other arguments are overwritten to yield the expected SquaredNorms.

Parameters:

• domain (regpy.vecsps.VectorSpaceBase) – The underlying vector space for the function space on which it is defined.

• h_space (regpy.hilbert.HilbertSpace (default: None)) – The underlying Hilbert space.

• a (float [default:1]) – coefficient of quadratic term

• b (h_space.domain [default:None]) – coefficient of linear term. In the default case it is 0.

• c (float [default: 0]) – constant term

• shift (h_space.domain [default:None]) – If not None, then we must have b is None and c==0. In this case the functional is initialized as \(\mathcal{F}(x) = \frac{a}{2}\|x-shift-data\|^2\).

• data (h_space.domain [default:None]) – If not None, then we must have b is None and c==0. In this case the functional is initialized as \(\mathcal{F}(x) = \frac{a}{2}\|x-shift-data\|^2\).

property data

property gram: regpy.operators.Operator

property gram_inv: regpy.operators.Operator

a() → float

b()

c() → float

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property convexity_param

The convexity parameter of the functional.

property is_convex

Flag if the functional is convex.

property conj_is_quadratic

Flag if the conjugate functional is quadratic.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

as_data_func(data)

dilation(dil)

Returns the functional \(x\mapsto F(ax)\)

shift(v=None, data_shift=None)

Returns the functional \(x\mapsto F(x-v-data)\)

class regpy.functionals.base.LinearCombination(*args)

Bases: Functional

Linear combination of functionals.

Parameters:

*args ((scalar, regpy.functionals.Functional) or regpy.functionals.Functional) – List of coefficients and functionals to be taken as linear combinations.

coeffs = []

List of all coefficients

funcs = []

List of all functionals.

linear_table = []

dist_subdiff(vstar, x, **kwargs)

Returns the distance of a vector \(v^*\) to the subdifferential \(\partial F(x)\) at x with respect to the dual norm. Needs to be re-implemented for functionals which are not Gateaux differentiable.

Parameters:

• vstar (in self.domain) – Vector of which the distance is to be determined.

• x (in self.domain) – Point at which the subdifferential is evaluated

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property convexity_param

The convexity parameter of the functional.

property is_quadratic

Flag if the functional is quadratic.

property conj_is_quadratic

Flag if the conjugate functional is quadratic.

property is_convex

Flag if the functional is convex.

property dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain.

property dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

class regpy.functionals.base.VerticalShift(func, offset)

Bases: Functional

Shifting a functional by some offset. Should not be used directly but rather by adding some scalar to the functional.

Parameters:

• func (regpy.functionals.Functional) – Functional to be offset.

• offset (scalar) – Reals offset added to the evaluation of the functional.

func

Functional to be offset.

offset

Offset added to the evaluation of the functional.

dist_subdiff(vstar, x, **kwargs)

Returns the distance of a vector \(v^*\) to the subdifferential \(\partial F(x)\) at x with respect to the dual norm. Needs to be re-implemented for functionals which are not Gateaux differentiable.

Parameters:

• vstar (in self.domain) – Vector of which the distance is to be determined.

• x (in self.domain) – Point at which the subdifferential is evaluated

property is_quadratic

Flag if the functional is quadratic.

property convexity_param

The convexity parameter of the functional.

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property is_convex

Flag if the functional is convex.

property dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain.

property dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

class regpy.functionals.base.HorizontalShiftDilation(func, dilation: float = 1.0, shift=None, data=None)

Bases: Functional

Implements a horizontal shift and/or a horizontal translation of the graph of a functional \(F\), i.e. replaces \(F(x)\) by \(F(dilation(x-shift))\)

Parameters:

• func (Functional) – The functional to be shifted and dilated.

• dilation (float [default: 1]) – Dilation factor.

• shift (self.domain or scalar or None [default: None]) – Shift vector. The default case (None) yields the same results as shift=0, but no zero-additions are performed.

func

dilation = 1.0

Returns the functional \(x\mapsto F(ax)\)

shift_val()

property data

dist_subdiff(vstar, x, **kwargs)

Returns the distance of a vector \(v^*\) to the subdifferential \(\partial F(x)\) at x with respect to the dual norm. Needs to be re-implemented for functionals which are not Gateaux differentiable.

Parameters:

• vstar (in self.domain) – Vector of which the distance is to be determined.

• x (in self.domain) – Point at which the subdifferential is evaluated

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property convexity_param

The convexity parameter of the functional.

property is_convex

Flag if the functional is convex.

property is_linear

Flag if the functional is linear.

property is_quadratic

Flag if the functional is quadratic.

property dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain.

property dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

class regpy.functionals.base.Composed(func: Functional, op: regpy.operators.Operator, op_norm: float = inf, op_lower_bound: float = 0, hessian: Callable | None = None, compute_op_norm: bool = False, norm_kwargs: dict = {}, h_domain: regpy.hilbert.HilbertSpace = None, methods: set[str] | None = None, conj_methods: set[str] | None = None)

Bases: Functional

Composition of an operator with a functional \(F\circ O\). This should not be called directly but rather used by multiplying the Functional object with an regpy.operators.Operator.

Parameters:

• func (regpy.functionals.Functional) – Functional to be composed with.

• op (regpy.operators.Operator) – Operator to be composed with.

• op_norm (float [default: inf]) – Norm of the operator. Used only to define self.Lipschitz

• op_lower_bound (float) – Lower bound of operator: |op(f)|geq op_lower_bound * |f| Used only to define self.convexity_param

• hessian (Callable or None) – If not None (default), this allows to specify a user-defined hessian (e.g., with allowing an inversion or more efficient inversion)

• compute_op_norm (boolean) – If true the op norm will be computed using the norm method of the operator. Will only be computed if op_norm is default value inf.

• norm_kwargs (dict) – possible arguments passed to the operator norm computation.

• h_domain (HilbertSpace or None) – Underlying Hilbert space. Default: None.

op_norm

op_lower_bound = 0

user_defined_hessian = None

func

Functional that is composed with an Operator.

op

Operator composed that is composed with a functional.

property is_linear

Flag if the functional is linear.

property is_quadratic

Flag if the functional is quadratic.

property conj_is_quadratic

Flag if the conjugate functional is quadratic.

property convexity_param

The convexity parameter of the functional.

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property is_convex

Flag if the functional is convex.

class regpy.functionals.base.FunctionalOnDirectSum(funcs: list[Functional], domain: regpy.vecsps.DirectSum | None = None)

Bases: Functional

Helper to define Functionals with respective prox-operators on sum spaces (vecsps.DirectSum objects). The functionals are given as a list of the functionals on the summands of the sum space.

\[F(x_1,... x_n) = \sum_{j=1}^n F_j(x_j)\]

Parameters:

• funcs ([regpy.functionals.Functional, ...]) – List of functionals each defined on one summand of the direct sum of vector spaces.

• domain (regpy.vecsps.DirectSum) – Domain on which the combined functional is defined.

length

Number of the summands in the direct sum domain.

funcs

List of the functionals on each summand of the direct sum domain.

dist_subdiff(vstar, x)

Returns the distance of a vector \(v^*\) to the subdifferential \(\partial F(x)\) at x with respect to the dual norm. Needs to be re-implemented for functionals which are not Gateaux differentiable.

Parameters:

• vstar (in self.domain) – Vector of which the distance is to be determined.

• x (in self.domain) – Point at which the subdifferential is evaluated

property is_linear

Flag if the functional is linear.

property is_quadratic

Flag if the functional is quadratic.

property conj_is_quadratic

Flag if the conjugate functional is quadratic.

property convexity_param

The convexity parameter of the functional.

property Lipschitz

The Lipschitz constant of the derivative of the functional.

property is_convex

Flag if the functional is convex.

property dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain.

property dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain.

property conj_dom_l

For a separable functional, this is the pointwise lower boundary of the essential domain of the conjugate functional.

property conj_dom_u

For a separable functional, this is the pointwise upper boundary of the essential domain of the conjugate functional.

regpy.functionals.base.as_functional(func: regpy.hilbert.HilbertSpace | regpy.operators.Operator | Functional, vecsp: regpy.vecsps.VectorSpaceBase) → Functional

Convert func to Functional instance on vecsp.

• If func is a HilbertSpace then it generated the SquaredNorm.

• If func is an Operator, it’s wrapped in a GramHilbertSpace and then SquaredNorm functional.

• If func is callable, e.g. an hilbert.AbstractSpace or AbstractFunctional, it is called on vecsp to construct the concrete functional or Hilbert space. In the later case the functional will be the SquaredNorm

Parameters:

• func (Functional or HilbertSapce or regpy.operators.Operator or callable) – Functional or object from which to construct the Functional.

• vecsp (regpy.vecsps.VectorSpaceBase) – Underlying vector space for the functional.

Returns:

Constructed Functional on the underlying vectorspace.

Return type:

Functional