2%> This is the base
class for the ParaMonte sampler routines.
5%> See below
for information on the attributes (properties).
8%> See below
for information on the methods.
11%> Given the basic primitive nature of
this class, it does not have a custom constructor.<br>
12%> Users should always use the subclasses of
this base
class.<br>
17%> \JoshuaOsborne, May 21 2024, 12:43 AM, University of Texas at Arlington<br>
18%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
19%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
22 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24 properties(Access =
public)
26 %> ``input`` : Optional scalar MATLAB
string representing the path to an external
27 %> input file that contains the simulation specification namelist(s).
30 %> <b>Use
this optional argument only
if you know what you are doing</b>.<br>
31 %> Specifying an input simulation file will force the ParaMonte sampler
32 %> to ignore all other simulation specifications set by the user via
33 %> the ``spec`` component of the sampler instance.<br>
37 %> ``checked`` : Optional scalar MATLAB logical.<br>
38 %> If set to ``
true``, then the checked (verified) versions of the
39 %> ParaMonte MATLAB shared libraries will be used
for simulations.<br>
40 %> This means that most function calls and computations will be
41 %> checked at runtime to ensure correctness, at the cost of
42 %> noticeably slower runtime simulation speeds.<br>
43 %> Set
this option to ``
true`` only
for diagnostics, testing, and development.<br>
44 %> If set to empty, the sampler will first search
for the non-checked
version
45 %> and
if none found, will search
for a checked
version of the library.<br>
49 %> ``mpiname`` : Optional scalar MATLAB
string representing the (
vendor)
name of the
50 %> MPI runtime library. The following three library names are supported:<br>
52 %> <li> ``
"impi"`` : The Intel MPI runtime library (Windows/Linux).<br>
53 %> <li> ``
"mpich"`` : The MPICH MPI runtime library (Linux/macOS).<br>
54 %> <li> ``
"openmpi"`` : The OpenMPI runtime library (Linux/macOS).<br>
56 %> By
default, you should set
this argument to [pm.lib.mpi.choice()](@ref
choice)
57 %> to enable the right preferred
choice of MPI-enabled ParaMonte libraries.<br>
58 %> If
for any reason, you want to use a non-preferred non-
default MPI library,
59 %> you can set the MPI library
name explicitly as in the above
list.<br>
60 %> Beware that you must launch MATLAB with an ``mpiexec`` binary that
61 %> comes from the same MPI library
vendor specified
for ``mpiname``.<br>
62 %> Note that the MPI-
parallel ParaMonte shared libraries
63 %> corresponding to the specified value
for ``mpiname``
64 %> may not exist in the ParaMonte package.<br>
67 %> <li> On Windows, only ParaMonte library
68 %> builds with Intel MPI are supported.<br>
69 %> <li> On Linux, the ParaMonte library builds with
70 %> all MPI libraries listed above are supported,
71 %> but there is no guarantee of their availability in
72 %> the package. Only the ParaMonte library builds with
73 %> Intel MPI (``
"impi"``) are guaranteed to exist,
74 %> unless user builds the ParaMonte MATLAB
package
75 %> from GitHub source for the desired MPI library.<br>
76 %> <li> On Darwin (macOS), only the ParaMonte shared library
77 %> builds with MPICH and OpenMPI libraries are supported,
78 %> but there is no guarantee of their availability in the
79 %> package. Only the ParaMonte library builds with OpenMPI
80 %> (``"openmpi"``) are guaranteed to exist, unless user
81 %> builds the ParaMonte MATLAB package from GitHub
82 %> source for the desired specified MPI library.<br>
85 %> <b>USE THIS OPTIONAL ARGUMENT ONLY IF YOU KNOW ITS RAMIFICATIONS</b>.<br>
86 %> This option should rarely be needed in any normal simulation.<br>
87 %> The default value for ``mpiname`` is an empty string, implying
88 %> no use of MPI-enabled ParaMonte library routines.<br>
92 %> ``silent`` : Optional logical (Boolean) indicator
which is ``
false`` by
default.<br>
93 %> If it is set to ``
true``, it will silence all output postprocessing messages.<br>
96 %> Setting ``mpiname`` to a non-empty
string
97 %> will automatically set ``silent`` to ``
true``.<br>
101 %> ``spec`` : A MATLAB structure containing all simulation specifications.<br>
102 %> All specifications are set to appropriate
default values at runtime.<br>
103 %> Set the `spec` attributes to the desired values of your
choice
104 %> to
override the
default simulation specifications.<br>
109 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
111 properties(Access =
public, Hidden)
112 mexname =
"pm_sampling";
116 bldtype =
""; % build type
117 clstype =
""; %
compiler/linker suite
120 matpath = []; % MATLAB paths.
126 %> ``libspec`` : Optional scalar MATLAB
string containing a
list of colon-(:)-separated
127 %> configurations of the kernel shared library to be used
for the sampling task.<br>
128 %> The most important of all is the
compiler suite with
which the library is built.<br>
131 %> <b>Use
this optional argument only
if you know what you are doing</b>.<br>
132 %> The specified value
for ``libspec`` is parsed internally to match a
133 %> corresponding library path
name within the ParaMonte library.<br>
134 %> The simulations will fail
if no such directory can be found.<br>
139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
141 methods(Access =
public)
143 %> Return a scalar
object of
class [pm.sampling.Sampler``.<br>
146 %> This is the constructor of the
class [pm.sampling.Sampler](@ref
Sampler).<br>
147 %> This
class is not meant to be accessed by the end users.<br>
148 %> It merely serves as the blueprint
for the sampler subclasses
149 %> accessible to the end users.<br>
151 %> \param[in] method : The input scalar MATLAB
string containing
152 %> the
name of the target ParaMonte sampler.<br>
155 %> ``self`` : The output scalar
object of
class [pm.sampling.Sampler](@ref
Sampler).<br>
160 %> sampler = pm.sampling.
Sampler();
161 %> sampler = pm.sampling.Sampler([]);
162 %> sampler = pm.sampling.Sampler(method);
169 %> \JoshuaOsborne, May 21 2024, 12:52 AM, University of Texas at Arlington<br>
170 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
171 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute
for Computational Engineering and Sciences (ICES), UT Austin<br>
172 function self =
Sampler(method)
176 self.method = string(method);
178 self.weblinks = pm.lib.weblinks();
179 if self.method ==
"ParaDRAM"
180 self.spec = pm.sampling.SpecDRAM(self.method);
181 elseif self.method ==
"ParaNest"
182 self.spec = pm.sampling.SpecNest(self.method);
183 elseif self.method ==
"sampler"
184 self.spec = pm.sampling.SpecBase(self.method);
187 +
"Unrecognized or unsupported ParaMonte sampler: " + self.method + newline ...
191 %filePath = mfilename(
"fullpath"); addpath(genpath(filePath),
"-begin");
192 self.name = inputname(1);
195 reportList = readReport(self, pattern)
196 restartList = readRestart(self, pattern)
197 chainList = readChain(self, pattern, sep)
198 sampleList = readSample(self, pattern, sep)
199 progressList = readProgress(self, pattern, sep)
206 fileList = findfile(self, ftype, pattern);
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared libraries.
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
function choice()
Return the ParaMonte-preferred MPI library vendor name as used in naming the ParaMonte MATLAB shared ...
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 routines.
function readSample(in self, in pattern, in sep)
Return a list of objects of class pm.sampling.FileContentsSample containing the content(s) of the Par...
function run(in self, in getLogFunc, in ndim)
Perform the basic runtime checks for the sampler and return nothing.
function getLogFuncConcurrent(in state)
function Sampler(in method)
Return a scalar object of class [pm.sampling.Sampler``.
function readReport(in self, in pattern)
Return a list of objects of class pm.sampling.FileContentsReport containing the content(s) of the Par...
function readChain(in self, in pattern, in sep)
Return a list of objects of class pm.sampling.FileContentsChain containing the content(s) of the Para...
function getLogFuncWrapped(in state)
function findfile(in self, in ftype, in pattern)
Return a vector of MATLAB strings containing the fully-resolved paths matching the input pattern.
function readRestart(in self, in pattern)
Return a list of objects of class pm.sampling.FileContentsRestartDRAM containing the content(s) of th...
function readProgress(in self, in pattern, in sep)
Return a list of objects of class pm.sampling.FileContentsProgress containing the content(s) of the P...
function finalize(in self)
Finalize the ParaMonte MATLAB sampler simulation run and return nothing.
function compiler()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
function getLogFunc(in point)
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...
function vendor(in path)
Return the a MATLAB string containing the MPI library vendor name corresponding to the input mpiexec ...
function weblinks()
Return a structure containing tree of weblinks for the ParaMonte MATLAB library source file and docum...
function which(in vendor)
Return the a MATLAB string containing the path to the first mpiexec executable binary found in system...