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:
-
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 polyhedron of the union:
fval =
vector of NaNs, where
is the range of the function,
feasible = false,
idx = [] ,
tb_value = [].
-
x is in a single polyhedron:
fval =
vector of function values,
feasible = true,
idx = index of the set which contains x,
tb_value = [].
-
x is contained in multiple polyhedra (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
polyhedra which contain
), each column contains the value of function_name
in the corresponding set,
feasible = true,
idx =
vector of indices of polyhedra which contain x,
tb_value = [].
-
x is contained in multiple polyhedra (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 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:
- Tie-breaking functions must be scalar-valued.
- No tie-breaking is done by default.
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
matrix, where
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:
|
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
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
with some properties. U = PolyUnion('Set',T,'Convex',true,'Bounded',true,'Overlaps',false);
Evaluate the PWA function "a" for a point inside the polyhedron
. 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