Home > source > createY1map.m

# createY1map

## PURPOSE

Check & create one structure representing one matrix variable Y

## SYNOPSIS

function [mapper, offset]=createY1map(Y,offset)

## DESCRIPTION

     Check & create one structure representing one matrix variable Y
     The structure will be one element of array vec2Ymap used in vec2Y().
       Y ... "pattern" matrix given by user (all nnz in one triangle -> variables)
       offset ... gives the last number of the variable (matrix element considered
         as variable) so far, so typically obj.NYnnz and 0 at the beggining;
         matrix element/variables will start with number (offset+1)
         and the returned offset is the last one
       mapper ... structure mapping vectorized variable back to Y in a fast way
         .dim   ... dimxdim dimension of the matrix variable
         .nelem ... no of variables (=no of elements in lower triangle)
         .dense ... generate as dense (true) or sparse (false)
         .xmap  ... mapping the (whole) vector of (Yall) elements) -> nnz of one Y
            the first one (xmap(1)) is always the same as offset+1, i.e., first
            variable (counting 1...NYnnz) in this matrix;
            thus this matrix is created by variables xmap(1)..xmap(1)+nelem-1
         .irow, .icol  ... to generate sparse matrix with xmap (if ~dense),
            first nelem refer to the lower triangle, the rest to the upper;
            if dense, the length is nelem and they map to the lower triangle,
            it could be computed because it'll be 1,1; 2,1; ...dim,1; 2,2; 3,2;...
     Note, to see exactly where the given variable maps (= its derivative):
       variable with index idx=1..nelem maps to irow(idx),icol(idx) + symmetric
       if nondiagonal, absolute number of such a variable (in xall()) is
       idx=Nx+xmap(1), ... ,Nx+xmap(1)+nelem-1

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

## SOURCE CODE

    0001 % Check & create one structure representing one matrix variable Y
    0002 % The structure will be one element of array vec2Ymap used in vec2Y().
    0003 %   Y ... "pattern" matrix given by user (all nnz in one triangle -> variables)
    0004 %   offset ... gives the last number of the variable (matrix element considered
    0005 %     as variable) so far, so typically obj.NYnnz and 0 at the beggining;
    0006 %     matrix element/variables will start with number (offset+1)
    0007 %     and the returned offset is the last one
    0008 %   mapper ... structure mapping vectorized variable back to Y in a fast way
    0009 %     .dim   ... dimxdim dimension of the matrix variable
    0010 %     .nelem ... no of variables (=no of elements in lower triangle)
    0011 %     .dense ... generate as dense (true) or sparse (false)
    0012 %     .xmap  ... mapping the (whole) vector of (Yall) elements) -> nnz of one Y
    0013 %        the first one (xmap(1)) is always the same as offset+1, i.e., first
    0014 %        variable (counting 1...NYnnz) in this matrix;
    0015 %        thus this matrix is created by variables xmap(1)..xmap(1)+nelem-1
    0016 %     .irow, .icol  ... to generate sparse matrix with xmap (if ~dense),
    0017 %        first nelem refer to the lower triangle, the rest to the upper;
    0018 %        if dense, the length is nelem and they map to the lower triangle,
    0019 %        it could be computed because it'll be 1,1; 2,1; ...dim,1; 2,2; 3,2;...
    0020 % Note, to see exactly where the given variable maps (= its derivative):
    0021 %   variable with index idx=1..nelem maps to irow(idx),icol(idx) + symmetric
    0022 %   if nondiagonal, absolute number of such a variable (in xall()) is
    0023 %   idx=Nx+xmap(1), ... ,Nx+xmap(1)+nelem-1
    0024 function [mapper, offset]=createY1map(Y,offset)
    0025   mapper=[];
    0026
    0027   % take empty as OK? Yes, such a matrix will be filtered-out from constraints
    0028   if (isempty(Y))
    0029     mapper.dim=0;
    0030     mapper.nelem=0;
    0031     mapper.dense=true;
    0032     mapper.xmap=[];
    0033     mapper.irow=[];
    0034     mapper.icol=[];
    0035   else
    0036     % does Y look OK?
    0037     [dim, dim2] = size(Y);
    0038     if (dim~=dim2)
    0039       error('Y is not a square??');
    0040       return;
    0041     end
    0042
    0043     if (~issparse(Y) && nnz(Y)==dim*dim)
    0044       % Y is really dense and the full lower triangle will create decision vars
    0045       nonnz=dim*(dim+1)/2;
    0046       % do it better???
    0047       [row,col]=find(tril(Y));  % should be 1,1; 2,1; 3,1; 2,2; 3,2; ...
    0048       mat=full(sparse(row,col,[1:nonnz]));
    0049       mat=mat+tril(mat,-1)';
    0050
    0051       mapper.dim=dim;
    0052       mapper.nelem=nonnz;
    0053       mapper.dense=true;
    0054       mapper.xmap=offset + mat(:);  % should be same as reshape(mat,dim*dim,1)
    0055       %mapper.irow=[];
    0056       %mapper.icol=[];
    0057       mapper.irow=row;
    0058       mapper.icol=col;
    0059       offset=offset+nonnz;
    0060
    0061     else
    0062       % work with it as sparse
    0063       Y=spones(Y);   % to avoid random nullification in Y+Y'
    0064       Y=tril(Y+Y');  % or don't symmetrize? or check?
    0065       [row, col] = find(Y);
    0066       inner=find(row~=col);
    0067       nonnz=length(row);
    0068
    0069       mapper.dim=dim;
    0070       mapper.nelem=nonnz;
    0071       mapper.dense=false;
    0072       mapper.irow=[row; col(inner)];
    0073       mapper.icol=[col; row(inner)];
    0074       mapper.xmap= offset + [[1:nonnz]'; inner];
    0075       offset = offset + nonnz;
    0076     end
    0077
    0078   end
    0079