FileContentsRestartDRAM.m

Go to the documentation of this file.

%>  \brief
%>  This is the base class for generating objects
%>  that contain the contents of a restart file
%>  generated by a ParaMonte sampler.<br>
%>
%>  \details
%>  This class is meant to be primarily internally
%>  used by the ParaMonte MATLAB library samplers.<br>
%>
%>  \warning
%>  The attributes of this class are considered
%>  internal implementation of the ParaMonte library.<br>
%>  As such, the interface of this class may change over time.<br>
%>
%>  \brief
%>  See the documentation of the class constructor.<br>
%>
%>  \note
%>  See below for information on the attributes (properties).<br>
%>
%>  \note
%>  See below for information on the methods.<br>
%>
%>  \final{FileContentsRestartDRAM}
%>
%>  \author
%>  \JoshuaOsborne, May 21 2024, 3:26 AM, University of Texas at Arlington<br>
%>  \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
%>  \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
classdef FileContentsRestartDRAM < pm.sampling.FileContentsRestart
 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    properties(Access = public)
        %>
        %>  ``meanAcceptanceRateSinceStart``
        %>
        %>  The real-valued MATLAB array of rank ``1`` of
        %>  shape ``(1:self.count)`` containing the set of
        %>  average MCMC acceptance rates of the sampler proposal
        %>  distribution over the course of the simulation.<br>
        %>
        meanAcceptanceRateSinceStart = [];
        %>
        %>  ``proposalAdaptiveScaleSq``
        %>
        %>  The real-valued MATLAB array of rank ``1`` of
        %>  shape ``(1:self.count)`` containing the set of
        %>  adaptive squared scale factors of the sampler proposal
        %>  distribution over the course of the simulation.<br>
        %>
        proposalAdaptiveScaleSq = [];
        %>
        %>  ``proposalCor``
        %>
        %>  The real-valued MATLAB array of rank ``3`` of
        %>  shape ``(self.ndim, self.ndim, self.count)`` containing
        %>  the set of correlation matrices of the proposal distribution
        %>  of the sampler, representing the evolution of the proposal
        %>  correlation matrix over the course of the simulation.<br>
        %>
        proposalCor = [];
        %>
        %>  ``proposalCov``
        %>
        %>  The real-valued MATLAB array of rank ``3`` of
        %>  shape ``(1:self.ndim, 1:self.ndim, 1:self.count)`` containing
        %>  the set of covariance matrices of the proposal distribution
        %>  of the sampler, representing the evolution of the proposal
        %>  covariance matrix over the course of the simulation.<br>
        %>
        proposalCov = [];
        %>
        %>  ``proposalCovLogVol``
        %>
        %>  The real-valued MATLAB array of rank ``1`` of
        %>  shape ``(1:self.count)`` containing the set of
        %>  ``log(determinant(covmat))`` of the proposal distribution
        %>  representing the evolution of mean of proposal distribution
        %>  over the course of the simulation.<br>
        %>
        proposalCovLogVol = [];
        %>
        %>  ``proposalMean``
        %>
        %>  The real-valued MATLAB array of rank ``2`` of
        %>  shape ``(1:self.ndim, 1:self.count)`` containing
        %>  the set of mean vectors of the proposal distribution
        %>  of the sampler, representing the evolution of the proposal
        %>  mean over the course of the simulation.<br>
        %>
        proposalMean = [];
        %>
        %>  ``uniqueStateVisitCount``
        %>
        %>  The scalar MATLAB integer containing the number of
        %>  states uniquely visited within the domain of the
        %>  objective function up to the stage specified
        %>  within the specified restart file.<br>
        %>
        uniqueStateVisitCount = [];
        %>
        %>  ``vis``
        %>
        %>  The scalar MATLAB ``struct`` containing the set of
        %>  predefined visualizations for the restart data.<br>
        %>
        vis = [];
    end
 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    methods(Access = public)
 
        %>  \brief
        %>  Return a scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
        %>
        %>  \details
        %>  This is the constructor of the class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
        %>
        %>  \param[in]  file    :   The input scalar MATLAB string containing the path to an external report file.<br>
        %>  \param[in]  silent  :   See the corresponding argument of [pm.sampling.FileContentsRestart](@ref FileContentsRestart) class.<br>
        %>                          (**optional**. The default is set by [pm.sampling.FileContentsRestart](@ref FileContentsRestart).)
        %>
        %>  \return
        %>  ``self``            :   The output scalar object of class [pm.sampling.FileContentsRestartDRAM](@ref FileContentsRestartDRAM).<br>
        %>
        %>  \interface{FileContentsRestartDRAM}
        %>  \code{.m}
        %>
        %>      contents = pm.sampling.FileContentsRestartDRAM(file)
        %>      contents = pm.sampling.FileContentsRestartDRAM(file, [])
        %>      contents = pm.sampling.FileContentsRestartDRAM(file, silent)
        %>      contents = pm.sampling.FileContentsRestartDRAM(file, [], [])
        %>      contents = pm.sampling.FileContentsRestartDRAM(file, silent, [])
        %>      contents = pm.sampling.FileContentsRestartDRAM(file, silent, method)
        %>
        %>  \endcode
        %>
        %>  \example{FileContentsRestartDRAM}
        %>  \include{lineno} example/sampling/FileContentsRestartDRAM/main.m
        %>  \vis{FileContentsRestartDRAM}
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCor.ellipse.12.png width=700
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCov.ellipse.12.png width=700
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCor.ellipse3.12.png width=700
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCov.ellipse3.12.png width=700
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.proposalCovLogVol.line.png width=700
        %>  <br><br>
        %>  \image html example/sampling/FileContentsRestartDRAM/FileContentsRestartDRAM.meanAcceptanceRateSinceStart.line.png width=700
        %>
        %>  \final{FileContentsRestartDRAM}
        %>
        %>  \author
        %>  \JoshuaOsborne, May 21 2024, 3:31 AM, University of Texas at Arlington<br>
        %>  \FatemehBagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.<br>
        %>  \AmirShahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin<br>
        function self = FileContentsRestartDRAM(file, silent)
 
            if  nargin < 2
                silent = [];
            end
 
            self = self@pm.sampling.FileContentsRestart(file, silent, "ParaDRAM");
 
            %%%%
            %%%% Find the update count in the file.
            %%%%
 
            self.count = count(self.contents, 'uniqueStateVisitCount');
 
            %%%%
            %%%% Parse the restart file contents.
            %%%%
 
            cholupp = zeros(self.ndim, self.ndim);
            self.meanAcceptanceRateSinceStart   = zeros(self.count, 1);
            self.proposalAdaptiveScaleSq        = zeros(self.count, 1);
            self.proposalCovLogVol              = zeros(self.count, 1);
            self.proposalMean                   = zeros(self.ndim, self.count);
            self.proposalCov                    = zeros(self.ndim, self.ndim, self.count);
            self.proposalCor                    = zeros(self.ndim, self.ndim, self.count);
            self.uniqueStateVisitCount          = zeros(self.count, 1);
            skip = 10 + self.ndim * (self.ndim + 3) / 2;
            icount = 0;
            istart = 1;
 
            while istart < length(self.lineList) - skip
 
                if ~strcmp(self.lineList{self.ilast + istart}, self.lineList{self.ilast + istart + 2})
                    icount = icount + 1;
                    if ~self.silent && mod(icount, 10) == 0
                        self.spinner.spin(icount / self.count);
                    end
                    self.meanAcceptanceRateSinceStart   (icount) = str2double(self.lineList(self.ilast + istart + 1));
                    self.uniqueStateVisitCount          (icount) = str2double(self.lineList(self.ilast + istart + 3));
                    self.proposalAdaptiveScaleSq        (icount) = str2double(self.lineList(self.ilast + istart + 5));
                    self.proposalCovLogVol              (icount) = str2double(self.lineList(self.ilast + istart + 7));
                    istart = istart + 9;
                    iend = istart + self.ndim;
                    self.proposalMean(1 : self.ndim, icount) = str2double(self.lineList(self.ilast + istart : self.ilast + iend - 1));
                    for idim = 1 : self.ndim % covmat
                        istart = iend + 1;
                        iend = iend + idim;
                        cholupp(1 : idim, idim) = str2double(self.lineList(self.ilast + istart : self.ilast + iend)); % This is the upper Cholesky.
                    end
                    self.proposalCov(:, :, icount) = cholupp' * cholupp;
                    istart = iend + 1;
                else
                    istart = istart + 2;
                end
 
            end
 
            %%%%
            %%%% Ensure the intrinsic ``corrcov`` is installed.
            %%%%
 
            try
 
                for icount = 1 : size(self.proposalCov, 3)
                    self.proposalCor(:, :, icount) = corrcov(squeeze(self.proposalCov(:, :, icount)));
                end
 
            catch me
 
                self.proposalCor = self.proposalCov;
                warning ( newline ...
                        + string(me.identifier) + " : " + string(me.message) + newline ...
                        + "The component ``proposalCor`` will be set to the same values as the component ``proposalCov``." + newline ...
                        + newline ...
                        );
 
            end
 
            if ~self.silent
                self.spinner.spin(1);
                self.checkpoint([]);
            end
 
            %%%%
            %%%% Add the restart visualizations.
            %%%%
 
            try
 
                self.vis = struct();
                self.vis.cascade = struct();
                silent_kws = {"silent", self.silent};
 
                self.checkpoint("adding restart data visualization tools for proposal evolution...");
 
                dims = self.ndim * (self.ndim - 1) / 2;
                dimx = zeros(dims, 1);
                dimy = zeros(dims, 1);
                counter = 1;
                for ix = 1 : self.ndim - 1
                    for iy = 2 : self.ndim
                        dimx(counter) = ix;
                        dimy(counter) = iy;
                        counter = counter + 1;
                    end
                end
 
                for field = ["proposalCor", "proposalCov"]
                    self.vis.(field) = struct();
                    self.vis.(field).cascade = struct();
                    self.vis.(field).cascade.ellipse = pm.vis.CascadeEllipse( @()self.(field) ...
                                                                            , @()self.proposalMean ...
                                                                            , [] ... color data
                                                                            , "dimx", dimx, "dimy", dimy ...
                                                                            , "names", self.domainAxisName ...
                                                                            , silent_kws{:} ...
                                                                            );
                    self.vis.(field).cascade.ellipse3 = pm.vis.CascadeEllipse3  ( @()self.(field) ...
                                                                                , @()self.proposalMean ...
                                                                                , @()transpose(self.uniqueStateVisitCount) ...
                                                                                , [] ... color data
                                                                                , "axes", {"zscale", "log"} ...
                                                                                , "dimx", dimx, "dimy", dimy ...
                                                                                , "names", self.domainAxisName ...
                                                                                , "zlabel", {"txt", "Unique State Visit Count"} ...
                                                                                , silent_kws{:} ...
                                                                                );
                end
 
                self.checkpoint("adding restart data visualization tools for other proposal properties...");
 
                colnames =  [ "uniqueStateVisitCount" ...
                            , "meanAcceptanceRateSinceStart" ...
                            , "proposalAdaptiveScaleSq" ...
                            , "proposalCovLogVol" ...
                            ];
                %fullnames = [ "Unique State Visit Count" ...
                %            , "Mean Acceptance Rate Since Start" ...
                %            , "Proposal Adaptive Scale-Squared" ...
                %            , "Proposal Covriance Log-Volume" ...
                %            ];
                cdf = array2table(  [ self.(colnames(1))(:) ...
                                    , self.(colnames(2))(:) ...
                                    , self.(colnames(3))(:) ...
                                    , self.(colnames(4))(:) ...
                                    ]);
                cdf.Properties.VariableNames = colnames;
                self.vis.cascade.line = pm.vis.CascadeLine  ( cdf ...
                                                            , "colx", colnames(1) ...
                                                            , "coly", colnames(2 : end) ...
                                                            , "axes", {"xscale", "log"} ...
                                                            , "colormap", {"enabled", false} ...
                                                            ..., "xlabel", {"txt", fullnames(1)} ...
                                                            ..., "ylabel", {"txt", fullnames(2 : end)} ...
                                                            , "plot", {"linewidth", 3} ...
                                                            , silent_kws{:} ...
                                                            );
 
                self.checkpoint([]);
 
            catch me
 
                warning ( newline ...
                        + "Failed to create the visualizations for the restart data." + newline ...
                        + "Here is the error message:" + newline ...
                        + newline ...
                        + string(me.identifier) + newline + string(me.message) + newline ...
                        + newline ...
                        );
 
            end
 
        end % constructor
 
    end % methods(Access = public)
 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    methods(Access = public, Hidden)
 
        function warn(self)
            if ~self.silent
                warning ( newline ...
                        + "The structure of the file:" + newline ...
                        + newline ...
                        + pm.io.tab + self.file + newline ...
                        + newline ...
                        + "does not match a DRAM-class restart file." + newline ...
                        + "The contents of the file may have been compromised." + newline ...
                        + "Verify the integrity of the file contents before attempting a reread." + newline ...
                        );
            end
        end
 
    end % methods(Access = Hidden)
 
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
end % classdef