ADMITcomposeADMITcompose
ADMITcompose converts or modifies an ADMITproject-object such that it can be
used in the estimation procedure (ADMITestimate)
VARARGOUT = ADMITcompose(VARARGIN, [OPTIONS])
Creates (MODE 'init') or updates (MODE 'update' or 'setBounds') structure
with information for the feasibility tests, or constructs
(MODE 'constructQP') a quadratic problem.
OPTIONS is an ADMIToptions object. If none provided, then the default
set of options is used.
Depending on MODE, different things are done and
different input/output arguments are needed as further described below.
DEFAULT MODE
If function is called without MODE specifier, then the function calls
itself first with MODE 'constructQP' and second 'init':
[OPTINFO,OPT_OUT] = ADMITcompose(OPT_IN, [OPTIONS])
[OPTINFO,OPT_OUT] = ADMITcompose(OPT_IN, TIME_OF_INTEREST, [OPTIONS])
Inputs
[...] : square brackets notify that input is optional.
OPT_IN : ADMITproject object
TIME_OF_INTEREST : name of a time-points-set that will be used to
determine the information in optInfo;
if none is provided, then t_ALL (*) is used instead.
OPTIONS : ADMIToptions object
Returns
OPT_OUT : modified ADMITproject-object
OPTINFO : ADMITinfo-object with the following fields:
.name : content of the name-field in OPT
.Q_LIN : LINEAR equality constraints
.Q_QP : QUADRATIC equality constraints
.B1_LIN : LINEAR normal inequality constraints
.B1_QP : QUADRATIC normal inequality constraints
.B2_LIN : LINEAR explicit bounds (always linear!)
.B3_LIN : LINEAR logical constraints
.B3_QP : QUADRATIC logical constraints
.B4_LIN : LINEAR tighter bounds on additional vars (always linear!)
.varIdx : indices of different types of variables in xi
.timeVariant : time-variant
.timeInVariant: time-invariant
.ofInterest : variables that are "ofInterest"
.bin : binary variables
.integer : integer variables
.real : real
.xi : xi-column-vector
.xiT : xi-row-vector
.xi_bounds : bounds-inform. on vars. in xi (used internally)
.cons_bounds : bounds-inform. for constraints (used internally)
.equations : information for all equations
.info : information (used internally) to rescale
logical constraints, generate matrices, etc.
.t_ALL : double vector with time-points
.t_ALL_intv : ADMITinterval vector with time-points
."TIME_POINT_SETS" : time-point sets as defined in OPT
MODE 'CONSTRUCTQP'
OPT_OUT = ADMITcompose(OPT_IN, 'constructQP', [OPTIONS])
OPT_OUT = ADMITcompose(OPT_IN, 'constructQP', FIRSTCHOICE, LASTCHOICE,[OPTIONS])
Determines a minimal quadratic representation (QP) of the system and
performs other operations on the system of (in-)equalities depending on
the input arguments (see below).
The last input argument can be an options structure. If none is provided,
then the default options are used.
OPT_IN is a valid ADMITproject-object and OPT_OUT is the modified one.
Constructs a minimal quadratic representation for the system using a
greedy and recursive (depth-first) algorithm. Recursion terminates if
all possible combinations have been tested or if time-out reached
(set by option COMPOSE.constructQP.timeOut).
Additional mode-specifiers:
'FIRSTCHOICE' and cell array of monomials : uses the provided
monomials first to construct the QP; e.g.:
ADMITcompose(OPT_IN,'constructQP','firstChoice',{'a(t)*b','c*d'})
'LASTCHOICE' and cell array of monomials : uses the provided
monomials only as the last resort to construct the QP; e.g.:
ADMITcompose(OPT_IN,'constructQP','lastChoice',{'a(t)*b','c*d'})
Contains order in which variables are replaced. E.g.:
options.COMPOSE.constructQP.order = ...
{'timeInvariant','timeVariant','all'};
a quadratic problem is constructed by attempting first to replace
products of time-invariant variables, then products of time-variant,
and then finally products of any kind of variables until a quadratic
problem is obtained.
The default value is usually the best and there's no need to change it.
Trys to reduce the order of the QP by substituting variables appearing
with powers larger than one in the (in-)equalities by the same variable
raised to the integer-valued LEAST-COMMON-DIVISOR, e.g:
Example 1: A^3 + A^6 = 0 ---> A + A^2 = 0
Example 2: A^3 + A^2 = 0 ---> A^3 + A^2 = 0
Example 3: A^2 + A^4 = 0 ---> A + A^2 = 0
A^2 + A^8 = 0 ---> A + A^4 = 0
Eliminates rational terms in the equations.
Value of option:
'MULTIPLY' : multiply equations with their common denominator.
Example: a/b + c = 0 ---> a + c*b = 0
'SUBSTITUTE' : substitute denominator of rational terms by an
additional variable.
Example: a/b + c = 0 ---> a*av1 + c = 0
av1*b -1 = 0
(NOTE: 'SUBSTITUTE' usually yields shorter xi-vectors, which is
advantageous from a computational point of view,
but it may cause numerical troubles.
This mode is therefore currently disabled until we've found a robust
solution.)
MODE 'init'
OPTINFO = ADMITcompose(OPT_IN, 'init', [OPTIONS])
OPTINFO = ADMITcompose(OPT_IN, 'init', TIME_OF_INTEREST, [OPTIONS])
Creates a ADMITinfo-object with all information for the
feasibility tests. This structure can then be updated using the other two
modes (see further below).
Inputs and Returns please see 'DEFAULT'.
MODE 'setBounds' and 'intersectBounds'
OPTINFO_OUT = ADMITcompose(OPTINFO_IN, 'setBounds', BOUNDS, [OPTIONS])
OPTINFO_OUT = ADMITcompose(OPTINFO_IN, 'intersectBounds', BOUNDS, [OPTIONS])
Sets explicit bounds in an ADMITinfo-object with bounds e.g. from
previous estimations. Bounds are provided as ADMITconstraints,
ADMITresults, or ADMITproject.
Inputs
[...] : square brackets notify that input is optional.
OPTINFO_IN : ADMITinfo-object
BOUNDS : One of three input object is possible:
1) ADMITconstraint defining explicit bounds on a
variable, e.g. ADMITconstraint('A(0) := [0,1]')
2) ADMITresults object as obtained from previous call to
ADMITestimate.
3) ADMITproject object; note: only the bounds are used, no
other constraints are added.
OPTIONS : ADMIToptions
Returns
OPTINFO_OUT : modified ADMITinfo-object
MODE 'update'
[OPTINFO_OUT,INFEASIBLE] = ADMITcompose(OPTINFO_IN, 'update', [OPTIONS])
Updates explicit and implicit bound of a ADMITinfo-object by using
the ADMITpresolve. This function should be called after 'setBounds' to
propagate any uncertainty changes to all other variables. This function
is also called internally by ADMITestimate.
Inputs
[...] : square brackets notify that input is optional.
OPTINFO_IN : ADMITinfo-object
OPTIONS : ADMIToptions
Returns
OPTINFO_OUT : updated ADMITinfo-object
INFEASIBLE : "0" or "1" indicated if problem is feasible using
ADMITpresolve().
MODES 'setVariablesOfInterest' and 'unsetVariablesOfInterest'
OPTINFO_OUT = ADMITcompose(OPTINFO_IN, 'setVariablesOfInterest', VARIABLES, [OPTIONS])
OPTINFO_OUT = ADMITcompose(OPTINFO_IN, 'unsetVariablesOfInterest', VARIABLES, [OPTIONS])
Set or unset variables to be 'variables of interest' (VOI), i.e. to be
estimated by ADMITestimate. VARIABLES contains symbolic names of
variables to be set/unset as VOI. To set/unset a time-variant variable
specify the time (e.g. "a(1.1)") or set/unset all time-points (e.g.
"a(*)"). To set/unset ALL variables use placeholder '*'.
Inputs
[...] : square brackets notify that input is optional.
OPTINFO_IN : ADMITinfo-object
VARIABLES : VARIABLES contains symbolic names of
variables to be set/unset as VOI
OPTIONS : ADMIToptions
Returns
OPTINFO_OUT : updated ADMITinfo-object