convex_function#

base_convex_functions#

class fenics_optim.convex_function.base_convex_function.ConvexFunction(expr, parameters=None, interp_type='quadrature', quadrature_scheme=None, degree=None, measure=None, on_facet=False)#

A composite convex function which acts by default as a MeshConvexFunction.

Parameters

  • expr (UFL expression) – UFL linear expression on which the convex function acts

  • parameters (dict, optional) – convex function parameters (e.g. radius of a norm ball), by default None

  • symmetric (bool, optional) – specify if tensors must be considered symmetric or not, by default True

  • interp_type (str, optional) – interpolation type of auxiliary variables, by default “quadrature”

  • quadrature_scheme ({"default", "vertex", "lobatto"}) – quadrature scheme for numerical quadrature and auxiliary variable discretization, by default “default”, “vertex” scheme available for degree 1 only.

  • degree (int, optional) – quadrature scheme degree, by default 1

  • measure (dolfin.Measure, optional) – integration measure, by default Measure(“dx”)

  • on_facet (bool, optional) – specify whether the function lives on facets, by default False

add_eq_constraint(Az, b=0, name=None)#

Add an equality constraint \(Az=b\).

z can contain a linear combination of X and local variables.

Parameters

  • Az (UFL expression) – a UFL linear combination of X and local variables defining the linear constraint. We still support expressing Az as a list of linear expressions of X and local variable blocks. Use 0 or None for an empty block.

  • b (float, expression) – corresponding right-hand side

  • name (str, optional) – Lagrange-multiplier name for later retrieval.

add_global_var(V, cone=None, ux=None, lx=None)#

Add a (list of) global optimization variable.

These variables are added to the block structure of the optimization problem by following their order of declaration.

Parameters

  • V ((list of) FunctionSpace) – variable FunctionSpace

  • cone (Cone, list of Cone) – cone in which each variable belongs (None if no constraint)

  • ux (float, Function) – upper bound on variable \(x\leq u_x\)

  • lx (float, Function) – lower bound on variable \(l_x\leq x\)

add_ineq_constraint(Az, bu=None, bl=None, name=None)#

Add an inequality constraint \(b_l \leq Az \leq b_u\).

z can contain a linear combination of X and local variables.

Parameters

  • Az (UFL expression) – a UFL linear combination of X and local variables defining the linear constraint. We still support expressing Az as a list of linear expressions of X and local variable blocks. Use 0 or None for an empty block.

  • b_l (float, expression) – corresponding lower bound. Ignored if None.

  • b_u (float, expression) – corresponding upper bound. Ignored if None

  • name (str, optional) – Lagrange-multiplier name for later retrieval.

add_var(dim=0, cone=None, ux=None, lx=None, name=None)#

Add a (list of) auxiliary optimization variable.

These variables are local and their interpolation is defined through the chosen quadrature scheme. They are added to the block structure of the optimization problem by following their order of declaration. Inside a ConvexFunction, the block structure is \(z=[X, Y_0, Y_1, \ldots, Y_n]\) where \(X\) is the global declared variable and each \(Y_i\) are the additional variables.

Parameters

  • dim (int, list of int) – dimension of each variable (0 for a scalar)

  • cone (Cone, list of Cone) – cone in which each variable belongs (None if no constraint)

  • ux (float, Function) – upper bound on variable \(x\leq u_x\)

  • lx (float, Function) – lower bound on variable \(x\leq l_x\)

  • name (str) – variable name

compute_cellwise()#

Compute the value of int f*dx per cell.

conic_repr(X, *args)#

Conic representation of the function f(X).

get_dimension(x)#

Compute the dimension of the abstract expression, stored in dim_x.

set_linear_term(cz)#

Add a linear combination term of X and local variables.

Parameters

cz (UFL expression) – a UFL linear combination of X and local variables defining the linear objective. We still support expressing Az as a list of linear expressions of \(z\)-blocks. Use 0 or None for an empty block.

set_term(expr, *args)#

Define on which expression of \(x\) operates the convex function.

A fictitious variable \(X\) is then substituted to the expression when defining the function conic representation.

Parameters

  • expr – expression of the optimization variable \(x\) on which acts the convex function. expr must be a (list of) linear operation on \(x\) or a SumExpr of \(x\) and a constant term \(x_0\).

  • defined. (Optional parameters can be) –

class fenics_optim.convex_function.base_convex_function.SumExpr(X, X0)#

Handle the sum of a variable and a constant expression.

Parameters

  • X (UFL expression) – variable expression

  • X0 (UFL expression) – constant expression

simple_terms#

class fenics_optim.convex_function.simple_terms.EqualityConstraint(x, b=0, **kwargs)#

Impose a linear equality constraint \(X = b\).

conic_repr(X, b)#

Conic representation of the function f(X).

class fenics_optim.convex_function.simple_terms.InequalityConstraint(x, bl=None, bu=None, **kwargs)#

Impose a linear inequality constraint \(bl <= X <= bu\).

conic_repr(X, bl, bu)#

Conic representation of the function f(X).

class fenics_optim.convex_function.simple_terms.LinearTerm(x, c, **kwargs)#

Define the linear function \(c^TX\).

conic_repr(X, c)#

Conic representation of the function f(X).

class fenics_optim.convex_function.simple_terms.QuadOverLin(expr, parameters=None, interp_type='quadrature', quadrature_scheme=None, degree=None, measure=None, on_facet=False)#

Define the quadratic over linear function \(X=(t,y) o y^T y/t\).

Parameters

X (UFL expression) – optimization variable

conic_repr(X)#

Conic representation of the function f(X).

class fenics_optim.convex_function.simple_terms.QuadraticTerm(x, Q=1, x0=0, **kwargs)#

Define the quadratic function \(\frac{1}{2}(X-x_0)^TQ^TQ(X-x_0)\).

Parameters

  • x (UFL expression) – optimization variable

  • Q (matrix) – Cholesky matrix

  • x0 (UFL expression) – constant term

conic_repr(X, Q, x0)#

Conic representation of the function f(X).

norms#

class fenics_optim.convex_function.norms.AbsValue(x, k=1, **kwargs)#

Define the scaled absolute value function \(k|X|\).

class fenics_optim.convex_function.norms.L1Ball(x, k=1, **kwargs)#

.Defines the scaled L1-ball constraint \(||X||_1 \leq k\).

class fenics_optim.convex_function.norms.L1Norm(x, k=1, **kwargs)#

Define the scaled L1-norm function \(k||X||_1\).

class fenics_optim.convex_function.norms.L2Ball(x, k=1, **kwargs)#

Define the scaled L2-ball constraint \(||X||_2 \leq k\).

class fenics_optim.convex_function.norms.L2Norm(x, k=1, **kwargs)#

Define the scaled L2-norm function \(k||X||_2\).

class fenics_optim.convex_function.norms.LinfBall(x, k=1, **kwargs)#

Defines the scaled Linf-ball constraint \(||X||_\infty \leq k\).

class fenics_optim.convex_function.norms.LinfNorm(x, k=1, **kwargs)#

Define the scaled Linf-norm function \(k||X||_\infty\).

perspective#

class fenics_optim.convex_function.perspective.Perspective(f, t, t0=0)#

Perspective \(\text{persp}_f\) of a convex function \(f(x)\).

\(\text{persp}_f(x, t) = t\cdot f(x/t)\)

Optional: if a constant \(t_0\) is given, then we have:

\(\text{persp}_f(x, t+t_0) = (t+t_0)\cdot f(x/(t+t_0))\)

epigraph#

class fenics_optim.convex_function.epigraph.Epigraph(f, t, t0=0)#

Epigraph constraint \((x,t)\in \text{epi} f\) of \(f(x)\).

\((x, t) \in \text{epi} f \Leftrightarrow f(x) \leq t\)

Optional: if a constant \(t_0\) is given, then we have:

\((x, t+t_0) \in \text{epi} f\)

infconvolution#

class fenics_optim.convex_function.infconvolution.InfConvolution(f1, f2, indices=None)#

Inf-convolution \(f_1 \square f_2\) of \(f_1(x)\) and \(f_2(x)\).

\(f_1 \square f_2(x) = \inf_{{y_1,y_2}} f_1(y_1)+f_2(y_2)\)

such that \(x=y_1+y_2\)

Optional: if a list of indices \(I\) is given, the inf-convolution is done only partially on the corresponding indices for the first function

\(f_1 \square f_2(x) = \inf_{{y_1,y_2}} f_1(y_1, x_j)+f_2(y_2)\)

where \(x=(x_i, x_j)=(y_1+y_2, x_j)\) with \(i\in I, j\not \in I\)

marginal#

class fenics_optim.convex_function.marginal.Marginal(f, A, expr)#

Marginal \(f \setminus A\) of \(f(y)\) through a linear operator \(A\).

\(f \setminus A(x) = \inf_{{y}} f(y)\)

such that \(x=Ay\).

class fenics_optim.convex_function.marginal.Marginals(f, A_list, expr, c_list=None, lagrange_multiplier_name=None)#

Generalized marginal operator.

\(f \setminus \{{A_i,c_i\}}(x) = \inf_{{y_i}} \sum_i c_i f(y_i)\)

such that \(x=\sum_i A_i y_i\).

Parameters

  • f (ConvexFunction) – the original convex function. It can be defined using a dummy variable if needed.

  • A_list (list) – a list of linear operators

  • expr (UFL expression) – the UFL expression for the variable \(x\)

  • c_list (list, optional) – a list of positive coefficients

  • lagrange_multiplier_name (str, optional) – the Lagrange multiplier name corresponding to the coupling constraint, by default None