ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
FileContentsRestartDRAM.m
Go to the documentation of this file.
1%> \brief
2%> This is the base class for generating objects
3%> that contain the contents of a restart file
4%> generated by a ParaMonte sampler.<br>
5%>
6%> \details
7%> This class is meant to be primarily internally
8%> used by the ParaMonte MATLAB library samplers.<br>
9%>
10%> \warning
11%> The attributes of this class are considered
12%> internal implementation of the ParaMonte library.<br>
13%> As such, the interface of this class may change over time.<br>
14%>
15%> \brief
16%> See the documentation of the class constructor.<br>
17%>
18%> \note
19%> See below for information on the attributes (properties).<br>
20%>
21%> \note
22%> See below for information on the methods.<br>
23%>
24%> \final{FileContentsRestartDRAM}
25%>
26%> \author
27%> \JoshuaOsborne, May 21 2024, 3:26 AM, University of Texas at Arlington<br>
28%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
29%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
30classdef FileContentsRestartDRAM < pm.sampling.FileContentsRestart
31
32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
33
34 properties(Access = public)
35 %>
36 %> ``meanAcceptanceRateSinceStart``
37 %>
38 %> The real-valued MATLAB array of rank ``1`` of
39 %> shape ``(1:self.count)`` containing the set of
40 %> average MCMC acceptance rates of the sampler proposal
41 %> distribution over the course of the simulation.<br>
42 %>
43 meanAcceptanceRateSinceStart = [];
44 %>
45 %> ``proposalAdaptiveScaleSq``
46 %>
47 %> The real-valued MATLAB array of rank ``1`` of
48 %> shape ``(1:self.count)`` containing the set of
49 %> adaptive squared scale factors of the sampler proposal
50 %> distribution over the course of the simulation.<br>
51 %>
52 proposalAdaptiveScaleSq = [];
53 %>
54 %> ``proposalCor``
55 %>
56 %> The real-valued MATLAB array of rank ``3`` of
57 %> shape ``(self.ndim, self.ndim, self.count)`` containing
58 %> the set of correlation matrices of the proposal distribution
59 %> of the sampler, representing the evolution of the proposal
60 %> correlation matrix over the course of the simulation.<br>
61 %>
62 proposalCor = [];
63 %>
64 %> ``proposalCov``
65 %>
66 %> The real-valued MATLAB array of rank ``3`` of
67 %> shape ``(1:self.ndim, 1:self.ndim, 1:self.count)`` containing
68 %> the set of covariance matrices of the proposal distribution
69 %> of the sampler, representing the evolution of the proposal
70 %> covariance matrix over the course of the simulation.<br>
71 %>
72 proposalCov = [];
73 %>
74 %> ``proposalCovLogVol``
75 %>
76 %> The real-valued MATLAB array of rank ``1`` of
77 %> shape ``(1:self.count)`` containing the set of
78 %> ``log(determinant(covmat))`` of the proposal distribution
79 %> representing the evolution of mean of proposal distribution
80 %> over the course of the simulation.<br>
81 %>
82 proposalCovLogVol = [];
83 %>
84 %> ``proposalMean``
85 %>
86 %> The real-valued MATLAB array of rank ``2`` of
87 %> shape ``(1:self.ndim, 1:self.count)`` containing
88 %> the set of mean vectors of the proposal distribution
89 %> of the sampler, representing the evolution of the proposal
90 %> mean over the course of the simulation.<br>
91 %>
92 proposalMean = [];
93 %>
94 %> ``uniqueStateVisitCount``
95 %>
96 %> The scalar MATLAB integer containing the number of
97 %> states uniquely visited within the domain of the
98 %> objective function up to the stage specified
99 %> within the specified restart file.<br>
100 %>
101 uniqueStateVisitCount = [];
102 %>
103 %> ``vis``
104 %>
105 %> The scalar MATLAB ``struct`` containing the set of
106 %> predefined visualizations for the restart data.<br>
107 %>
108 vis = [];
109 end
110
111 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
112
113 methods(Access = public)
114
115 %> \brief
116 %> Return a scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
117 %>
118 %> \details
119 %> This is the constructor of the class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
120 %>
121 %> \param[in] file : The input scalar MATLAB string containing the path to an external report file.<br>
122 %> \param[in] silent : See the corresponding argument of [pm.sampling.FileContentsRestart](@ref FileContentsRestart) class.<br>
123 %> (**optional**. The default is set by [pm.sampling.FileContentsRestart](@ref FileContentsRestart).)
124 %>
125 %> \return
126 %> ``self`` : The output scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
127 %>
128 %> \interface{FileContentsRestartDRAM}
129 %> \code{.m}
130 %>
131 %> contents = pm.sampling.FileContentsRestartDRAM(file)
132 %> contents = pm.sampling.FileContentsRestartDRAM(file, [])
133 %> contents = pm.sampling.FileContentsRestartDRAM(file, silent)
134 %>
135 %> \endcode
136 %>
137 %> \example{FileContentsRestartDRAM}
138 %> \include{lineno} example/sampling/FileContentsRestartDRAM/main.m
139 %> \vis{FileContentsRestartDRAM}
140 %> <br><br>
141 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCor.ellipse.12.png width=700
142 %> <br><br>
143 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCov.ellipse.12.png width=700
144 %> <br><br>
145 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCor.ellipse3.12.png width=700
146 %> <br><br>
147 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCov.ellipse3.12.png width=700
148 %> <br><br>
149 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCovLogVol.line.png width=700
150 %> <br><br>
151 %> \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.meanAcceptanceRateSinceStart.line.png width=700
152 %>
153 %> \final{FileContentsRestartDRAM}
154 %>
155 %> \author
156 %> \JoshuaOsborne, May 21 2024, 3:31 AM, University of Texas at Arlington<br>
157 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
158 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
159 function self = FileContentsRestartDRAM(file, silent)
160
161 if nargin < 2
162 silent = [];
163 end
164
165 self = self@pm.sampling.FileContentsRestart(file, silent, "ParaDRAM");
166
167 %%%%
168 %%%% Find the update count in the file.
169 %%%%
170
171 self.count = count(self.contents, 'uniqueStateVisitCount');
172
173 %%%%
174 %%%% Parse the restart file contents.
175 %%%%
176
177 cholupp = zeros(self.ndim, self.ndim);
178 self.meanAcceptanceRateSinceStart = zeros(self.count, 1);
179 self.proposalAdaptiveScaleSq = zeros(self.count, 1);
180 self.proposalCovLogVol = zeros(self.count, 1);
181 self.proposalMean = zeros(self.ndim, self.count);
182 self.proposalCov = zeros(self.ndim, self.ndim, self.count);
183 self.proposalCor = zeros(self.ndim, self.ndim, self.count);
184 self.uniqueStateVisitCount = zeros(self.count, 1);
185 skip = 10 + self.ndim * (self.ndim + 3) / 2;
186 icount = 0;
187 istart = 1;
188
189 while istart < length(self.lineList) - skip
190
191 if ~strcmp(self.lineList{self.ilast + istart}, self.lineList{self.ilast + istart + 2})
192 icount = icount + 1;
193 if ~self.silent && mod(icount, 10) == 0
194 self.spinner.spin(icount / self.count);
195 end
196 self.meanAcceptanceRateSinceStart (icount) = str2double(self.lineList(self.ilast + istart + 1));
197 self.uniqueStateVisitCount (icount) = str2double(self.lineList(self.ilast + istart + 3));
198 self.proposalAdaptiveScaleSq (icount) = str2double(self.lineList(self.ilast + istart + 5));
199 self.proposalCovLogVol (icount) = str2double(self.lineList(self.ilast + istart + 7));
200 istart = istart + 9;
201 iend = istart + self.ndim;
202 self.proposalMean(1 : self.ndim, icount) = str2double(self.lineList(self.ilast + istart : self.ilast + iend - 1));
203 for idim = 1 : self.ndim % covmat
204 istart = iend + 1;
205 iend = iend + idim;
206 cholupp(1 : idim, idim) = str2double(self.lineList(self.ilast + istart : self.ilast + iend)); % This is the upper Cholesky.
207 end
208 self.proposalCov(:, :, icount) = cholupp' * cholupp;
209 istart = iend + 1;
210 else
211 istart = istart + 2;
212 end
213
214 end
215
216 %%%%
217 %%%% Ensure the intrinsic ``corrcov`` is installed.
218 %%%%
219
220 try
221
222 for icount = 1 : size(self.proposalCov, 3)
223 self.proposalCor(:, :, icount) = corrcov(squeeze(self.proposalCov(:, :, icount)));
224 end
225
226 catch me
227
228 self.proposalCor = self.proposalCov;
229 warning ( newline ...
230 + string(me.identifier) + " : " + string(me.message) + newline ...
231 + "The component ``proposalCor`` will be set to the same values as the component ``proposalCov``." + newline ...
232 + newline ...
233 );
234
235 end
236
237 if ~self.silent
238 self.spinner.spin(1);
239 self.checkpoint([]);
240 end
241
242 %%%%
243 %%%% Add the restart visualizations.
244 %%%%
245
246 try
247
248 self.vis = struct();
249 self.vis.cascade = struct();
250 silent_kws = {"silent", self.silent};
251
252 self.checkpoint("adding restart data visualization tools for proposal evolution...");
253
254 dims = self.ndim * (self.ndim - 1) / 2;
255 dimx = zeros(dims, 1);
256 dimy = zeros(dims, 1);
257 counter = 1;
258 for ix = 1 : self.ndim - 1
259 for iy = 2 : self.ndim
260 dimx(counter) = ix;
261 dimy(counter) = iy;
262 counter = counter + 1;
263 end
264 end
265
266 for field = ["proposalCor", "proposalCov"]
267 self.vis.(field) = struct();
268 self.vis.(field).cascade = struct();
269 self.vis.(field).cascade.ellipse = pm.vis.CascadeEllipse( @()self.(field) ...
270 , @()self.proposalMean ...
271 , [] ... color data
272 , "dimx", dimx, "dimy", dimy ...
273 , "names", self.domainAxisName ...
274 , silent_kws{:} ...
275 );
276 self.vis.(field).cascade.ellipse3 = pm.vis.CascadeEllipse3 ( @()self.(field) ...
277 , @()self.proposalMean ...
278 , @()transpose(self.uniqueStateVisitCount) ...
279 , [] ... color data
280 , "axes", {"zscale", "log"} ...
281 , "dimx", dimx, "dimy", dimy ...
282 , "names", self.domainAxisName ...
283 , "zlabel", {"txt", "Unique State Visit Count"} ...
284 , silent_kws{:} ...
285 );
286 end
287
288 self.checkpoint("adding restart data visualization tools for other proposal properties...");
289
290 colnames = [ "uniqueStateVisitCount" ...
291 , "meanAcceptanceRateSinceStart" ...
292 , "proposalAdaptiveScaleSq" ...
293 , "proposalCovLogVol" ...
294 ];
295 %fullnames = [ "Unique State Visit Count" ...
296 % , "Mean Acceptance Rate Since Start" ...
297 % , "Proposal Adaptive Scale-Squared" ...
298 % , "Proposal Covriance Log-Volume" ...
299 % ];
300 cdf = array2table( [ self.(colnames(1))(:) ...
301 , self.(colnames(2))(:) ...
302 , self.(colnames(3))(:) ...
303 , self.(colnames(4))(:) ...
304 ]);
305 cdf.Properties.VariableNames = colnames;
306 self.vis.cascade.line = pm.vis.CascadeLine ( cdf ...
307 , "colx", colnames(1) ...
308 , "coly", colnames(2 : end) ...
309 , "axes", {"xscale", "log"} ...
310 , "colormap", {"enabled", false} ...
311 ..., "xlabel", {"txt", fullnames(1)} ...
312 ..., "ylabel", {"txt", fullnames(2 : end)} ...
313 , "plot", {"linewidth", 3} ...
314 , silent_kws{:} ...
315 );
316
317 self.checkpoint([]);
318
319 catch me
320
321 warning ( newline ...
322 + "Failed to create the visualizations for the restart data." + newline ...
323 + "Here is the error message:" + newline ...
324 + newline ...
325 + string(me.identifier) + newline + string(me.message) + newline ...
326 + newline ...
327 );
328
329 end
330
331 end % constructor
332
333 end % methods(Access = public)
334
335 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
336
337 methods(Access = public, Hidden)
338
339 function warn(self)
340 if ~self.silent
341 warning ( newline ...
342 + "The structure of the file:" + newline ...
343 + newline ...
344 + pm.io.tab() + self.file + newline ...
345 + newline ...
346 + "does not match a DRAM-class restart file." + newline ...
347 + "The contents of the file may have been compromised." + newline ...
348 + "Verify the integrity of the file contents before attempting a reread." + newline ...
349 );
350 end
351 end
352
353 end % methods(Access = Hidden)
354
355 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
356
357end % classdef
FileContentsRestartDRAM
This is the base class for generating objects that contain the contents of a restart file generated b...
Definition: FileContentsRestartDRAM.m:31
FileContentsRestartDRAM::FileContentsRestartDRAM
function FileContentsRestartDRAM(in file, in silent)
Return a scalar object of class pm.sampling.FileContentsRestartDRAM.
FileContentsRestartDRAM::warn
function warn(in self)
FileContentsRestart
This is the base class for generating objects that contain the contents of a restart file generated b...
Definition: FileContentsRestart.m:27