ParaMonte MATLAB 3.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
FileContentsRestart.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%> See the documentation of the class constructor.<br>
10%>
11%> \note
12%> See below for information on the attributes (properties).<br>
13%>
14%> \note
15%> See below for information on the methods.<br>
16%>
17%> \return
18%> An object of class [pm.sampling.FileContentsRestart](@ref FileContentsRestart).<br>
19%>
20%> \final{FileContentsRestart}
21%>
22%> \author
23%> \JoshuaOsborne, May 21 2024, 3:19 AM, University of Texas at Arlington<br>
24%> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
25%> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
26classdef FileContentsRestart < pm.io.FileContents
27
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
29
30 properties(Access = public)
31 %>
32 %> ``count``
33 %>
34 %> The scalar MATLAB integer containing the number of
35 %> restart entries in the specified restart file.<br>
36 %>
37 count = [];
38 %>
39 %> ``ndim``
40 %>
41 %> The scalar MATLAB integer containing the number of
42 %> dimensions of the domain of the objective function.<br>
43 %>
44 ndim = [];
45 %>
46 %> ``domainAxisName``
47 %>
48 %> The vector of MATLAB strings of size ``ndim`` containing
49 %> the domain axes names of the density function explored.<br>
50 %>
51 domainAxisName = [];
52 %>
53 %> ``contents``
54 %>
55 %> The scalar MATLAB string containing the entire
56 %> contents of the restart file with all Carriage Return
57 %> characters removed (relevant only to Windows OS).<br>
58 %>
59 contents = [];
60 end
61
62 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
63
64 properties(Hidden)
65 %>
66 %> ``method``
67 %>
68 %> The ``Hidden`` scalar MATLAB string component
69 %> containing the sampling method name.<br>
70 %>
71 %> \warning
72 %> This is an internal class attribute that
73 %> is inaccessible to the end users.<br>
74 %>
75 method = '';
76 %>
77 %> ``lineList``
78 %>
79 %> The ``Hidden`` scalar MATLAB string array
80 %> containing the list of all restart file lines.<br>
81 %>
82 %> \warning
83 %> This is an internal class attribute that
84 %> is inaccessible to the end users.<br>
85 %>
86 lineList = [];
87 %>
88 %> ``lineListLen``
89 %>
90 %> The ``Hidden`` scalar MATLAB whole-number containing
91 %> the length of the class component ``lineList``.<br>
92 %>
93 %> \warning
94 %> This is an internal class attribute that
95 %> is inaccessible to the end users.<br>
96 %>
97 lineListLen = [];
98 %>
99 %> ``ilast``
100 %>
101 %> The ``Hidden`` scalar MATLAB whole-number component
102 %> containing the number of the lines parsed up a given
103 %> point in the internals of the class methods.<br>
104 %>
105 %> \warning
106 %> This is an internal class attribute that
107 %> is inaccessible to the end users.<br>
108 %>
109 ilast = 0; % index that is always set to the last line number read.
110 end
111
112 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
113
114 methods(Access = public)
115
116 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
117
118 %> \brief
119 %> Return a scalar object of class [pm.sampling.FileContentsRestart](@ref FileContentsRestart).<br>
120 %>
121 %> \details
122 %> This is the constructor of the class [pm.sampling.FileContentsRestart](@ref FileContentsRestart).<br>
123 %>
124 %> \param[in] file : The input scalar MATLAB string containing the path to an external restart file.<br>
125 %> \param[in] silent : See the corresponding argument of [pm.io.FileContents](@ref FileContents) class.<br>
126 %> (**optional**. The default is set by [pm.io.FileContents](@ref FileContents).)
127 %> \param[in] method : The input scalar MATLAB string containing the sampling method name.<br>
128 %> The input value must be any of the following:<br>
129 %> <ol>
130 %> <li> ``"ParaDRAM"``
131 %> <li> ``"ParaDISE"``
132 %> <li> ``"ParaNest"``
133 %> </ol>
134 %> (**optional**. If missing, some of the restart file contents will not be (properly) parsed.)
135 %>
136 %> \return
137 %> ``self`` : The output scalar object of class [pm.sampling.FileContentsRestart](@ref FileContentsRestart).
138 %>
139 %> \interface{FileContentsRestart}
140 %> \code{.m}
141 %>
142 %> contents = pm.sampling.FileContentsRestart(file)
143 %> contents = pm.sampling.FileContentsRestart(file, [])
144 %> contents = pm.sampling.FileContentsRestart(file, silent)
145 %> contents = pm.sampling.FileContentsRestart(file, [], [])
146 %> contents = pm.sampling.FileContentsRestart(file, silent, [])
147 %> contents = pm.sampling.FileContentsRestart(file, silent, method)
148 %>
149 %> \endcode
150 %>
151 %> \final{FileContentsRestart}
152 %>
153 %> \author
154 %> \JoshuaOsborne, May 21 2024, 3:25 AM, University of Texas at Arlington<br>
155 %> \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
156 %> \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
157 function self = FileContentsRestart(file, silent, method)
158 if nargin < 2
159 silent = [];
160 end
161 self = self@pm.io.FileContents(file, silent);
162 if 2 < nargin
163 self.method = convertStringsToChars(method);
164 end
165
166 %%%%
167 %%%% remove any CARRIAGE RETURN.
168 %%%%
169
170 self.contents = strrep(fileread(file), char(13), '');
171 self.lineList = strsplit(self.contents, newline);
172 self.lineListLen = length(self.lineList);
173
174 % find the field names in the file.
175 %fields = [];
176 %for ilast = 1 : self.lineListLen
177 % line = self.lineList{ilast};
178 % if isletter(line(1))
179 % if ~any(contains(fields, line))
180 % fields = [fields, line];
181 % else
182 % break;
183 % end
184 % end
185 %end
186
187 %%%%
188 %%%% Read restart meta data (ndim, domainAxisName).
189 %%%%
190
191 %%%% This is the old DRAM-specific approach where we inferred the ndim value from the file contents.
192
193 % self.ndim = 0;
194 % rowOffset = 1;
195 % while ~contains(self.lineList(rowOffset), "proposalMean")
196 % rowOffset = rowOffset + 1;
197 % if self.lineListLen < rowOffset
198 % error ( newline ...
199 % + "Failed to detect any field named ""proposalMean""" + newline ...
200 % + "in the specified restart file:" + newline ...
201 % + newline ...
202 % + pm.io.tab + file + newline ...
203 % + newline ...
204 % + "The file structure may have been compromized." + newline ...
205 % + newline ...
206 % );
207 % end
208 % end
209 % rowOffset = rowOffset + 1; % the first numeric value of proposalMean.
210 % while ~isnan(str2double(self.lineList{self.ndim + rowOffset}))
211 % self.ndim = self.ndim + 1;
212 % end
213 % if self.ndim == 0
214 % error ( newline ...
215 % + "Failed to infer the value of ``ndim``." + newline ...
216 % + "from the specified restart file:" + newline ...
217 % + newline ...
218 % + pm.io.tab + file + newline ...
219 % + newline ...
220 % + "The file structure may have been compromized." + newline ...
221 % + newline ...
222 % );
223 % end
224
225 %%%% This is the new approach where the ndim value is explicitly written in the file along with domainAxisName.
226
227 if ~contains(self.lineList(1), "ndim") || ~contains(self.lineList(3), "domainAxisName")
228 error ( newline ...
229 + "The structure of the specified restart file appears to have been compromised:" + newline ...
230 + newline ...
231 + pm.io.tab + file + newline ...
232 + newline ...
233 + "The first line of the restart file must match ""ndim""." + newline ...
234 + "The third line of the restart file must match ""domainAxisName""." + newline ...
235 + newline ...
236 );
237 else
238 self.ndim = str2double(self.lineList(2));
239 self.domainAxisName = strings(self.ndim, 1);
240 for idim = 1 : self.ndim
241 self.domainAxisName(idim) = string(self.lineList(3 + idim));
242 end
243 end
244
245 self.ilast = 3 + self.ndim;
246
247 end % constructor
248
249 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
250
251 end % methods(Access = public)
252
253 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
254
255end % classdef
name
function name(in vendor)
Return the MPI library name as used in naming the ParaMonte MATLAB shared library directories.
list
function list()
Return a list of MATLAB strings containing the names of OS platforms supported by the ParaMonte MATLA...
index
function index(in array)
Given array(1 : n), return the array index indx(1 : n) such that array(indx) is in ascending order.
FileContentsRestart
This is the base class for generating objects that contain the contents of a restart file generated b...
Definition: FileContentsRestart.m:27
FileContentsRestart::FileContentsRestart
function FileContentsRestart(in file, in silent, in method)
Return a scalar object of class pm.sampling.FileContentsRestart.
FileContents
This is the base class for generating objects that contain the contents of a given file.
Definition: FileContents.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.