rbasis/basisgen/+SnapshotsGenerator/Cached.m

classdef Cached < handle
% Interface for the storage and generation of detailed data that can be used to
% build reduced basis functions.
%
% Via the generate() method, detailed data for exactly one parameter can vector be
% generated and is returned. Usually, this data needs to be postprocessed
% afterwards. E.g. in case of reduced basis generation for evolution equations,
% a Cached instance could produce a detailed solution trajectory for
% the specified parameter and by applying a POD algorithm on this trajectory a
% single basis vector is extracted for basis extension.
%
% The generate method uses caching facilities to prevent data generation twice.
%
% Furthermore, the class provides methods to prepare and store solutions
% before-hand. This can be used in to compare reduced and detailed
% approximations for the entire training or validation set 'M'.

  properties(Dependent)
    % unique name created from the IDs as given to the constructor.
    idname;
  end

  properties(GetAccess = public, SetAccess = private)
    id;                          % string identifier for this generator

    enable_caching = true;       % boolean flag indicating whether caching is enabled.

    model_name     = 'default';  % name id of DetailedModel
  end

  properties
    % boolean value indicating whether the cached data shall be automatically
    % deleted if its inconsistent with the given 'dmodel'.
    force_delete = true;

    % seconds to wait before cached data is deleted automatically in case of
    % inconsistent models.
    countdown    = 5;
  end

  properties(Dependent)
    % checks whether the basis generator points to a valid directory
    is_valid;
  end

  properties(Access = private)

    % number of files read from cache (only needed for debugging)
    nocachereads = 0;

  end

  properties(Access = private, Dependent)
    % path to all the cached data for the model for which this generator is
    % constructed.
    modelpath;

    % path where the cached functions shall be stored.
    filepath;

    % full path to settingsfile where model data is stored for consistency
    % checks.
    settingsfile;

  end


  methods

    function modelpath = get.modelpath(this)
      modelpath    = fullfile(rbmatlabtemp, 'cache', this.model_name);
    end

    function filepath = get.filepath(this)
      filepath     = fullfile(this.modelpath, this.idname);
    end

    function settingsfile = get.settingsfile(this)
      settingsfile = fullfile(this.filepath, 'settings.mat');
    end

    function ok = get.is_valid(this)
      ok = exist(this.settingsfile, 'file');
    end

    function dg = Cached(dmodel, id, force_delete, enable_caching)
      % function dg = Cached(dmodel, id, force_delete)
      % constructor for the detailed generator
      %
      % Parameters:
      %   id:           an identifier string or a cell array of identifier
      %                 strings.
      %   force_delete: boolean value indicating whether the cached data shall
      %                 be automatically deleted if its inconsistent with the
      %                 given 'dmodel'. (Default = 'true')
      %   enable_caching: boolean value indicating whether the generated data
      %                   shall be stored in a cache. (Default = 'true')
      %
      dg.id = id;
      if nargin >= 3 && ~isempty(force_delete)
        dg.force_delete = force_delete;
      end
      if nargin >= 4 && ~isempty(enable_caching)
        dg.enable_caching = enable_caching;
      end
      dg.model_name = dmodel.name;
      if dg.enable_caching
        % When NEWDIR exists, MKDIR returns SUCCESS = 1, but with WARNING!
        if ~exist(fullfile(rbmatlabtemp, 'cache', dmodel.name, dg.idname), 'dir')
          success = mkdir(rbmatlabtemp, fullfile('cache', dmodel.name, dg.idname));
        else
          success = true;
        end

        if ~success
          error(['error in generating the caching savepath: ', dg.filepath]);
        end


        if exist(dg.settingsfile, 'file')
          tmp = load(dg.settingsfile);
          try
            assert_model_is_consistent(dg, dmodel, tmp.dmodel);
          catch exception
            if ~dmodel.debug && dg.force_delete
              disp(exception.message);
              disp('==================================================================');
              disp('========================== WARNING: ==============================');
              disp('dmodel.force_delete is set to true. The data in the savepath'       );
              disp(['will be deleted in ', num2str(dg.countdown), ' seconds. ']);
              disp('Press Ctrl-C if you want to keep the precompute files.');
              disp('==================================================================');
              for i=dg.countdown:-1:1
                disp(['Deleting in directory in ', num2str(i), ' seconds.']);
                pause(1);
              end
              clear_cachedirectory(dg);
            else
              error(exception.message);
            end
          end
        end

        save(dg.settingsfile, 'dmodel');
      end
    end

    function idname = get.idname(this)
      if iscell(this.id)
        idname = sprintf('%s_', this.id{:});
      else
        idname = this.id;
      end
    end

    function clear_cachedirectory(this)
      % clears the directory containing the cached mat-files

      delete(fullfile(this.filepath, '*.mat'));
      if exist(this.settingsfile, 'file')
        delete(this.settingsfile);
      end
    end

    function assert_model_is_consistent(this, dmodel, comparemodel)
      % function assert_model_is_consistent(this, dmodel, comparemodel)
      % throws an inconsistency error if the the current IDetailedModel object
      % and the one stored on the harddrive differ.
      %

      iseq = (dmodel == comparemodel);
      if ~iseq
        throw(MException('RBMatlab:Storage:InconsistentData', ...
               ['parameters of precomputed data and current',...
                ' simulation are inconsistent! Please delete files in path ', ...
                this.filepath, ' and restart!']));
      end

    end

    function [detailed_sample, tictoc, opt_fields] = generate(this, dmodel, detailed_data, fields)
      % function detailed_sample = generate(this, model, detailed_data[, fields])
      % generates a detailed data sample for a specific parameter using
      % caching facilities
      %
      % Internally this method calls the engine method generate_impl() if the
      % result cannot be read from the harddrive cache.
      %
      % Parameters:
      %   fields:  cell array of structure field names which shall also be
      %            stored in the cache in the 'opt_fields' structure. If not
      %            given only the 'detailed_sample' is generated.
      %
      % Return values:
      %   detailed_sample: This is usually a matrix with DOF vector columns
      %            holding the generated snapshots.
      %   tictoc:  time needed to compute the snapshots.
      %   opt_fields: optional fields to be cached.

      if nargin <= 3
        fields = [];
      end

      opt_fields = [];

      if this.enable_caching
        hash     = this.hashcode(dmodel);
        filename = fullfile(this.filepath, ['dsample', hash, '.mat']);

        if exist(filename, 'file')
          tmp             = load(filename);
          cache_hit = true;
          if ~isempty(fields)
            if ~isfield(tmp, 'opt_fields')
              cache_hit = false;
            else
              for i =1:length(fields)
                if ~isfield(tmp.opt_fields, fields{i})
                  cache_hit = false;
                  break;
                end
              end
              opt_fields = tmp.opt_fields;
            end
          end
          detailed_sample = tmp.detailed_sample;
          tictoc          = tmp.tictoc;

          if dmodel.debug
            this.nocachereads = this.nocachereads+1;
            if mod(this.nocachereads, 10) == 0
              disp(['This is the tenth cache read and we are in debug mode.', ...
                    'Comparing with real simulation...']);
              comp = generate_impl(this, dmodel, detailed_data);
              if any(size(comp) ~= size(detailed_sample))...
                  || any(comp ~= detailed_sample)
                disp('computations do not correspond with the cached result!!!');
                disp('Please check the hash function of whether the data directory')
                disp(['  ', this.filepath]);
                disp('needs to be deleted');
                keyboard;
              end
            end
          end

          if cache_hit
            return;
          else
            disp('cache file not found because opt_fields are missing...');
          end
        end
      end

      tstart                        = tic;
      [detailed_sample, opt_fields] = generate_impl(this, dmodel, detailed_data, fields);
      tictoc                        = toc(tstart);

      if this.enable_caching
        hash     = this.hashcode(dmodel);
        filename = fullfile(this.filepath, ['dsample', hash, '.mat']);

        save(filename, 'detailed_sample', 'tictoc', 'opt_fields');
      end

    end

    function prepare(this, dmodel, detailed_data, M)
      % function prepare_data(this, dmodel, detailed_data)
      % precompute detailed data for all parameters given by \a M.
      %
      % parameter:
      % M: matrix storing the parameters for which the generation shall be
      %    prepared.  The matrix size equal `dim(\cal M) \times M_p`, where `M_p`
      %    denotes the number of parameter vectors. (Default = [])

      num_cpus = 2*dmodel.num_cpus;

      tmp_fp   = this.filepath;
      npar     = size(M, 1);
      for mout = 0:floor((npar-1)/num_cpus)
        dsample_c = cell(1, npar);
        tictoc_c  = cell(1, npar);

        %parfor muind = (mout*num_cpus+1):min(npar, (mout+1)*num_cpus)
        for muind = (mout*num_cpus+1):min(npar, (mout+1)*num_cpus)
          tmp_M    = M;
          tmp_dmodel = dmodel;
          set_mu( tmp_dmodel, tmp_M(muind,:) );
          tmp_this = this;

          hash     = tmp_this.hashcode(tmp_dmodel);
          filename = fullfile(tmp_fp, ['dsample', hash, '.mat']);
          if ~exist(filename, 'file')
            disp(['Processing parameter vector ', num2str(muind),'/',num2str(npar),...
                  ' in Cached ', tmp_this.idname, '...']);
            tstart           = tic;
            dsample_c{muind} = generate_impl(this, tmp_dmodel, detailed_data);
            tictoc_c{muind}  = toc(tstart);
          else
            disp(['File exists: Skipping parameter vector ', num2str(muind),'/',num2str(npar),...
                  ' in Cached ', tmp_this.idname, '...']);
          end
        end
        for muind = (mout*num_cpus+1):min(npar, (mout+1)*num_cpus)
          detailed_sample = dsample_c{muind};
          tictoc          = tictoc_c{muind};

          set_mu( dmodel, M(muind,:) );
          hash     = this.hashcode(dmodel);
          filename = fullfile(tmp_fp, ['dsample', hash, '.mat']);
          if ~exist(filename, 'file')
            save(filename, 'detailed_sample', 'tictoc')
          end
        end
      end
    end % end of function prepare_data

    function dmodel = get_underlying_model(this)
      % function dmodel = get_underlying_model(this)
      % returns the detailed model stored on the harddrive with which the
      % snaphshots were generated.
      if exist(this.settingsfile, 'file')
        tmp = load(this.settingsfile);
        dmodel = tmp.dmodel;
      else
        dmodel = ['settingsfile for extension ', this.id, ' does not exist!'];
      end
    end


  end

  methods (Abstract, Access=protected)
    % generates a sample trajectory or detailed simulation item from which a
    % new basis function can be generated.
    %
    % Parameters:
    %   fields:  cell array of structure field names which shall also be
    %            stored in the cache in the 'opt_fields' structure. If not
    %            given only the 'U' is generated.
    %
    % Return values:
    %   U:       a matrix with DOF vector columns holding the generated
    %            snapshots.
    %   opt_fields: optional fields to be cached.
    [U, opt_fields] = generate_impl(this, dmodel, detailed_data, fields);

  end

  methods (Static, Access=protected)
    % function hashcode = hashcode(basis_generation)
    % this is a very simple hash code, generating an md5 hash out of the
    % current parameter vector.
    %
    % The default implementation of this function simply computes an MD5 hash
    % out of the parameter vector;
    function hashcode = hashcode(dmodel)

      mu       = get_mu(dmodel);
      hashcode = hash(mu, 'MD5');
    end

  end

end