Functions Used to Find Control Laws

% FINDCTRL finds the control on a simplex that realises a discrete equivalent.
%
% Usage: CT=FINDCTRL(S,DE,OUTFACET,@OPTFUNC,ARGS);
%
% S is a prepared polytope
% DE is a discrete equivalent of s, which can be found using
% FINDDISCRETEEQ
% OUTFACET is the desired outputfacet, must be in the blockable set or be
% empty if the facet is to be left through an uncontrollable facet or stay
% inside.
% @OPTFUNC is a function-pointer to an optimisation function
%  See the documentation for instructions on creating optimisation functions.
%  Functions included in the toolbox are:
%  FINDBESTEFFORTINPUT(S,DE,OUTFACET)
%  FINDMINSQINPUT()
% ARGS are any arguments that must be supplied to the optimisation
% function.
%
% CT is the control realising the DE
%  CT.K=K - Control gain
%  CT.G=G - Affine control gain
%
% U=KX+G is the control law achiving the optimum values
%
% Example:

 s=demosimplex();
 s=preparepolytope(s);
 de=finddiscreteeq(s);
 out=de.exits(1);
 ct=findctrl(s,de,out,@findminsqinput);

% See also FINDBESTEFFORTINPUT, FINDMINSQINPUT and FINDDISCRETEEQ

% SOL2CTRL refines a winning strategy on a discrete game abstraction to a
% controller catalogue
%
% Usage: CTCAT=SOL2CTRL(PAHS,DGABS,SOL)
%
% PAHS a piecewise-affine hybrid system
% DGABS a discrete game abstraction of PAHS
% SOL a solution to the DGABS obtained by FINDDGSOL
%
% CTCAT a catalogue of controllers
%  CTCAT.MODE{i}.LOC{J}.PREV{K} des to choose when previous polytope was K
%  CTCAT.MODE{i}.LOC{J}.DES controllers for the different discrete
%  equivalents
%  CTCAT.MODE{i}.LOC{J}.DES{L}.PREV{K} exit to choose when previous
%   polytope was K, if 0 block all blockable facets
%  CTCAT.MODE{i}.LOC{J}.DES{L}.EXIT{M}.K control parameter when desired
%   exit facet is M
%  CTCAT.MODE{i}.LOC{J}.DES{L}.EXIT{M}.G control parameter when desired
%   exit facet is M
%  CTCAT.MODE{i}.LOC{J}.DES{L}.BLOCK.K control parameter when all facet
%   must be blocked
%  CTCAT.MODE{i}.LOC{J}.DES{L}.BLOCK.G control parameter when all facet
%   must be blocked
%
% Example:

 pahs=demopahs2();
 dgabs=finddiscgame(pahs);
 req=demoreq2();
 spec=req2spec(pahs,req);
 [win,sol]=finddgsol(dgabs,spec);
 if(win)
    disp('Winning')
    ctcat=sol2ctrl(pahs,dgabs,sol);
 end

% See also SIMPAHS and FINDDGSOL

% FINDMINSQINPUT optimisation function used for FINDCTRL.
% DO NOT call this function directly, see the documentation for details.
%
% Minimises J=SUM UI'*UI where UI denotes the input at facet I.
%
% Usage: As a parameter to the findctrl function.
% No extra arguments are needed for this function.
%
% Example:

 s=demosimplex();
 s=preparepolytope(s);
 de=finddiscreteeq(s);
 out=de.exits(1);
 ct=findctrl(s,de,out,@findminsqinput);

% See also FINDCTRL, FINDBESTEFFORTINPUT and GETDISCRETEEQ

% FINDBESTEFFORTINPUT optimisation function used for FINDCTRL.
% DO NOT call this function directly, see the documentation for details.
%
% Optimises the vectorfield of the controlled system to point towards the
% desired exit facet and away from uncontrollable facets.
%
% Usage: As a parameter to the findctrl function.
% The extra arguments that needs to be passed to this function is
% S,DE,OUTFACET.
%
% S is the polytope
% DE is the discrete equivalent
% OUTFACET is the facet which the controller should try and exit
% through
%
% Example:

 s=demosimplex();
 s=preparepolytope(s);
 de=finddiscreteeq(s);
 out=de.exits(1);
 ct=findctrl(s,de,out,@findbesteffortinput,s,de,out);

% See also FINDCTRL, FINDMINSQINPUT and GETDISCRETEEQ