generates a decomposition for a fixed set of facet normals
Syntax: dec = computeDecomposition(A, 'mapping', groupMappingMatrix)
or dec = computeDecomposition(A, 'constraint', constraintMatrix)
The returned decomposition structurure contains data that is required to
map invalid/unconfined vectors to the validity/confinement cone. It
also contains a partitioning of the validity/confinement cone for
efficient measure calculations. Please, use this <a href="matlab:help helpDec>decDetail">Link</a> for detailed
information on used entities, or this <a href="matlab: help helpDec>decOutput">Link</a> for a description of the
output structure.
The procedure has three steps:
1) Checking, if the mapping/contraint fixes the position of the
polytope. If this is not the case, the mapping/constraint is
corrected to fix the position, dependent on the parameter
allowFixPosition.
2) Obtaining facet validity information in H-representation and
checking whether the decomposition is proper. If it is improper, a
proper decomposition is constructed (dec.properData) and projected
accordingly by projectDec, dependent on the parameter allowImproper.
3) Obtaining the validity cone and the required data to map invalid
hC-vectors to valid hC-vectors without a change in shape.
4) Decompose the validity cone into unified and simplex partitions to
prepare the output for efficient measure calculations.
5) If the original representation was improper, the constructed proper
representation is projected to yield the improper representation.
Input options:
verbose - changes verbosity level from 0 up to 2. Default: 0
zerotol - tolerance to determine if numbers are close to zero. Zerotol
is a relative tolerance, as entities are scaled. Default: elkZerotol
constraint - a constraint matrix C*h = 0. Default: []
mapping - a mapping matrix h = M*hC. Default: []
allowFixPosition - allow modification of the mapping/constraint matrix
to fix the position of represented polytopes. A value (0) throws an
error, if position of input is not fixed. A value (1) throws a
warning, corrects the mapping/constraints and proceeds. A value (-1)
performs as (1), but without a warning. Default: 0
allowImproper - allow the processing of improper representations. A
value (0) throws an error for improper representations. A value (1)
throws a warning, but constructs a proper representation. A value
(-1) proceeds as (1), but without a warning. Default: 0
See also: validateDec, computePartitionIndexDec, addMeasureDataDec,
computeMeasureDec0001 function dec = obtainDec(A, varargin) 0002 % generates a decomposition for a fixed set of facet normals 0003 % 0004 % Syntax: dec = computeDecomposition(A, 'mapping', groupMappingMatrix) 0005 % or dec = computeDecomposition(A, 'constraint', constraintMatrix) 0006 % 0007 % The returned decomposition structurure contains data that is required to 0008 % map invalid/unconfined vectors to the validity/confinement cone. It 0009 % also contains a partitioning of the validity/confinement cone for 0010 % efficient measure calculations. Please, use this <a href="matlab:help helpDec>decDetail">Link</a> for detailed 0011 % information on used entities, or this <a href="matlab: help helpDec>decOutput">Link</a> for a description of the 0012 % output structure. 0013 % 0014 % The procedure has three steps: 0015 % 1) Checking, if the mapping/contraint fixes the position of the 0016 % polytope. If this is not the case, the mapping/constraint is 0017 % corrected to fix the position, dependent on the parameter 0018 % allowFixPosition. 0019 % 2) Obtaining facet validity information in H-representation and 0020 % checking whether the decomposition is proper. If it is improper, a 0021 % proper decomposition is constructed (dec.properData) and projected 0022 % accordingly by projectDec, dependent on the parameter allowImproper. 0023 % 3) Obtaining the validity cone and the required data to map invalid 0024 % hC-vectors to valid hC-vectors without a change in shape. 0025 % 4) Decompose the validity cone into unified and simplex partitions to 0026 % prepare the output for efficient measure calculations. 0027 % 5) If the original representation was improper, the constructed proper 0028 % representation is projected to yield the improper representation. 0029 % 0030 % Input options: 0031 % verbose - changes verbosity level from 0 up to 2. Default: 0 0032 % zerotol - tolerance to determine if numbers are close to zero. Zerotol 0033 % is a relative tolerance, as entities are scaled. Default: elkZerotol 0034 % constraint - a constraint matrix C*h = 0. Default: [] 0035 % mapping - a mapping matrix h = M*hC. Default: [] 0036 % allowFixPosition - allow modification of the mapping/constraint matrix 0037 % to fix the position of represented polytopes. A value (0) throws an 0038 % error, if position of input is not fixed. A value (1) throws a 0039 % warning, corrects the mapping/constraints and proceeds. A value (-1) 0040 % performs as (1), but without a warning. Default: 0 0041 % allowImproper - allow the processing of improper representations. A 0042 % value (0) throws an error for improper representations. A value (1) 0043 % throws a warning, but constructs a proper representation. A value 0044 % (-1) proceeds as (1), but without a warning. Default: 0 0045 % 0046 % See also: validateDec, computePartitionIndexDec, addMeasureDataDec, 0047 % computeMeasureDec 0048 0049 % The elk-library: convex geometry applied to crystallization modeling. 0050 % Copyright (C) 2012 Alexander Reinhold 0051 % 0052 % This program is free software: you can redistribute it and/or modify it 0053 % under the terms of the GNU General Public License as published by the 0054 % Free Software Foundation, either version 3 of the License, or (at your 0055 % option) any later version. 0056 % 0057 % This program is distributed in the hope that it will be useful, but 0058 % WITHOUT ANY WARRANTY; without even the implied warranty of 0059 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0060 % General Public License for more details. 0061 % 0062 % You should have received a copy of the GNU General Public License along 0063 % with this program. If not, see <http://www.gnu.org/licenses/>. 0064 0065 %% Input Handling 0066 % input parameters 0067 par = mapOptionStruct(varargin, ... 0068 'verbose', 2,... 0069 'zerotol', elkZerotol,... 0070 'allowFixPosition', 0,... 0071 'allowImproper', 0,... 0072 'constraint', [],... 0073 'mapping', []); 0074 0075 % normalize facet normals 0076 for iFacet = 1:size(A, 2) 0077 A(iFacet, :) = A(iFacet, :) / norm(A(iFacet, :), 2); 0078 end 0079 dec.A = A; 0080 0081 % general information 0082 dec.nDim = size(A, 2); 0083 dec.nH = size(A, 1); 0084 dec.inputData = par; 0085 0086 0087 %% (1) Handle constraint and mapping input; fixPosition 0088 if par.verbose, disp('Generate mapping and constraint matrices (includes fixing position) .. ');end 0089 tic 0090 dec.constraintMatrix = par.constraint; 0091 dec.mappingReducedToFull = par.mapping; 0092 dec = computeMappingAndConstraint(dec, par.zerotol, par.allowFixPosition); 0093 dec.nC = size(dec.mappingReducedToFull, 2); 0094 dec.timingData.fixPosition = toc; 0095 if par.verbose, disp('done.');end 0096 0097 % Result: we now have a constraint matrix, both mapping matrices and all 0098 % three are consistent. They also imply that the position of every 0099 % polytope is fixed that fulfills the constraints or is generated by the 0100 % mapping. 0101 0102 %% (2) Cone of valid h/hC-vectors 0103 % get the cone in h-space - this function only generates inequalities for 0104 % (nDim+1)-tuplets of the facet normals in A 0105 if par.verbose, disp('Gather inequalities for validity cone .. ');end 0106 tic 0107 validityDataOriginal = gatherValidityConeIneq(dec.A, par.zerotol, ... 0108 max(par.verbose-1,0)); 0109 dec.timingData.generateCone = toc; 0110 if par.verbose, disp('done.');end 0111 0112 % decide on proper/improper decomposition - this call contains the 0113 % error/warning handling for allowImproper - it does create a field 0114 % dec.improperData if input was improper. 0115 tic 0116 dec = constructProperRepresentation(dec, validityDataOriginal, ... 0117 par.zerotol, par.verbose, par.allowImproper); 0118 dec.timingData.propernessHandling = toc; 0119 0120 % transfer validity cone to hC and simplify 0121 if par.verbose, disp('Simplify cone representation and extract initial structuring elements ..');end 0122 tic 0123 % transfer cone to hC-space 0124 validityDataOriginal.A = validityDataOriginal.A * dec.mappingReducedToFull; 0125 % remove zero-rows and trim rows 0126 validityDataOriginal.A = trimConstraintMatrix(validityDataOriginal.A, ... 0127 par.zerotol, 1); 0128 0129 dec = addValidityCone(dec, validityDataOriginal.A, par.zerotol); 0130 % the validity cone is idedntical to the confinement cone (validate dec 0131 % will look at the decomposition of the confinement cone. 0132 dec.confinementCone = dec.validityCone; 0133 0134 dec.timingData.simplifyCone = toc; 0135 if par.verbose, disp('done.');end 0136 0137 if par.verbose, disp('Adding facet validity and mapping data ..');end 0138 tic 0139 dec = addFacetValidityData(dec, validityDataOriginal, par.zerotol, ... 0140 max(par.verbose-1,0)); 0141 % validity mapping and confinement mapping is equivalent for proper 0142 % reprentations so that even if the function is named 0143 % addValidityMappingData, it actually adds a field 0144 % confinementMappingData to be compatible with improper representations 0145 % for which validity mapping requires a confinement mapping (no shape 0146 % change) and a validity mapping (shape changes). 0147 dec = addValidityMappingData(dec, par.zerotol); 0148 dec.timingData.addBoundaryData = toc; 0149 if par.verbose, disp('done.');end 0150 0151 % Result: cone of valid polytopes including extreme rays and volume. 0152 % The starting set of structuring elements that are scaled to the 0153 % definition of the cone closure. 0154 0155 0156 %% Decompose this cone 0157 % This algorithm consists of three parts. decomposeCone handles the 0158 % decomposition of the validity cone in a generic way. This means, it 0159 % handles the selection of sample hC-vectors and the handling of the 0160 % remaining domain. 0161 % To generate and evaluate a sample, it uses generateMinkowskiPartition. 0162 % This function stores all partition informations in a struct that is 0163 % accumulated by decomposeCone. 0164 % Finally, the accumulated information is written appropriately to the 0165 % decomposition structure by addMinkowskiPartitionData. 0166 if par.verbose, disp('Decompose cone of valid polytopes .. ');end 0167 tic 0168 partitionData = decomposeCone(dec, dec.validityCone.A, ... 0169 @generateMinkowskiPartition, par.zerotol, max(par.verbose-1, 0)); 0170 dec = addMinkowskiPartitionData(dec, partitionData, par.zerotol); 0171 dec.timingData.decomposeCone = toc; 0172 if par.verbose, disp('done.');end 0173 0174 %% Finalize results 0175 % the following will always be the case (so far dec is a proper 0176 % representaion) 0177 dec.isComplete = 1; 0178 dec.isOrdinary = 1; 0179 0180 % now we have to distinguish between proper and improper representation 0181 if isfield(dec, 'improperData') 0182 % extract and remove improper data 0183 improperData = dec.improperData; 0184 dec = rmfield(dec, 'improperData'); 0185 % intermediate beautify this proper decomposition 0186 dec = cleanupDecStructure(dec); 0187 % project to improper decomposition 0188 dec = projectDec(dec, improperData.mappingImproperToProper, ... 0189 'verbose', par.verbose); 0190 0191 else 0192 % only sort fields and ensure all fields are present 0193 dec = cleanupDecStructure(dec); 0194 end 0195 0196 end