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:
  1. Find the index of the set where the point x lies.
  2. Evaluate the function over the set determined by given index.
If the point lies outside of the union, the result is NaN. Notes:

Outputs

  1. x is not contained in any set of the union: fval = ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval1.png vector of NaNs, where ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval2.png is the range of the function, feasible = false, idx = [] , tb_value = [].
  2. x is in a single set: fval = ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval3.png vector of function values, feasible = true, idx = index of the set which contains x, tb_value = [].
  3. x is contained in multiple sets (either at the boundary or in strict interior if there are overlaps), no tie-breaking (default): fval = ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval4.png matrix of function values (../../../../../../fig/mpt/modules/geometry/unions/@Union/feval5.png denotes the number of sets which contain ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval6.png), each column contains the value of function_name in the corresponding set, feasible = true, idx = ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval7.png vector of indices of sets which contain x, tb_value = [].
  4. x is contained in multiple sets (either at the boundary or in strict interior if there are overlaps), tie-breaking enabled (see below): fval = ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval8.png 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: 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 ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval9.png matrix, where ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval10.png 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:

  • 1
  • 0

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 ../../../../../../fig/mpt/modules/geometry/unions/@Union/feval11.png 
      
 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

../../../../../../fig/mpt/modules/geometry/unions/@Union/feval_img_1.png

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