Description of validateInput

0001 function par = validateInput(hcMatrix, dec, par)
0002 % validate input arguments to approximateDec
0003 
0004 % The elk-library: convex geometry applied to crystallization modeling.
0005 %   Copyright (C) 2013 Alexander Reinhold
0006 %
0007 % This program is free software: you can redistribute it and/or modify it
0008 %   under the terms of the GNU General Public License as published by the
0009 %   Free Software Foundation, either version 3 of the License, or (at your
0010 %   option) any later version.
0011 %
0012 % This program is distributed in the hope that it will be useful, but
0013 %   WITHOUT ANY WARRANTY; without even the implied warranty of
0014 %   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0015 %   General Public License for more details.
0016 %
0017 % You should have received a copy of the GNU General Public License along
0018 %   with this program.  If not, see <http://www.gnu.org/licenses/>.
0019 
0020 % This function is also used internally for computeApproximationDec,
0021 %   cs-approximation/generateApproxData and cs-approximation/..
0022 %   loadApproxData. Therefore, the input/output interface is not
0023 %   documented.
0024 
0025 %% Lists / available options
0026 % strings in List must end with an extra space
0027 methodApproxList = {'PCA ' 'nonlinear ' 'nonlinearLocal '};
0028 methodErrorList = {'relativeSquared ', 'relativeMean ', 'relativeMax ', ...
0029     'relativeTotal ', 'absoluteSquared ', 'absolute ', 'absoluteMax ', ...
0030     'absoluteTotal ', 'relativeMaxGroupedMean ', 'PCA '};
0031 methodProjectionList = {'true ', 'confined '};
0032 
0033 msgMethod = ['Supported approximation methods are: ' methodApproxList{:}];
0034 msgError = ['Supported error types are: ' methodErrorList{:}];
0035 msgProjection = ['Supported projection types are: ' methodProjectionList{:}];
0036 
0037 %% consistecy of dec and hcMatrix
0038 if ~dec.isProper && dec.isComplete
0039     error('elk:decomposition:wrongInput', ['input representation dec ' ...
0040         'must be proper or incomplete (via computeExtendedEmbedding).']);
0041 end
0042 if dec.nC ~= size(hcMatrix, 1)
0043     error('elk:decomposition:wrongInput', ['dimension of vectors in ' ...
0044         ' must match dec.nC.']);
0045 end
0046 if size(hcMatrix, 1) < 1
0047     error('elk:decomposition:wrongInput', ['please give me a vector to ' ...
0048         'work with - the provided hcMatrix is empty']);
0049 end
0050 % And now, let's have some fun with a user:
0051 if size(hcMatrix, 2) <= par.targetDim && ~strcmpi(par.method, 'pca')
0052     warning('elk:decomposition:input', ['Are you kidding me? The '...
0053         'number of hC-vectors just define a subspace perfectly, ' ...
0054         ' you do not need nonlinear optimization to find it. ' ...
0055         ' You shall pass, however.']);
0056 end
0057 if size(hcMatrix, 2) < par.targetDim
0058     warning('elk:decomposition:input', ['Have you recognized that your ' ...
0059         'problem allows a not countable and infinite number of solutions? ' ...
0060         'I will provide you one, but you have to find all of them by ' ...
0061         'yourself. Have fun. :D']);
0062 end
0063 
0064 %% basic parameters
0065 % .. they are always required
0066 
0067 % method
0068 checkArgumentList(methodApproxList, msgMethod, par.method);
0069 
0070 % target dimension
0071 if par.targetDim >= dec.nC
0072     error('elk:decomposition:wrongInput', ['The target dimension should be ' ...
0073         'lower than the dimension of the input representation in dec.']);
0074 end
0075 
0076 % zerotol should already be OK
0077     
0078 %% extended parameters
0079 % .. they apply only for nonlinear optimization (not PCA)
0080 if strcmpi(par.method, 'pca')
0081     return
0082 end
0083 
0084 % list of measures for error calculation
0085 if isempty(par.measureList)
0086     par.measureList = {'volume'};
0087 end
0088 if ~iscell(par.measureList)
0089     par.measureList = {par.measureList};
0090 end
0091 % do the measures exist?
0092 try
0093     sampleMeasureVector = computeMeasureDec(dec, 'hC', hcMatrix(:,1), ...
0094         par.measureList, par.zerotol, 0, 1);
0095 catch thisError
0096     warning(['elk:decomposition:wrongInput', 'Something is wrong with ' ...
0097         'the measure list or the hcMatrix you provided for approximateDec']);
0098     rethrow(thisError);
0099 end
0100 
0101 % error type
0102 checkArgumentList(methodErrorList, msgError, par.errorType);
0103 
0104 % measure weight vector
0105 if isempty(par.measureWeightVector)
0106     par.measureWeightVector = ones(1, length(sampleMeasureVector));
0107 else
0108     % ensure row vector
0109     par.measureWeightVector = par.measureWeightVector(:)';
0110 end
0111 
0112 % projection type
0113 checkArgumentList(methodProjectionList, msgProjection, par.projectionType);
0114 
0115 %! DEV: currently unused:
0116 % % distance limit
0117 % if isempty(par.distanceLimit)
0118 %     par.distanceLimit = max(hcMatrix(:))*1e-3;
0119 % end
0120 %
0121 % % penalty
0122 % if par.penaltySlope < 0
0123 %     error('elk:decomposition:wrongInput', 'the penalty slope must be positive');
0124 % end
0125 % if par.penaltyRatioLimit < 0 || par.penaltyRatioLimit > 1
0126 %     error('elk:decomposition:wrongInput', ['the penalty ratio limit ' ....
0127 %         ' must be in the interval [0, 1]']);
0128 % end
0129 %/
0130 
0131 % the following parameters are for debugging and should only be applied if
0132 %   you know what you do:
0133 if ~(numel(par.manualScaling) == 1) && all(par.manualScaling(:) == 0.5)
0134     warning('elk:decomposition:scalingMatrix', ['I hope, you know what ' ...
0135         'you are doing, providing a manual scaling (matrix).']);
0136 end
0137 if ~isempty(par.manualBoundingCone)
0138     warning('elk:decomposition:boundingCone', ['I hope, you know what ' ...
0139         'you are doing, providing a manual bounding cone']);
0140 end
0141 
0142 % if strcmpi(par.method, 'PCA')
0143 %     % nothing to do for manual initial condition
0144 % else
0145 %     if ~isempty(par.manualInitialCondition) && ...
0146 %             isnumeric(par.manualInitialCondition)
0147 %         warning('elk:decomposition:scalingMatrix', ['I hope, you know what ' ...
0148 %             'you are doing, providing a manual initial condition']);
0149 %     elseif isempty(par.manualInitialCondition) || ...
0150 %             strcmpi(par.manualInitialCondition, 'nonlinearLocal')
0151 %         disp('NONLINEAR')
0152 %         % the possibly more advanced initial condition is obtained by a
0153 %         %   local optimization run.
0154 %         thisPar = par;
0155 %         thisPar.method = 'nonlinearLocal';
0156 %         thisPar.manualInitialCondition = 'PCA';
0157 %         dataApprox = approximateDec(hcMatrix, dec, thisPar);
0158 %         par.manualInitialCondition = dataApprox.mappingReducedToEmbedding;
0159 %         disp('/NONLINEAR')
0160 %
0161 %     elseif strcmpi(par.manualInitialCondition, 'PCA')
0162 %         % the simple initial condition is the PCA solution
0163 %         disp('PCA')
0164 %         thisPar = par;
0165 %         thisPar.method = 'PCA';
0166 %         dataApprox = approximateDec(hcMatrix, dec, thisPar);
0167 %         par.manualInitialCondition = dataApprox.mappingReducedToEmbedding;
0168 %         disp('/PCA')
0169 %
0170 %     else
0171 %         error('elk:approximation:inputError', ['Please correct the value '...
0172 %             'for the manualInitialCondition option, it does not make sense.'])
0173 %     end
0174 % end
validateInput

PURPOSE

SYNOPSIS

DESCRIPTION

CROSS-REFERENCE INFORMATION

SOURCE CODE
