2%> This is the base
class for the ParaMonte sampler basic specifications.<br>
5%> This is a low-level
class that is not meant to be used by the user.<br>
8%> See the documentation of the
class constructor.<br>
11%> All
class attributes can be set after constructing an instance of this class.<br>
14%> See below
for information on the methods.<br>
17%> [ParaDRAM simulation specifications listing](\pmdoc_usage_sampling/paradram/specifications/)<br>
22%> \JoshuaOsborne, May 21 2024, 3:38 AM, University of Texas at Arlington<br>
23%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
24%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
37 domainCubeLimitLower = [];
38 domainCubeLimitUpper = [];
40 domainErrCountMax = [];
41 outputChainFileFormat = [];
42 outputColumnWidth = [];
46 outputReportPeriod = [];
47 outputRestartFileFormat = [];
48 outputSampleSize = [];
50 outputSplashMode = [];
52 parallelismMpiFinalizeEnabled = [];
53 parallelismNumThread = [];
55 targetAcceptanceRate = [];
58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
60 properties(Hidden, Access =
protected)
67 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 methods(Access = public)
72 %> Construct and return an
object of class [pm.sampling.
SpecBase](@ref
SpecBase).
74 %> \param[in] method : The input scalar MATLAB
string containing
75 %> the
name of the specific ParaMonte sampler
76 %> whose simulation specifications are to be
77 %> stored in the output of this constructor.<br>
78 %> \param[in] silent : The input scalar MATLAB logical.<br>
79 %> If ``true``, all descriptive messages on
80 %> the MATLAB command line will be suppressed.<br>
81 %> (**optional**, default = ``false``)
84 %> The output scalar
object of class [pm.sampling.
SpecBase](@ref
SpecBase).<br>
87 %> [ParaDRAM simulation specifications listing](\pmdoc_usage_sampling/paradram/specifications/)<br>
93 %> spec = pm.sampling.SpecBase([])
94 %> spec = pm.sampling.SpecBase([], [])
95 %> spec = pm.sampling.SpecBase(method)
96 %> spec = pm.sampling.SpecBase(method, [])
97 %> spec = pm.sampling.SpecBase([], silent)
98 %> spec = pm.sampling.SpecBase(method, silent)
105 %> \JoshuaOsborne, May 21 2024, 3:40 AM, University of Texas at Arlington<br>
106 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
107 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
108 function self =
SpecBase(method, silent)
119 self.method = method;
123 %
if isa(ndim,
"real") || isa(ndim,
"int32")
124 %
if rem(ndim, 1) == 0
132 % error ( newline ...
133 % +
"The specified input value for ``ndim`` (" +
string(ndim) +
") must be a whole number (integer)." + newline ...
134 % +
"The variable ``ndim`` represents the number of dimensions of the domain" + newline ...
135 % +
"of the object function that is to be explored." + newline ...
142 %> Return documentation help
for the input simulation specification
name.<br>
145 %> Otherwise,
return documentation help
for all simulation specifications
146 %>
if the input ``specification`` argument is missing.<br>
149 %> The underlying reason
for unifying documentation of
object attributes
150 %> within a single online page is to significantly reduce duplication and
151 %> work required
for generating and maintaining such documentation across
152 %> all supported programming language environments.<br>
154 %> \param[in] self : The input parent
object of
class [pm.sampling.SpecBase](@ref
SpecBase)
155 %>
which is **implicitly** passed to
this dynamic method (not by the user).<br>
156 %> \param[in] specification : The input scalar MATLAB
string containing the
157 %>
name of a simulation specification corresponding
158 %> an attribute of the parent
object.<br>
161 %> ``
weblink`` : The output scalar MATLAB
string containing the web address
162 %>
for the documentation of the requested simulation specification.<br>
168 %>
weblink = self.doc(specification)
174 %> pmpd.spec.doc() %
return help
for all specifications.
175 %> pmpd.spec.doc(
"outputFileName") %
return help
for the specification ``outputFileName``.
182 %> \JoshuaOsborne, May 21 2024, 3:42 AM, University of Texas at Arlington<br>
183 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
184 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
185 function
weblink = doc(self, specification)
188 weblink = pm.web.href(self.url);
190 if isstring(specification) || ischar(specification)
191 specList = properties(self);
192 specListLen = length(specList);
193 for i = 1 : specListLen
194 if strcmpi(specList{i}, specification)
195 specLower =
"#" + lower(specification);
196 weblink = pm.web.href(self.url + specLower);
201 +
"The input specification must be a string or char vector " + newline ...
202 +
"whose value is the name of one of the specification properties" + newline ...
203 +
"of the sampler as specified in the ``spec`` component." + newline ...
204 +
"Example usage:" + newline ...
206 + pm.io.tab +
"doc()" + newline ...
207 + pm.io.tab +
"doc(""chainSize"")" + newline ...
216 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
221 %> Ensure all specification properties of the parent
object are sensible.<br>
222 %> This is a dynamic method of the
class [pm.sampling.SpecBase](@ref
SpecBase).<br>
224 %> \param[inout] self : The input/output parent
object of
class [pm.sampling.SpecBase](@ref
SpecBase)
225 %>
which is **implicitly** passed to
this dynamic method (not by the user).<br>
226 %> \param[in] ndim : The input scalar MATLAB integer containing
227 %> the number of dimensions of the domain of the
228 %>
object function that is to be explored.<br>
231 %> ``entries`` : The output scalar MATLAB
string containing
232 %> the simulation specifications converted to
233 %> a Fortran-namelist-compatible entry.<br>
235 %> \interface{getEntriesNML}
238 %> entries = self.getEntriesNML(ndim)
242 %> \final{getEntriesNML}
245 %> \JoshuaOsborne, May 21 2024, 3:43 AM, University of Texas at Arlington<br>
246 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
247 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
248 function entries = getEntriesNML(self, ndim)
249 if isempty(self.outputFileName)
250 % First define ``outputFileName``
if it is empty.
251 self.outputFileName = fullfile(
string(pwd), pm.io.getFileName(self.method));
252 elseif pm.introspection.istype(self.outputFileName,
"string", 1)
253 if ~self.silent && contains(self.outputFileName,
" ")
254 warning ( newline ...
255 + "The specified simulation specification ``outputFileName`` contains whitespace characters(s)." + newline ...
256 + "Blanks are infamous for causing software crashes and failures." + newline ...
257 + "Best is to blanks and special characters in paths." + newline ...
261 if endsWith(self.outputFileName, "\") || endsWith(self.outputFileName, "/")
262 self.outputFileName = fullfile(
string(pm.sys.path.
abs(self.outputFileName, "lean")), pm.io.
getFileName(self.method));
266 if ~isempty(self.description ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("description ", self.description , "
string" , 1); end
267 if ~isempty(self.domain ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domain ", self.domain , "
string" , 1); end
268 if ~isempty(self.domainAxisName ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainAxisName ", self.domainAxisName , "
string" , ndim); end
269 if ~isempty(self.domainBallAvg ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainBallAvg ", self.domainBallAvg , "real" , ndim); end
270 if ~isempty(self.domainBallCor ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainBallCor ", self.domainBallCor , "real" , ndim^2); end
271 if ~isempty(self.domainBallCov ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainBallCov ", self.domainBallCov , "real" , ndim^2); end
272 if ~isempty(self.domainBallStd ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainBallStd ", self.domainBallStd , "real" , ndim); end
273 if ~isempty(self.domainCubeLimitLower ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainCubeLimitLower ", self.domainCubeLimitLower , "real" , ndim); end
274 if ~isempty(self.domainCubeLimitUpper ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainCubeLimitUpper ", self.domainCubeLimitUpper , "real" , ndim); end
275 if ~isempty(self.domainErrCount ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainErrCount ", self.domainErrCount , "integer", 1); end
276 if ~isempty(self.domainErrCountMax ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("domainErrCountMax ", self.domainErrCountMax , "integer", 1); end
277 if ~isempty(self.outputChainFileFormat ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputChainFileFormat ", self.outputChainFileFormat , "
string" , 1); end
278 if ~isempty(self.outputColumnWidth ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputColumnWidth ", self.outputColumnWidth , "integer", 1); end
279 if ~isempty(self.outputFileName ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputFileName ", self.outputFileName , "
string" , 1); end
280 if ~isempty(self.outputStatus ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputStatus ", self.outputStatus , "
string" , 1); end
281 if ~isempty(self.outputPrecision ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputPrecision ", self.outputPrecision , "integer", 1); end
282 if ~isempty(self.outputReportPeriod ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputReportPeriod ", self.outputReportPeriod , "integer", 1); end
283 if ~isempty(self.outputRestartFileFormat ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputRestartFileFormat ", self.outputRestartFileFormat , "
string" , 1); end
284 if ~isempty(self.outputSampleSize ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputSampleSize ", self.outputSampleSize , "integer", 1); end
285 if ~isempty(self.outputSeparator ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputSeparator ", self.outputSeparator , "
string" , 1); end
286 if ~isempty(self.outputSplashMode ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("outputSplashMode ", self.outputSplashMode , "
string" , 1); end
287 if ~isempty(self.parallelism ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("parallelism ", self.parallelism , "
string" , 1); end
288 if ~isempty(self.parallelismMpiFinalizeEnabled ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("parallelismMpiFinalizeEnabled", self.parallelismMpiFinalizeEnabled , "logical", 1); end
289 if ~isempty(self.parallelismNumThread ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("parallelismNumThread ", self.parallelismNumThread , "integer", 1); end
290 if ~isempty(self.randomSeed ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("randomSeed ", self.randomSeed , "integer", 1); end
291 if ~isempty(self.targetAcceptanceRate ); entries = entries + self.nmlsep + pm.introspection.
getEntryNML("targetAcceptanceRate ", self.targetAcceptanceRate , "real" , 2); end
293 % % These methods have been implemented to override the default 'handle' class methods,
294 % % so that they will not pop-up after pressing 'Tab' button.
295 % function addlistener (self) end
296 % function delete (self) end
297 % function findobj (self) end
298 % function findprop (self) end
299 % function valid (self) end
300 % function listener (self) end
301 % function notify (self) end
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.
function abs(in path, in style)
Return the Get absolute canonical path of a file or folder.
This is the base class for generating subclass of MATLAB handle superclass whose annoying methods are...
This is the base class for the ParaMonte sampler basic specifications.
Property outputReportPeriod
function getEntriesNML(in self, in ndim)
Ensure all specification properties of the parent object are sensible. This is a dynamic method of t...
Property outputColumnWidth
Property outputChainFileFormat
function SpecBase(in method, in silent)
Construct and return an object of class pm.sampling.SpecBase.
Property parallelismMpiFinalizeEnabled
function doc(in self, in specification)
Return documentation help for the input simulation specification name.
Property domainCubeLimitLower
Property parallelismNumThread
Property targetAcceptanceRate
Property domainCubeLimitUpper
Property outputSampleSize
Property outputSplashMode
Property outputRestartFileFormat
Property domainErrCountMax
function getEntryNML(in varname, in varval, in vartype, in varsize)
Return a Fortran-namelist-compatible conversion of the input varval.
function getFileName(in prefix)
Return a scalar MATLAB string containing a file name based on the current date and time.
function weblink(in silent)
Return a scalar MATLAB string containing the download weblink to latest ParaMonte MATLAB library vers...
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...