ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
Paradram.m
Go to the documentation of this file.
1%> \brief
2%> This is the ParaDRAM class for generating instances of serial and parallel
3%> Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo
4%> sampler of the ParaMonte MATLAB library.<br>
5%>
6%> \details
7%> For more information, see the documentation of the class
8%> constructor [pm.sampling.Paradram::Paradram](@ref Paradram::Paradram).<br>
9%>
10%> \note
11%> See the documentation of the class constructor for usage interface and examples.<br>
12%>
13%> \final
14%>
15%> \author
16%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
17classdef Paradram < pm.sampling.Sampler
18
19 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20
21 methods(Access = public)
22
23 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24
25 %> \brief
26 %> Generate and return an instance of the serial and parallel
27 %> Delayed-Rejection Adaptive Metropolis-Hastings Markov Chain Monte Carlo
28 %> sampler of the ParaMonte MATLAB library.<br>
29 %>
30 %> \details
31 %> This function is the constructor of the [pm.sampling.Paradram](@ref Paradram) sampler class.<br>
32 %> Once you assign the desired simulation specifications to the corresponding attributes within the
33 %> component `spec` of an object of class [pm.sampling.Paradram](@ref Paradram), call the ParaDRAM
34 %> sampler via the object method [pm.sampling.Paradram.run()](@ref Paradram::run).<br>
35 %>
36 %> While the constructor of this class does not take any input arguments,
37 %> all ParaDRAM simulation specifications can be set after creating the object.<br>
38 %>
39 %> \return
40 %> ``sampler`` : The output scalar object of class [pm.sampling.Paradram](@ref Paradram).<br>
41 %>
42 %> \interface{Paradram}
43 %> \code{.m}
44 %>
45 %> sampler = pm.sampling.Paradram();
46 %>
47 %> \endcode
48 %>
49 %> \warning
50 %> When using the ParaMonte MATLAB library functionalities, particularly ParaMonte samplers in parallel,
51 %> it would be best to close any such aggressive software/applications as **Dropbox**, **ZoneAlarm**, ...
52 %> that interfere with your ParaMonte MATLAB library output files, potentially causing the tasks
53 %> to fail and crash before successful completion.<br>
54 %> These situations scarcely happen.<br>
55 %>
56 %> \note
57 %> On Windows systems, when restarting an old interrupted ParaDRAM simulation,
58 %> ensure your MATLAB session is also restarted before the simulation restart.<br>
59 %> This may be needed as **Windows frequently locks access to some or all simulation output files**.<br>
60 %>
61 %> \note
62 %> To unset an already-set input simulation specification, simply set the
63 %> simulation attribute to empty double `[]` or re-instantiate an object
64 %> of class [pm.sampling.Paradram.run()](@ref Paradram).<br>
65 %>
66 %> \see
67 %> [ParaDRAM simulation specifications listing](\pmdoc_usage_sampling/paradram/specifications/)<br>
68 %> [ParaDRAM simulation restart functionality](\pmdoc_usage_sampling/paradram/restart/)<br>
69 %> [ParaDRAM simulation output files](\pmdoc_usage_sampling/paradram/output/)<br>
70 %>
71 %> ParaDRAM Simulation Specifications
72 %> ----------------------------------
73 %>
74 %> The ParaDRAM simulation specifications have lengthy comprehensive descriptions
75 %> that appear in full in the output report files of every ParaDRAM simulation.<br>
76 %>
77 %> The best way to learn about individual ParaDRAM simulation attributes
78 %> is to a run a minimal serial simulation as given in the above.<br>
79 %> You can also use the ``sampler.spec.doc()`` method:
80 %>
81 %> \code{.m}
82 %> sampler = pm.sampling.Paradram();
83 %> sampler.spec.doc()
84 %> \endcode
85 %>
86 %> Example Usage: Serial
87 %> ---------------------
88 %>
89 %> First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.
90 %>
91 %> Here is a MATLAB script ``main.m`` for a serial ParaDRAM simulation.<br>
92 %> Copy and paste the following code into your MATLAB session:<br>
93 %>
94 %> \code{.m}
95 %>
96 %> ndim = 4;
97 %> sampler = pm.sampling.Paradram();
98 %> sampler.run ( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function.
99 %> , ndim ... ndim: the number of dimensions of the objective function.
100 %> );
101 %> samples = sampler.readSample();
102 %> sample = samples{1};
103 %> tile = pm.vis.TileLine(sample.df);
104 %> tile.make("coly", sample.slfc + 1 : sample.slfc + ndim, "colc", "sampleLogFunc");
105 %>
106 %> \endcode
107 %>
108 %> The mathematical objective function in the above example is a
109 %> is a multivariate Normal distribution centered at the origin,
110 %> whose natural logarithm is returned by the lambda (``Anonymous``)
111 %> function defined as a function handle input to the ParaDRAM sampler.<br>
112 %>
113 %> Running this code will generate a set of simulation output files (in the current working directory of MATLAB).<br>
114 %> Among these, the file suffixed with "_report.txt" contains the full description of all input specifications
115 %> of the ParaDRAM simulation as well as other information about the simulation results.<br>
116 %>
117 %> Example Usage: Thread-Parallel
118 %> ------------------------------
119 %>
120 %> First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.<br>
121 %>
122 %> Threading parallelism is possible as of ParaMonte MATLAB version ``3.0.0``.<br>
123 %> However, only ``singleChain`` ParaDRAM simulations are supported.<br>
124 %>
125 %> Here is a MATLAB script ``main.m`` for a thread-parallel ParaDRAM simulation.<br>
126 %> Copy and paste the following code and paste into your MATLAB session:<br>
127 %>
128 %> \code{.m}
129 %>
130 %> sampler = pm.sampling.Paradram();
131 %> sampler.spec.parallelismNumThread = 0; % use all available threads.
132 %> sampler.run ( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function.
133 %> , 4 ... ndim: the number of dimensions of the objective function.
134 %> );
135 %> samples = sampler.readSample();
136 %> sample = samples{1};
137 %> sample.vis.tile.line.make();
138 %> sample.vis.triplex.lshc2.make(); % Make a corner scatter/density-contour plot.
139 %>
140 %> \endcode
141 %>
142 %> The statement ``sample.vis.tile.line.make();`` in
143 %> the above is equivalent to the following set of lines:
144 %>
145 %> \code{.m}
146 %>
147 %> tile = pm.vis.TileLine(sample.df);
148 %> tile.make("coly", sample.slfc + 1 : sample.slfc + 4, "colc", "sampleLogFunc");
149 %>
150 %> \endcode
151 %>
152 %> The mathematical objective function in the above example is a
153 %> is a multivariate Normal distribution centered at the origin,
154 %> whose natural logarithm is returned by the lambda (``Anonymous``)
155 %> function defined as a function handle input to the ParaDRAM sampler.<br>
156 %>
157 %> Running this code will generate a set of simulation output files (in the current working directory of MATLAB).<br>
158 %> Among these, the file suffixed with ``"_report.txt"`` contains the full description of all input specifications
159 %> of the ParaDRAM simulation as well as other information about the simulation results.<br>
160 %>
161 %> Specifying ``0`` as the number of threads will lead to using
162 %> all available CPU threads for thread-parallel ParaDRAM simulation.<br>
163 %>
164 %> \note
165 %> **Benefits of thread-parallelism**<br>
166 %> Thread-parallel simulations offer a much more flexible
167 %> and easier approach to benefiting from parallelism without
168 %> going through the hassle of MPI-parallel simulations.<br>
169 %> But they can still potentially offer much faster speed than serial simulations.<br>
170 %> The actual speedup depends on a lot of factors.<br>
171 %> Moreover, the number of threads is limited to maximum
172 %> number of physical cores available on your system.<br>
173 %> As such, thread-parallel simulations are not scalable.<br>
174 %> If you need scalability, checkout MPI-parallelism below.<br>
175 %>
176 %> Example Usage: MPI-Parallel
177 %> ---------------------------
178 %>
179 %> First, ensure the ParaMonte ``+pm`` package (i.e., folder) is available in your MATLAB paths.<br>
180 %>
181 %> MPI-parallel simulations can be slightly more cumbersome than thread-parallel simulations
182 %> described above because MPI-parallel simulations cannot be performed from within a MATLAB GUI
183 %> session and require launching MATLAB via a compatible ``mpiexec`` launcher.<br>
184 %>
185 %> <ol>
186 %> <li> Ensure you need and will get a speedup by running the an MPI-parallel simulation.<br>
187 %> Typically, your simulation may then benefit from parallelism only if a single
188 %> evaluation of the objective function takes longer than a few milliseconds.<br>
189 %>
190 %> <li> Ensure the required MPI libraries are installed on your system
191 %> (You can skip this step if you know that you already have
192 %> a compatible MPI library installed on your system).<br>
193 %> On the MATLAB command line type the following,<br>
194 %> \code{.m}
195 %> pm.lib.verify();
196 %> \endcode
197 %> This will verify the existence of a valid MPI library on your system and,
198 %> if missing, will guide you to install the MPI library on your system.<br>
199 %>
200 %> <li> Once the MPI installation is verified, copy and paste the following
201 %> code into your MATLAB session:
202 %> \code{.m}
203 %>
204 %> fid = fopen("main_mpi.m", "w");
205 %> sourceCode = ...
206 %> "sampler = pm.sampling.Paradram();" + newline + ...
207 %> "%sampler.mpiname = ''; % set this to an explicit MPI library name if needed." + newline + ...
208 %> "sampler.run( @(x) - sum(x.^2) ... getLogFunc: the natural log of the objective function." + newline + ...
209 %> " , 4 ... ndim: the number of dimensions of the objective function" + newline + ...
210 %> " );";
211 %> fprintf(fid, "%s\n", sourceCode);
212 %> fclose(fid);
213 %>
214 %> \endcode
215 %>
216 %> <li> This will generate a ``main_mpi.m`` MATLAB script file in the current working directory of your MATLAB session.<br>
217 %> Now, you can execute this MATLAB script file (``main_mpi.m``) in parallel.<br>
218 %> To do so, you need to call MATLAB on a command-line, **out of MATLAB GUI**.<br>
219 %> <ol>
220 %> <li> **On Windows**:<br>
221 %> From within command prompt that recognizes both MATLAB and ``mpiexec``,
222 %> ideally, the Intel dedicated command-prompt that is shipped with Intel MPI library,
223 %> type the following,
224 %> \code{.m}
225 %>
226 %> mpiexec -localonly -n 3 matlab -batch "main_mpi"
227 %>
228 %> \endcode
229 %>
230 %> \note
231 %> In the above MPI launcher command for Windows OS,
232 %> we assumed that you would be using the Intel MPI library, hence,
233 %> the reason for the extra flag ``-localonly``.<br>
234 %> This flag runs the parallel code only on one node, but in doing so,
235 %> it avoids the use of Hydra service and its registration.<br>
236 %> If you are not on a Windows cluster, (e.g., you are using your personal device),
237 %> then we recommend specifying this flag.<br>
238 %>
239 %> <li> **On macOS/Linux**:<br>
240 %> From within a Bash terminal that recognizes both MATLAB and ``mpiexec``,
241 %> type the following,
242 %> \code{.m}
243 %>
244 %> mpiexec -n 3 matlab -batch "main_mpi"
245 %>
246 %> \endcode
247 %>
248 %> \note
249 %> In both cases in the above, the script ``main_mpi.m`` will run on 3 processors.<br>
250 %> Feel free to change the number of processors to any number desired.<br>
251 %> But do not request more than the available number of physical cores on your system.<br>
252 %> </ol>
253 %> </ol>
254 %>
255 %> \warning
256 %> Do not add postprocessing codes (such as reading and plotting the output samples) in your MPI-parallel code.<br>
257 %> There is no point in doing so, since MATLAB will run in ``-batch`` mode for parallel simulations, disabling all plotting capabilities.<br>
258 %> Moreover, if you read and postprocess the output files in parallel mode, the task will be done
259 %> by all parallel processes, potentially overwriting external IO activities of each other.<br>
260 %> Only perform the sampling as described above in MPI-parallel mode.<br>
261 %>
262 %> \example{himmelblau}
263 %> \include{lineno} example/sampling/Paradram/himmelblau/main.m
264 %> \output{himmelblau}
265 %> \include{lineno} example/sampling/Paradram/himmelblau/main.out.m
266 %> \vis{himmelblau}
267 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.domain.2d.png width=700
268 %> <br><br>
269 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.domain.3d.png width=700
270 %> <br><br>
271 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.triplex.lshc2.png width=700
272 %> <br><br>
273 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.triplex.lshc3.png width=700
274 %> <br><br>
275 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.triplex.lshcf.png width=700
276 %> <br><br>
277 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.traceplot.png width=700
278 %> <br><br>
279 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.proposalCov.png width=700
280 %> <br><br>
281 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.proposalAdaptation.png width=700
282 %> <br><br>
283 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.proposalAdaptation.line.png width=700
284 %> <br><br>
285 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.proposalAdaptation.scatter.png width=700
286 %> <br><br>
287 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.parallelism.speedup.scaling.strong.sameeff.png width=700
288 %> <br><br>
289 %> \image html example/sampling/Paradram/himmelblau/Paradram.himmelblau.parallelism.speedup.scaling.strong.zeroeff.png width=700
290 %>
291 %> \final{Paradram}
292 %>
293 %> \author
294 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
295 function self = Paradram()
296 self = self@pm.sampling.Sampler("ParaDRAM")
297 end
298
299 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
300
301 run(self, getLogFunc, ndim)
302
303 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
304
305 chainMarkovList = readChainMarkov(self, pattern, sep)
306
307 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
308
309 end
310
311 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
312
313 methods(Hidden)
314
315 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
316
317 ppm = getppm(self)
318
319 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
320
321 end
322
323 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
324
325end
verify
function verify(in varval, in vartype, in varsize, in varname)
Verify the type and number of elements of the input varval match the specified input vartype and vars...
version
function version(in silent)
Return a scalar MATLAB string containing the latest available ParaMonte MATLAB version newer than the...
Paradram
This is the ParaDRAM class for generating instances of serial and parallel Delayed-Rejection Adaptive...
Definition: Paradram.m:18
Paradram::getppm
function getppm(in self)
Generate and return the relevant Post-Processing Message (ppm) for the current ParaMonte sampler to b...
Paradram::run
function run(in self, in getLogFunc, in ndim)
Run the ParaDRAM sampler and return nothing.
Paradram::Paradram
function Paradram()
Generate and return an instance of the serial and parallel Delayed-Rejection Adaptive Metropolis-Hast...
Paradram::readChainMarkov
function readChainMarkov(in self, in pattern, in sep)
Return a list of objects of class pm.sampling.FileContentsChainDRAM containing the content(s) of the ...
Sampler
This is the base class for the ParaMonte sampler routines.
Definition: Sampler.m:21
copy
function copy(in from, in to, in field, in exclude)
Copy the contents of the struct/object from to the struct/object to recursively and without destroyin...
getLogFunc
function getLogFunc(in point)
install
function install(in vendor, in isyes)
Install or provide instructions to install the MPI library from the requested input MPI vendor.
parallel
function parallel()
Return a scalar MATLAB logical that is true if and only if the current installation of MATLAB contain...