mapFromProperEmbedding

 map hE-vector from proper embedding to hC-vector space

 Syntax: hcMatrix = convertToProperEmbedding(hcMatrix, dec)

 The input decomposition is assumed to be improper and the hE vectors
   reside in the hE-space of the proper embedding. The input hE-vectors 
   (each column in heMatrix) are assumed to reside on the nC-dimensional 
   domains in hE-space that correspond to the unified partitions of the 
   improper representation. If this is not the case the corresponding
   unified partition might not be found or the shape of the corresponding
   polytope might be changed.

 See also: projectDec, mapToConfonementCone

• mapToConfinementCone map a hC vector to the cone of confined hC-vectors
• limitGrowthRate limit growth rate so that hC-vector remains valid

0001 function hcMatrix = mapFromProperEmbedding(heMatrix, dec, zerotol, ...
0002     partitionVector, enforcePartition)
0003 % map hE-vector from proper embedding to hC-vector space
0004 %
0005 % Syntax: hcMatrix = convertToProperEmbedding(hcMatrix, dec)
0006 %
0007 % The input decomposition is assumed to be improper and the hE vectors
0008 %   reside in the hE-space of the proper embedding. The input hE-vectors
0009 %   (each column in heMatrix) are assumed to reside on the nC-dimensional
0010 %   domains in hE-space that correspond to the unified partitions of the
0011 %   improper representation. If this is not the case the corresponding
0012 %   unified partition might not be found or the shape of the corresponding
0013 %   polytope might be changed.
0014 %
0015 % See also: projectDec, mapToConfonementCone
0016 
0017 % The elk-library: convex geometry applied to crystallization modeling.
0018 %   Copyright (C) 2013 Alexander Reinhold
0019 %
0020 % This program is free software: you can redistribute it and/or modify it
0021 %   under the terms of the GNU General Public License as published by the
0022 %   Free Software Foundation, either version 3 of the License, or (at your
0023 %   option) any later version.
0024 %
0025 % This program is distributed in the hope that it will be useful, but
0026 %   WITHOUT ANY WARRANTY; without even the implied warranty of
0027 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0028 %   General Public License for more details.
0029 %
0030 % You should have received a copy of the GNU General Public License along
0031 %   with this program.  If not, see <http://www.gnu.org/licenses/>.
0032 
0033 if dec.isProper
0034     error(['elk:decomposition:inputError', 'The input decomposition is ' ...
0035         'supposed to be improper for this function.']);
0036     % if it is proper, one does not need this function.
0037 end
0038 if ~dec.isComplete
0039     % in case of an incomplete representation, there is not much to do:
0040     hcMatrix = dec.properData.mappingProperToNew * heMatrix;
0041     return
0042 end
0043 if ~exist('zerotol', 'var') || isempty(zerotol)
0044     zerotol = elkZerotol;
0045 end
0046 if ~exist('partitionVector', 'var') || isempty(partitionVector)
0047     partitionVector = zeros(1, size(heMatrix, 2));
0048     processFilter = true(1, size(heMatrix, 2));
0049     
0050     for iPart = 1:dec.nPU
0051         filterInPartition = processFilter;
0052         filterInPartition(processFilter) = max(...
0053             dec.unifiedPartition{iPart}.embeddingDomain.hrepStrict.A * ...
0054             heMatrix(:, processFilter), [], 1) < zerotol;
0055         partitionVector(filterInPartition) = iPart;
0056         processFilter(filterInPartition) = false;
0057         
0058         if ~any(processFilter)
0059             break;
0060         end
0061     end
0062         
0063     % error handling
0064     if any(partitionVector == 0)
0065         error('elk:decomposition:indistinctError', ...
0066             ['the unified partition for some input vector could ' ...
0067             'not be found. This can have several causes, please check: ' ...
0068             '(1) whether your decomposition is ordinary, (2) whether ' ...
0069             'all input vectors describe a polytope of the input improper ' ...
0070             'decomposition, (3) otherwise, the decomposition was not ' ...
0071             'created properly and this should not happen.']);
0072     end
0073 end
0074 % partitionVector
0075 if exist('enforcePartition', 'var') && enforcePartition
0076     for iPart = 1:dec.nPU
0077         thisFilter = partitionVector == iPart;
0078         heMatrix(:, thisFilter) = dec.unifiedPartition{iPart...
0079             }.embedding.validityProjection * heMatrix(:, thisFilter);
0080     end    
0081 end
0082 
0083 hcMatrix = nan(dec.nC, size(heMatrix, 2));
0084 for iPart = 1:dec.nPU
0085     thisFilter = partitionVector == iPart;
0086     hcMatrix(:, thisFilter) = ...
0087         dec.unifiedPartition{iPart}.projection.fromProper * ...
0088         heMatrix(:, thisFilter);
0089 end
0090 
0091 if any(isnan(hcMatrix(:)))
0092     error(['elk:decomposition:wrongInput', 'Please check your input to ' ...
0093         'this function (partitionVector) as some vectors could not ' ...
0094         'be projected.']);
0095 end