obtain a discrete probability distribution
Syntax: disD = obtainDistributionDiscrete(name, par)
OR disD = obtainDistributionDiscrete(name, 'option', value, ..)
This function returns a discrete realization of a probability
distribution. Common option/value pairs are:
'nSample' - number of sample points {100}
'verbose' - verbosity level (0 is off, 1 is on) {0}
The input "name" is one out of the list below. The input "par" is a
structure containing the parameters of the distribution. The supported
distributions are:
uniform polytope: uniform distribution in a given polytope;
parameters: poly (the polygon in V- or H-representation)
uniform ray: uniform distribution in a cone around a given ray,
parameters: ray (the center ray); radius (radius of the base at the
end of the ray)
normal: multivariate Gaussian normal distribution with parameters:
mean (vector with mean values); cov (matrix with covariances)
metropolis: the points are sampled by the Metropolis algorithm and
the first parameter set considers the Metropolis algorithm itself:
metroHanlde (distribution density @(x)), metroInit (an initial
point x for which metroHandle(x) should be large), metroCov (a
guess for the covariance matrix of sampled points), metroSpacing
(measure of the steps waited before a new sample is taken taken
relative to the time the autocorellation reaches a negative value
the first time), nSampleBatch (amount of points sampled in parallel
for speedup); the second set of parameters is used to estimate
the integral of the given distribution to calculate the probability
density: metroIntegral (the integral value that is directly used),
metroIntegralBatch (points to evaluate in each step of the Monte
Carlo Integration), metroRelTol (the coefficient of variation to
be obtained by the MC integration)
The output disD is a structure with the fields:
name - the name of the distribution
nDim - the dimension of the distribution
par - the input parameters of the distribution
pivotPositionMatrix - the coordinates the sampled points (each is a
column vector)
pivotProbabilityVector - the assigned value for the sample point
See also: obtainDistributiondisContinuous, discretizeDistribution0001 function disD = obtainDistributionDiscrete(name, varargin) 0002 % obtain a discrete probability distribution 0003 % 0004 % Syntax: disD = obtainDistributionDiscrete(name, par) 0005 % OR disD = obtainDistributionDiscrete(name, 'option', value, ..) 0006 % 0007 % This function returns a discrete realization of a probability 0008 % distribution. Common option/value pairs are: 0009 % 'nSample' - number of sample points {100} 0010 % 'verbose' - verbosity level (0 is off, 1 is on) {0} 0011 % 0012 % The input "name" is one out of the list below. The input "par" is a 0013 % structure containing the parameters of the distribution. The supported 0014 % distributions are: 0015 % uniform polytope: uniform distribution in a given polytope; 0016 % parameters: poly (the polygon in V- or H-representation) 0017 % uniform ray: uniform distribution in a cone around a given ray, 0018 % parameters: ray (the center ray); radius (radius of the base at the 0019 % end of the ray) 0020 % normal: multivariate Gaussian normal distribution with parameters: 0021 % mean (vector with mean values); cov (matrix with covariances) 0022 % metropolis: the points are sampled by the Metropolis algorithm and 0023 % the first parameter set considers the Metropolis algorithm itself: 0024 % metroHanlde (distribution density @(x)), metroInit (an initial 0025 % point x for which metroHandle(x) should be large), metroCov (a 0026 % guess for the covariance matrix of sampled points), metroSpacing 0027 % (measure of the steps waited before a new sample is taken taken 0028 % relative to the time the autocorellation reaches a negative value 0029 % the first time), nSampleBatch (amount of points sampled in parallel 0030 % for speedup); the second set of parameters is used to estimate 0031 % the integral of the given distribution to calculate the probability 0032 % density: metroIntegral (the integral value that is directly used), 0033 % metroIntegralBatch (points to evaluate in each step of the Monte 0034 % Carlo Integration), metroRelTol (the coefficient of variation to 0035 % be obtained by the MC integration) 0036 % 0037 % The output disD is a structure with the fields: 0038 % name - the name of the distribution 0039 % nDim - the dimension of the distribution 0040 % par - the input parameters of the distribution 0041 % pivotPositionMatrix - the coordinates the sampled points (each is a 0042 % column vector) 0043 % pivotProbabilityVector - the assigned value for the sample point 0044 % 0045 % 0046 % See also: obtainDistributiondisContinuous, discretizeDistribution 0047 0048 % The elk-library: convex geometry applied to crystallization modeling. 0049 % Copyright (C) 2013 Alexander Reinhold 0050 % 0051 % This program is free software: you can redistribute it and/or modify it 0052 % under the terms of the GNU General Public License as published by the 0053 % Free Software Foundation, either version 3 of the License, or (at your 0054 % option) any later version. 0055 % 0056 % This program is distributed in the hope that it will be useful, but 0057 % WITHOUT ANY WARRANTY; without even the implied warranty of 0058 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0059 % General Public License for more details. 0060 % 0061 % You should have received a copy of the GNU General Public License along 0062 % with this program. If not, see <http://www.gnu.org/licenses/> 0063 0064 %% input handling 0065 par = mapOptionStruct(varargin, 'nSample', 100, 'verbose', 0, ... 0066 'ray', 1, 'radius', 1, ... 0067 'mean', 1, 'cov', 1, ... 0068 'poly', obtainVrep('cube'), ... 0069 'metroInit', 1, 'metroCov', 1, 'metroHandle', @(x)(1./(x.^2+1)), ... 0070 'metroSpacing', 2, 'metroNonAdaptive', 10, 'metroNoHistory', 10, ... 0071 'metroHistory', 1000, 'metroLag', 100, 'metroShowAutoCor', 0, ... 0072 'metroRelTol', 0.01, 'metroIntegral', [], 'metroIntegralBatch', 1e5, ... 0073 'metroSampleBatch', 100 ... 0074 ); 0075 0076 if strcmpi(name, 'ray') || strcmpi(name, 'ray uniform') || ... 0077 strcmpi(name, 'uniform ray') 0078 0079 % basic information 0080 disD.name = 'uniform ray'; 0081 disD.nDim = length(par.ray); 0082 0083 0084 [disD.positionMatrix disD.probabilityVector] = sampleRay(... 0085 par.nSample, par.ray(:), par.radius); 0086 0087 % parameter mapping 0088 disD.parDiscrete.ray = par.ray(:); 0089 disD.parDiscrete.radius = par.radius; 0090 0091 elseif strcmpi(name, 'poly') || strcmpi(name, 'uniform poly') || ... 0092 strcmpi(name, 'polytope') || strcmpi(name, 'uniform polytope') || ... 0093 strcmpi(name, 'poly uniform') || strcmpi(name, 'polytope uniform') 0094 0095 % basic information 0096 disD.name = 'uniform polygon'; 0097 infoPoly = identifyPolytope(par.poly); 0098 disD.nDim = infoPoly.dim; 0099 0100 [disD.positionMatrix disD.probabilityVector] = samplePolygon(... 0101 par.nSample, par.poly); 0102 0103 % parameter mapping 0104 disD.parDiscrete.poly = par.poly; 0105 0106 elseif strcmpi(name, 'normal') || strcmpi(name, 'normal distribution') 0107 % basic information 0108 disD.name = 'normal'; 0109 disD.nDim = length(par.mean); 0110 [disD.parDiscrete.mean, disD.parDiscrete.cov] = ensureMeanAndCov(... 0111 disD.nDim, par.mean, par.cov); 0112 0113 % assign position & probability 0114 [disD.positionMatrix disD.probabilityVector] = sampleNormal(disD.nDim, ... 0115 par.nSample, disD.parDiscrete.mean, disD.parDiscrete.cov); 0116 0117 elseif strcmpi(name, 'metro') || strcmpi(name, 'metropolis') 0118 % basic information 0119 disD.name = 'metropolis'; 0120 0121 [disD.positionMatrix disD.probabilityVector disD.resMetro] = ... 0122 sampleMetropolis(par, par.nSample); 0123 0124 % parameter mapping 0125 disD.parDiscrete = par; 0126 0127 else 0128 0129 error('elk:distribution:wrongInput', ... 0130 ['The given distribution name (' name ') is not supported.']); 0131 end