Home > source > expen.m

# expen

## PURPOSE

example pennon structure to play with

## SYNOPSIS

function penm=expen()

## DESCRIPTION

     example pennon structure to play with
     call penm=expen & problem=penlab(penm)

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

## SOURCE CODE

    0001 % example pennon structure to play with
    0002 % call penm=expen & problem=penlab(penm)
    0003 function penm=expen()
    0004
    0005   penm = [];
    0006
    0007   % [optional] problem name and a comment (e.g. source)
    0008   % just for logging
    0009   penm.probname = 'Example Problem 1';
    0010   penm.comment = 'bla bla comment';
    0011
    0012   %% [optional] userdata
    0013   % will get always pass in and from any callback function, can be anything
    0014   % if not set, an empty array will be used instead
    0015   penm.userdata = [];
    0016
    0017   % [optional] option settings different from defaults
    0018   penm.opts=[];
    0019
    0020   %% define decision variables
    0021   % number of (ordinary) decision variables
    0022   % If the field is not present, Nx=0; lower/upper bounds for box constraints
    0023   % will be ignored.
    0024   penm.Nx = 7;
    0025   % number of matrix variables, should be the same as length(Y)
    0026   % If the field is not present, NY=0; thus Y{:}, bounds etc. will be ignored.
    0027   penm.NY = 3;
    0028   % cell array of length 'NY' with a nonzero pattern of each of the matrix
    0029   % variables. Each matrix will be symmetrized and all its nonzeros in one
    0030   % triangle will be considered as variables, the rest as constant zeros.
    0031   % Whenever array Y{} is present in the callbacks, it will be symmetrized.
    0032   % All (element-)variables will be counted with indicies starting with (Nx+1),
    0033   % the order is Y{1}, Y{2}, ..., Y{NY} and in each matrix lower (symmetrized)
    0034   % triangle column-wise. If any (derivative) callback needs derivatives
    0035   % with respect to 'k' (k>Nx), it means it's one of the variables in one
    0036   % of the matrices. A routine '...' can generate back the matrix and the exact
    0037   % position of the variable ...
    0038   penm.Y{1} = ones(3);
    0039   penm.Y{2} = spones(sprandsym(5,0.3));
    0040   penm.Y{3} = spones(sprand(6,6,0.2));
    0041
    0042   %% decision variables box constraints
    0043   % box constraints (lower/upper bounds) on the variables, lbx <= x <= ubx
    0044   % if lbx==-Inf, it is not considered; similarly if ubx=Inf so, e.g.,
    0045   % by setting lbx=-Inf, ubx=Inf the variable is unbounded.
    0046   % length of each array should be Nx
    0047   % if one or both are missing, 'x' is considered as unconstrained from that
    0048   % side. Any ubx>lbx is considered as error. If lbx==ubx the variable will
    0049   % be fixed and won't have further effect.
    0050   penm.lbx = 0;
    0051   %penm.lbx = [-Inf, -Inf, -1, 0, -3, -6, -77];
    0052   penm.ubx = [10, Inf, Inf, 4, 66, 0.1, Inf];
    0053
    0054   % lower, upper bounds on Y variable elements?
    0055   % if not present, unconstrained
    0056   % penm.lbYx, ubYx ? or not at all? It can be always defined as one of the g()
    0057   % constraints
    0058
    0059   % lower and upper bound on matrices Y (as matrix inequalities, i.e. eigenvals)
    0060   % if fixed... what to do? Might even not have solution...
    0061   % length NY
    0062   penm.lbY = [0, -Inf, 1];
    0063   penm.ubY = [Inf, 0, 10];
    0064
    0065   % [optional] box constraints on the elements of the matrix variables
    0066   % only elements matchin patterns of Y{} will be taken into account
    0067   % if the matrix is empty ([]) it is automatically considered as +/-Inf
    0068   % accordingly
    0069   penm.lbYx{1} = - magic(3);
    0070   penm.ubYx{1} = magic(3);
    0071   penm.lbYx{2} = sparse(5,5);
    0072   penm.ubYx{3} = 100;
    0073
    0074   %% starting point
    0075   % ideally feasible, might get adjusted, optional, if not set will be computed
    0076   % somehow. With the matrices, it will accept only these nnz which where in
    0077   % Y pattern. Symmetric or automatically lower triangle???
    0078   penm.xinit=rand(penm.Nx,1);
    0079   %penm.Yinit{1} {2} {3}=....;
    0080
    0081   %% linear and nonlinear function constraints
    0082   % nonlinear constraints, first NLN , then LIN
    0083   penm.NgNLN = 2;
    0084   penm.NgLIN = 1;
    0085
    0086   % nonlinear and linear matrix constraints
    0087   penm.NANLN = 0;
    0088   penm.NALIN = 1;
    0089
    0090   % lower/upper bounds ... equalities, must be defined at least on one side
    0091   % (e.g. not unconstrained constraints ;-)
    0092   penm.lbg = [-Inf, 0, 5];
    0093   penm.ubg = [0, Inf, 5];
    0094   penm.lbA = [0];
    0095   penm.ubA = [Inf];
    0096
    0097   %% call back functions to evaluate objective function, function constraints
    0098   % and matrix constraint and their derivatives. First go NLN then LIN.
    0099   %penm.objfun = ...
    0100   % [fx, userdata] = objfun(x,Y,userdata)   % returns a number
    0101   % [fdx, userdata] = objgrad(x,Y,userdata) % returns a (sparse) vector
    0102      % w.r.t. all variables (even matrix ones)
    0103   % objfun, objgrad, objhess
    0104   % confun, congrad, conhess
    0105   % mconfun, mcongrad, mconhess
    0106   % alternatively objhess + conhess -> lagrhess
    0107
    0108   %[fx, userdata] = objfun(x,Y,userdata)   % returns a number
    0109
    0110   %[fdx, userdata] = objgrad(x,Y,userdata) % returns a (possibly sparse) vector
    0111      % w.r.t. all variables (even matrix ones), if objfun doesn't depend on Y
    0112      % it can be just Nx long, otherwise Nx+NYnnz
    0113
    0114