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`` : The real-valued MATLAB array of rank ``1`` of
37 %> shape ``(1:self.count)`` containing the set of
38 %> average MCMC acceptance rates of the sampler proposal
39 %> distribution over the course of the simulation.<br>
40 %>
41 meanAcceptanceRateSinceStart = [];
42 %
43 % ``proposalAdaptiveScaleSq`` : The real-valued MATLAB array of rank ``1`` of
44 % shape ``(1:self.count)`` containing the set of
45 % adaptive squared scale factors of the sampler proposal
46 % distribution over the course of the simulation.<br>
47 %
48 proposalAdaptiveScaleSq = [];
49 %
50 % ``proposalCor`` : The real-valued MATLAB array of rank ``3`` of
51 % shape ``(self.ndim, self.ndim, self.count)`` containing
52 % the set of correlation matrices of the proposal distribution
53 % of the sampler, representing the evolution of the proposal
54 % correlation matrix over the course of the simulation.<br>
55 %
56 proposalCor = [];
57 %
58 % ``proposalCov`` : The real-valued MATLAB array of rank ``3`` of
59 % shape ``(1:self.ndim, 1:self.ndim, 1:self.count)`` containing
60 % the set of covariance matrices of the proposal distribution
61 % of the sampler, representing the evolution of the proposal
62 % covariance matrix over the course of the simulation.<br>
63 %
64 proposalCov = [];
65 %
66 % ``proposalLogVolume`` : The real-valued MATLAB array of rank ``1`` of
67 % shape ``(1:self.count)`` containing the set of
68 % ``log(determinant(covmat))`` of the proposal distribution
69 % representing the evolution of mean of proposal distribution
70 % over the course of the simulation.<br>
71 %
72 proposalLogVolume = [];
73 %
74 % ``proposalMean`` : The real-valued MATLAB array of rank ``2`` of
75 % shape ``(1:self.ndim, 1:self.count)`` containing
76 % the set of mean vectors of the proposal distribution
77 % of the sampler, representing the evolution of the proposal
78 % mean over the course of the simulation.<br>
79 %
80 proposalMean = [];
81 %
82 % ``uniqueStateVisitCount`` : The scalar MATLAB integer containing the number of
83 % states uniquely visited within the domain of the
84 % objective function up to the stage specified
85 % within the specified restart file.<br>
86 %
87 uniqueStateVisitCount = [];
88 end
89
90 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
91
92 methods(Access = public)
93
94 %> \brief
95 %> Return a scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
96 %>
97 %> \details
98 %> This is the constructor of the class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
99 %>
100 %> \param[in] file : The input scalar MATLAB string containing the path to an external report file.<br>
101 %> \param[in] silent : See the corresponding argument of [pm.sampling.FileContentsRestart](@ref FileContentsRestart) class.<br>
102 %> (**optional**. The default is set by [pm.sampling.FileContentsRestart](@ref FileContentsRestart).)
103 %>
104 %> \return
105 %> ``self`` : The output scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
106 %>
107 %> \interface{FileContentsRestartDRAM}
108 %> \code{.m}
109 %>
110 %> contents = pm.sampling.FileContentsRestartDRAM(file)
111 %> contents = pm.sampling.FileContentsRestartDRAM(file, [])
112 %> contents = pm.sampling.FileContentsRestartDRAM(file, silent)
113 %> contents = pm.sampling.FileContentsRestartDRAM(file, [], [])
114 %> contents = pm.sampling.FileContentsRestartDRAM(file, silent, [])
115 %> contents = pm.sampling.FileContentsRestartDRAM(file, silent, method)
116 %>
117 %> \endcode
118 %>
119 %> \final{FileContentsRestartDRAM}
120 %>
121 %> \author
122 %> \JoshuaOsborne, May 21 2024, 3:31 AM, University of Texas at Arlington<br>
123 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
124 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
125 function self = FileContentsRestartDRAM(file, silent)
126 if nargin < 2
127 silent = [];
128 end
129 self = self@pm.sampling.FileContentsRestart(file, silent, "ParaDRAM");
130
131 %%%%
132 %%%% find the update count in the file.
133 %%%%
134
135 self.count = count(self.contents, 'uniqueStateVisitCount');
136
137 %%%%
138 %%%% Parse the restart file contents.
139 %%%%
140
141 cholupp = zeros(self.ndim, self.ndim);
142 self.meanAcceptanceRateSinceStart = zeros(self.count, 1);
143 self.proposalAdaptiveScaleSq = zeros(self.count, 1);
144 self.proposalLogVolume = zeros(self.count, 1);
145 self.proposalMean = zeros(self.ndim, self.count);
146 self.proposalCov = zeros(self.ndim, self.ndim, self.count);
147 self.proposalCor = zeros(self.ndim, self.ndim, self.count);
148 self.uniqueStateVisitCount = zeros(self.count, 1);
149 skip = 10 + self.ndim * (self.ndim + 3) / 2;
150 icount = 0;
151 istart = 1;
152
153 while istart < length(self.lineList) - skip
154
155 if ~strcmp(self.lineList{self.ilast + istart}, self.lineList{self.ilast + istart + 2})
156 icount = icount + 1;
157 if ~self.silent && mod(icount, 10) == 0
158 self.spinner.spin(icount / self.count);
159 end
160 self.meanAcceptanceRateSinceStart (icount) = str2double(self.lineList(self.ilast + istart + 1));
161 self.uniqueStateVisitCount (icount) = str2double(self.lineList(self.ilast + istart + 3));
162 self.proposalAdaptiveScaleSq (icount) = str2double(self.lineList(self.ilast + istart + 5));
163 self.proposalLogVolume (icount) = str2double(self.lineList(self.ilast + istart + 7));
164 istart = istart + 9;
165 iend = istart + self.ndim;
166 self.proposalMean(1 : self.ndim, icount) = str2double(self.lineList(self.ilast + istart : self.ilast + iend - 1));
167 for idim = 1 : self.ndim % covmat
168 istart = iend + 1;
169 iend = iend + idim;
170 cholupp(1 : idim, idim) = str2double(self.lineList(self.ilast + istart : self.ilast + iend)); % This is the upper Cholesky.
171 end
172 self.proposalCov(:, :, icount) = cholupp' * cholupp;
173 istart = iend + 1;
174 else
175 istart = istart + 2;
176 end
177
178 end
179
180 %%%%
181 %%%% Ensure the instrinc ``corrcov`` is installed.
182 %%%%
183
184 try
185
186 for icount = 1 : size(self.proposalCov, 3)
187 self.proposalCor(:, :, icount) = corrcov(squeeze(self.proposalCov(:, :, icount)));
188 end
189
190 catch me
191
192 self.proposalCor = self.proposalCov;
193 warning ( newline ...
194 + string(me.identifier) + " : " + string(me.message) + newline ...
195 + "The component ``proposalCor`` will be set to the same values as the component ``proposalCov``." + newline ...
196 + newline ...
197 );
198
199 end
200
201 if ~self.silent
202 self.spinner.spin(1);
203 self.checkpoint([]);
204 end
205
206 end % constructor
207
208 end % methods(Access = public)
209
210 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
211
212 methods(Access = public, Hidden)
213
214 function warn(self)
215 if ~self.silent
216 warning ( newline ...
217 + "The structure of the file:" + newline ...
218 + newline ...
219 + pm.io.tab + self.file + newline ...
220 + newline ...
221 + "does not match a DRAM-class restart file." + newline ...
222 + "The contents of the file may have been compromised." + newline ...
223 + "Verify the integrity of the file contents before attempting a reread." + newline ...
224 );
225 end
226 end
227
228 end % methods(Access = Hidden)
229
230 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
231
232end % 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
find
function find(in vendor)
Return a list of scalar MATLAB strings containing the paths to all detected mpiexec binaries installe...
tab
function tab()
Return a scalar MATLAB string containing 4 blank characters equivalent to a tab character.