ADMIT documentation: ADMITcompose

ADMITcompose

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'})

Option 'COMPOSE.constructQP.order'

  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.

Option 'COMPOSE.constructQP.reduceOrder' set to 1

  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

Option 'COMPOSE.constructQP.replaceRationalTerms'

  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