INode.m

classdef INode < DataTree.INode & Greedy.DataTree.Info
  % %Interface class for general data tree nodes storing detailed data returned
  % by Greedy.Interface.gen_detailed_data()
  %
  % Usually every Greedy.Interface instance creates a new node in the detailed
  % data tree with new reduced basis functions or a logging information about
  % the steps taken by the Greedy.Interface node.


  properties

    % storage of history entries (c.f. snapshot() and format_snapshot() )
    history;

  end

  properties (Access = private)

    history_ids = struct('id', {}, 'id_descr', {}, 'map', []);

  end

  methods

    function set_rb(this, RB)
      % function set_rb(this, RB)
      % sets the reduced basis space
      %
      % @todo is this correct or should it be in a specialization?
      this.RB = RB;
    end

    function RB = get_rb(this)
      % function set_rb(this, RB)
      % returns the reduced basis space
      %
      % @todo is this correct or should it be in a specialization?
      RB = this.RB;
    end


%    function data = get_by_description(this, id, dmodel)
%      % function data = get_by_description(this, id, model)
%      % returns a leaf in the DataTree for a specific ID, parameter and time instant.
%      %
%      % Parameters:
%      %   dmodel: of type Greedy.User.IDetailedModel
%      %   id: a string specifying an optional ID restriction. (default = empty)
%      %
%      % Return values:
%      %   data: leaf element of type Greedy.DataTree.Detailed.ILeafNode.
%      %
%      % See also: DataTree.INode.get_by_description()

%      if nargin == 2
%        mu = [];
%        nt = [];
%      else
%        mu = get_mu(dmodel);
%        nt = dmodel.descr.nt;
%      end
%      data = get_by_description@DataTree.INode(this, id, mu, nt);
%    end

    function snapshot(this, id, id_text, snapshot_description)
      % function snapshot(this, id, id_text, snapshot_description)
      % creates a copy of the Greedy.Info element of the subtree rooted by this
      % node and stores it in a history.
      %
      % The history is organized by short ID strings to whom a longer
      % description text should be attached. Furthermore every history entry
      % can be decribed by a Matlab struct. A Date tag is added automatically.
      %
      % A use-case for this feature is the Greedy.TrainingSetAdaptation class
      % which refines the training parameter space several times. At all these
      % time instants it creates a new history entry.
      %
      % Parameters:
      %   id:       the id string under which the history entry shall be stored.
      %   id_text:  a descriptive text for the id. This is only used at the
      %             first time a history entry for the 'id' is created.
      %   snapshot_description: a description of the history entry with
      %              arbitrary content.
      [dummy, index] = intersect({this.history_ids.id}, id);
      hist_index = length(this.history) + 1;
      if isempty(index)
        index = length(this.history_ids) + 1;
        this.history_ids(index).id  = id;
        this.history_ids(index).map = hist_index;
      else
        this.history_ids(index).map = [this.history_ids(index).map, hist_index];
      end

      if ~isempty(id_text)
        this.history_ids(index).id_descr = id_text;
      end

      dates = datestr(clock, 'dd.mm.yyyy HH:MM');

      if ~isempty(this.fields) || ~isempty(this.stop_flags)
        this.history{hist_index}.description = snapshot_description;
        this.history{hist_index}.date        = dates;
        if ~isempty(this.fields)
          this.history{hist_index}.fields = this.fields;
        end
        if ~isempty(this.stop_flags)
          this.history{hist_index}.stop_flags = this.stop_flags;
        end
      end

      snapshot_children(this, id, id_text, snapshot_description);
    end

    function sl = get_snapshot_length(this, id)
      % function sl = get_snapshot_length(this, id)
      % returns the number of history entries stored for a specific id.
      %
      % Parameters:
      %   id:  history ID
      %
      % Return values:
      %   sl: number of history entries
      [dummy, index] = intersect(this.history_ids.id, id);
      if isempty(index)
        sl = 0;
      else
        sl = length(this.history_ids.id{index});
      end
    end

    function fs = format_snapshot(this, id, indices)
      % function fs = format_snapshot(this, id, indices)
      % retuns a formatted structure of a history item for several indices
      %
      % @todo: rewrite
      [dummy, index] = intersect({this.history_ids.id}, id);
      if isempty(index)
        fs = '';
        return;
      end
      if nargin == 2 || isempty(indices)
        indices = 1:length(this.history_ids(index).map);
      end

      fs.id       = id;
      fs.descr    = this.history_ids(index).id_descr;
      fs.history  = this.history{this.history_ids(index).map(indices)};

      children = gather_children_format_snapshot(this, id, indices);
      if ~isempty(children)
        fs.children = children;
      end
    end

  end

  methods(Access = protected)

    function snapshot_children(this, id, id_text, snapshot_description)
      % function snapshot_children(this, id, id_text, snapshot_description)
      % forward the snapshot generation to the children
      for i = 1:length(this)
        snapshot_children(get(this, i), id, id_text, snapshot_description);
      end
    end

    function children = gather_children_format_snapshot(this, id, indices)
      % function children = gather_children_format_snapshot(this, id, indices)
      % helper function called by format_snapshot()
      children = cell(1, length(this));
      for i = 1:length(this)
        children{i} = gather_children_format_snapshot(get(this, i), id, indices);
      end
    end
  end

  methods (Abstract)

    % function siz = get_rb_size(this);
    % returns the size of the reduced basis stored in this tree.
    %
    % Return values:
    %   siz: dimension of stored reduced basis space `{\cal W}_{\text{red}}`
    siz = get_rb_size(this);

    % function siz = get_ei_size(this);
    % returns the size of the collateral reduced basis stored in this tree.
    %
    % Return values:
    %   siz: a tree of nodes which are objects of type DataTree.IdMapNode
    %        of stored collateral reduced basis spaces `{\cal W}^{{\cal
    %        L}_h}_{\text{red}}` for operators `{\cal L}_h`
    siz = get_ei_size(this);

    % function [ot1, ot2, ot3] = offtime(this, rmodel)
    % returns up to three different offline time measurements
    [ot1, ot2, ot3] = offtime(this, rmodel);
  end

end