feval
Purpose
Evaluates a given function defined over a union of convex sets.
Syntax
fval = U.feval(x)
fval = U.feval(x, function_name)
[fval, feasible, idx, tb_value] = U.feval(x, function_name)
[fval, feasible, idx, tb_value] = feval(U, x, function_name)
Description
Evaluates function for a given value of the point x over the union of convex sets U characterized
by the name function_name. If the string function_name is omitted, it is assumed that only one
function is attached to the union.
The dimension of the vector x must be the same as the dimension of all sets in the union.
The evaluation is based on the following approach:
- Find the index of the set where the point x lies.
- Evaluate the function over the set determined by given index.
If the point lies outside of the union, the result is NaN.
Notes:
-
U must be a single union. Arrays of unions are not accepted. Use
array.forEach(@(e) e.feval(...)) to evaluate arrays of unions.
-
function_name must refer to a single function. If omitted, U.feval(x)
only works if the union has a single function.
Outputs
-
x is not contained in any set of the union:
fval =
vector of NaNs, where
is the range of the function,
feasible = false,
idx = [] ,
tb_value = [].
-
x is in a single set:
fval =
vector of function values,
feasible = true,
idx = index of the set which contains x,
tb_value = [].
-
x is contained in multiple sets (either at the boundary or in
strict interior if there are overlaps), no tie-breaking (default):
fval =
matrix of function values (
denotes the number of
sets which contain
), each column contains the value of function_name
in the corresponding set,
feasible = true,
idx =
vector of indices of sets which contain x,
tb_value = [].
-
x is contained in multiple sets (either at the boundary or in
strict interior if there are overlaps), tie-breaking enabled (see
below):
fval =
vector containing the function value in the set in
which value of the tie-breaking function is smallest (if there
are multiple sets with the same tie-breaking value, the first
such set is considered),
feasible = true,
idx = index of the set which contains x and, simultaneously, has
the smallest value of the tie-breaking function,
tb_value = scalar value of the tie-breaking function in set indexed
by idx.
Tie-breaking
The purpose of tie-breaking is to automatically resolve situations
where the evaluation point x is contained in multiple sets. With
tie-breaking enabled Union/feval() evaluates the tie-breaking function
to decide which set containing x should be used for evaluation of
the original function.
The tie-breaking function can be specified by U.feval(x, 'tiebreak',
tb_fun), where tb_fun can be either a string or a function
handle. A string value must refer to an another function which exists
in the union U.
A typical case where tie-breaking is useful is evaluation of
discontinuous MPC feedback laws:
uopt = U.feval(x, 'primal', 'tiebreak', 'obj')
Here, if x is contained in multiple sets, then the function primal
is only evaluated in the set which contain x and simultaneously has
the smallest value of the tie-breaking function obj.
A special case of tie-breaking is the "first-set" rule where we are
only interested in evaluating a function in the first set which
contains x (despite the fact there can be multiple such sets). This
is achieved by
fval = U.feval(x, 'function_name', 'tiebreak', @(x) 0)
Notes:
- Tie-breaking functions must be scalar-valued.
- No tie-breaking is done by default.
Evaluation in particular sets
fval = U.feval(x, 'myfun', 'regions', indices) evaluates function
myfun over all sets indexed by indices. The output fval is
always an
matrix, where
is the cardinality of indices.
Note that once the regions option is enabled, Union/feval() will not
perform point location. Instead, it will evaluate the function in all
sets indexed by indices, regardless of whether they contain x or
not.
The regions option allows to quickly evaluate multiple functions as
follows:
[first_value, idx] = U.feval(x, 'first_function')
second_value = U.feval(x, 'second_function', 'regions', idx)
In the second call, Union/feval will only evaluate second_function
in sets specified by the indices option, hence skipping expensive
point location.
Input Arguments
U |
Union of convex sets derived from the ConvexSet class, e.g. Polyhedron, YSet, ...
Class: Union
|
x |
A point at which the function should be evaluated. The point must be given as a column
real vector with the same dimension as the convex set.
Class: double
|
function_name |
Name of the function to evaluate. The string must match one of the stored function names.
If there is only one function attached, this argument can be omitted.
Class: char
|
Output Arguments
fval |
Function value at the point x over the union of convex sets U.
Class: double
|
feasible |
Logical value indicating if the point x is contained in the union or not.
Class: logical Allowed values:
|
idx |
Vector of indices of sets that contain the point x.
Class: double
|
tb_value |
Value of the tie-breaking function if the point belongs to multiple sets.
Class: double
|
Example(s)
Example
1
PWA function over two Yalmip sets and polyhedron x = sdpvar(2,1);
A = [1 -0.2; 0.4 -1];
F = [ norm(A*x-[1;1])<=2; [1 -2]*x<=0.4 ];
G = [ [1 -2]*x>=0.4; -1.5<= x <=1.5 ];
Create YSet objects out of Yalmip constraints. Y(1) = YSet(x,F);
Y(2) = YSet(x,G);
Add two functions "a" and "b" to the sets. Y.addFunction(AffFunction([1,-0.4],-1),'a');
Y.addFunction(AffFunction(3*eye(2),[-1;1]),'b');
Create the Union object. U = Union(Y);
Add an affine set to the union P = Polyhedron('Ae',[0 1],'be',-1.5)
Affine set with 1 equations in R^2
P.addFunction(AffFunction([-0.6, 0.5], 0.8),'a');
P.addFunction(AffFunction(eye(2)),'b');
U.add(P);
Evaluate function "a" for the point
v = [1;1];
y1 = U.feval(v,'a')
y1 =
-0.4
Plot the sets to see the union. U.plot('color','lightgreen');
Plotting...
26 of 40

Assume that we provide a point that lies in two sets, for instance [1;-1.5] y2 = U.feval([1;-1.5],'b')
y2 =
2 1
-3.5 -1.5
The output is a matrix because this point is contained in two sets. In particular, it lies exactly
on the boundary of those sets. If we want just one output, we specify a tie-breaking function. Evaluate the function 'b' with respect to a tie-breaking function 'a'. y3 = U.feval([1;-1.5],'b','tiebreak','a')
y3 =
1
-1.5
See Also
fplot
© 2010-2013 Martin Herceg: ETH Zurich, herceg@control.ee.ethz.ch
© 2003-2013 Michal Kvasnica: STU Bratislava, michal.kvasnica@stuba.sk