feval

Purpose

Evaluates a given function defined over a union of polyhedra.

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 polyhedra 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 the PolyUnion. If the point lies outside of the union, the result is NaN. Notes:

Outputs

  1. x is not contained in any polyhedron of the union: fval = ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval1.png vector of NaNs, where ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval2.png is the range of the function, feasible = false, idx = [] , tb_value = [].
  2. x is in a single polyhedron: fval = ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval3.png vector of function values, feasible = true, idx = index of the set which contains x, tb_value = [].
  3. x is contained in multiple polyhedra (either at the boundary or in strict interior if there are overlaps), no tie-breaking (default): fval = ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval4.png matrix of function values (../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval5.png denotes the number of polyhedra which contain ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval6.png), each column contains the value of function_name in the corresponding set, feasible = true, idx = ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval7.png vector of indices of polyhedra which contain x, tb_value = [].
  4. x is contained in multiple polyhedra (either at the boundary or in strict interior if there are overlaps), tie-breaking enabled (see below): fval = ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval8.png vector containing the function value in the polyhedra in which value of the tie-breaking function is smallest (if there are multiple polyhedra with the same tie-breaking value, the first such set is considered), feasible = true, idx = index of the polyhedron which contains x and, simultaneously, has the smallest value of the tie-breaking function, tb_value = scalar value of the tie-breaking function in a polyhedron indexed by idx.
Tie-breaking

The purpose of tie-breaking is to automatically resolve situations where the evaluation point x is contained in multiple polyhedra. With tie-breaking enabled PolyUnion/feval() evaluates the tie-breaking function to decide which polyhedron 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 polyhedra, then the function primal is only evaluated in the polyhedron 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 polyhedron 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 polyhedra

fval = U.feval(x, 'myfun', 'regions', indices) evaluates function myfun over all polyhedra indexed by indices. The output fval is always an ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval9.png matrix, where ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval10.png is the cardinality of indices. Note that once the regions option is enabled, PolyUnion/feval() will not perform point location. Instead, it will evaluate the function in all polyhedra 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, PolyUnion/feval will only evaluate second_function in polyhedra specified by the indices option, hence skipping expensive point location.

Input Arguments

U

Union of polyhedra in the same dimension.

Class: PolyUnion

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 PolyUnion.

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 PolyUnion 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 polyhedra that contain the point x.

Class: double

tb_value

Value of the tie-breaking function if the point belongs to multiple polyhedra.

Class: double

Example(s)

Example 1

PWA function over polyhedral complex. Define one bounded polyhedron in dimension 3.
 P = ExamplePoly.randVrep('d',3); 
 Triangulate the polyhedron 
 T = P.triangulate; 
 Add linear function to each polyhedron ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval11.png in the array under the name "a". 
 T.addFunction(AffFunction([1 -2 0]),'a'); 
 For each polyhedron in the array add second function 'b'. 
 for i=1:length(T), T(i).addFunction(AffFunction(rand(1,3),rand(1)),'b'); end 
 Create union out of polyhedra ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval12.png with some properties. 
 U = PolyUnion('Set',T,'Convex',true,'Bounded',true,'Overlaps',false); 
 Evaluate the PWA function "a" for a point inside the polyhedron ../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval13.png. 
 x = P.interiorPoint.x; 

 y = U.feval(x,'a') 
y =

        -0.520345123015406

Evaluate function a with respect to a tie-breaking function 'b'
 yn = U.feval(x,'a','tiebreak','b') 
yn =

        -0.520345123015406

See Also

fplot


© 2010-2013 Martin Herceg: ETH Zurich, herceg@control.ee.ethz.ch

© 2003-2013 Michal Kvasnica: STU Bratislava, michal.kvasnica@stuba.sk