computeMappingAndConstraint

 generate mapping matrix and constraint matrix and ensure fixed position

 THIS IS NO USER FUNCTION

• computeMappingAndConstraint generate mapping matrix and constraint matrix and ensure fixed position
• fixPosition calculate constraints to fix the position of the polytope
• trimColumns trim the columns of the input matrix to equal values

• computeMappingAndConstraint generate mapping matrix and constraint matrix and ensure fixed position
• constructProperRepresentation check (and construct) proper representation
• obtainDec generates a decomposition for a fixed set of facet normals

0001 function dec = computeMappingAndConstraint(dec, zerotol, allowFixPosition)
0002 % generate mapping matrix and constraint matrix and ensure fixed position
0003 %
0004 % THIS IS NO USER FUNCTION
0005 
0006 % The elk-library: convex geometry applied to crystallization modeling.
0007 %   Copyright (C) 2012 Alexander Reinhold
0008 %
0009 % This program is free software: you can redistribute it and/or modify it
0010 %   under the terms of the GNU General Public License as published by the
0011 %   Free Software Foundation, either version 3 of the License, or (at your
0012 %   option) any later version.
0013 %
0014 % This program is distributed in the hope that it will be useful, but
0015 %   WITHOUT ANY WARRANTY; without even the implied warranty of
0016 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0017 %   General Public License for more details.
0018 %
0019 % You should have received a copy of the GNU General Public License along
0020 %   with this program.  If not, see <http://www.gnu.org/licenses/>.
0021 
0022 %% info
0023 % This part ensures that the mapping matrix (for crystals group mapping
0024 %   matrix) and the constraint matrix are generated and consistent. It also
0025 %   corrects the input if the position is not fixed.
0026 % Not fixing the position might work, but results in cones that can hardly
0027 %   be imagined. Especially, unfixed positions might imply that polytopes
0028 %   become empty sets for h~=0, which is strongly unhandy.
0029 
0030 
0031 %% input handling
0032 % check sizes, if matrices are present
0033 if ~isempty(dec.mappingReducedToFull) && ...
0034     size(dec.mappingReducedToFull, 1) ~= dec.nH
0035         error('elk:decomposition:wrongInput', ...
0036              ['the provided mapping matrix must have the same number ' ...
0037               'of rows like the matrix of facet normals A']);
0038 end
0039 if ~isempty(dec.constraintMatrix) && (...        
0040         size(dec.constraintMatrix, 2) ~= dec.nH )
0041     error('elk:decomposition:wrongInput', ...
0042         ['the provided constraint matrix must be square and must' ...
0043         'have the size of the row number of the matrix of facet normals A']);
0044 end
0045   
0046 if isempty(dec.constraintMatrix) && isempty(dec.mappingReducedToFull)
0047     %% nothing provided
0048     if allowFixPosition == 0
0049         error('elk:decomposition:fixPosition', ['you need to provide a ' ...
0050             'mapping or constraint matrix, or set allowFixPosition to -1']);
0051     elseif allowFixPosition == 1
0052         warning('elk:decomposition:fixPosition', ['Mapping and constraint ' ...
0053             'matrices are generated to fix the position of represented ' ...
0054             'polytopes, use allowFixPosition option with (-1) to supress ' ...
0055             'this warning']);
0056     end
0057     % need to fix position
0058     dec.constraintMatrix = fixPosition(dec.A, zeros(0, size(dec.A, 1)), zerotol);
0059     % generate mapping
0060     [~, s, v] = svd(dec.constraintMatrix);
0061     s = diag(s);
0062     s(isZero(s, zerotol)) = 0;
0063     dec.mappingReducedToFull = trimColumns(v(:, s==0), zerotol);    
0064     
0065 elseif isempty(dec.constraintMatrix)
0066     %% constraint not provided
0067     % generate constraint
0068     dec.constraintMatrix = eye(dec.nH) - dec.mappingReducedToFull * ...
0069         pinv(dec.mappingReducedToFull);
0070     % incorporate fixed position
0071     additionalConstraintMatrix = fixPosition(dec.A, dec.constraintMatrix, zerotol);
0072     if rank(additionalConstraintMatrix) ~= 0
0073         % error/warning handle if modification is allowed
0074         if allowFixPosition == 0
0075             error('elk:decomposition:fixPosition', ['polytopes in the given ' ...
0076                 'representation are not fixed in their position. change ' ...
0077                 'allowFixPosition to 1 to automatically modify the ' ...
0078                 'mapping matrix.']);
0079         elseif allowFixPosition == 1
0080             warning('elk:decomposition:fixPosition', ['Mapping matrix ' ...
0081                 'is modified to fix the position of represented ' ...
0082                 'polytopes. use allowFixPosition option with (-1) to supress ' ...
0083                 'this warning']);
0084         end
0085         % we need to generate a new mapping matrix (reduced dimension)
0086         dec.mappingReducedToFull = [];
0087         dec.constraintMatrix = [dec.constraintMatrix; additionalConstraintMatrix];
0088         dec = computeMappingAndConstraint(dec, zerotol, allowFixPosition);
0089         
0090 %         % merge constraint - additionalConstraintMatrix has only a single
0091 %         %   1 in each row to fix that facet distance to zero. We can
0092 %         %   directly apply this for the mapping matrix:
0093 %         dec.mappingReducedToFull(sum(additionalConstraintMatrix, 1) >= 1, :) = 0;
0094 %         % this gives a new constraint matrix:
0095 %         dec.constraintMatrix = eye(dec.nH) - dec.mappingReducedToFull * ...
0096 %             pinv(dec.mappingReducedToFull);
0097     end
0098     
0099 else
0100     %% constraint is provided
0101     % incorporate fixed position
0102     additionalConstraintMatrix = fixPosition(dec.A, dec.constraintMatrix, zerotol);
0103     if rank(additionalConstraintMatrix) ~= 0
0104         % error/warning handle if modification is allowed
0105         if allowFixPosition == 0
0106             error('elk:decomposition:fixPosition', ['polytopes in the given ' ...
0107                 'representation are not fixed in their position. change' ...
0108                 'allowFixPosition to 1 to automatically modify the ' ...
0109                 'constraint matrix.']);
0110         elseif allowFixPosition == 1
0111             warning('elk:decomposition:fixPosition', ['Constraint matrix ' ...
0112                 'is modified to fix the position of represented ' ...
0113                 'polytopes. use allowFixPosition option with (-1) to supress ' ...
0114                 'this warning']);
0115         end
0116         % append new constraints
0117         dec.constraintMatrix = [dec.constraintMatrix; additionalConstraintMatrix];
0118     end
0119     % generate mapping matrix
0120     [~, s, v] = svd(dec.constraintMatrix);
0121     s = diag(s);
0122     s(isZero(s, zerotol)) = 0;
0123     dec.mappingReducedToFull = trimColumns(v(:, s==0), zerotol);    
0124     
0125 end
0126 
0127 %% check consistency of mapping and constraint
0128 if ~all(isZero(dec.constraintMatrix * dec.mappingReducedToFull, zerotol))
0129     error('elk:decomposition:wrongInput', ...
0130          ['the provided constraint matrix is not consistent with the ' ...
0131           'provided mapping matrix: constraint*mapping should result ' ...
0132           'in a matrix with all elements close to zero. This should not ' ...
0133           'happen.']);
0134 end
0135 
0136 %% generate reverse mapping
0137 dec.mappingFullToReduced = pinv(dec.mappingReducedToFull);
0138 
0139 end