INode.m

classdef INode < handle
  % Interface for a node in a DataTree.
  %
  % A DataTree consists of nodes with an arbitrary number of children or
  % DataTree.ILeafNode's which store data. In the abstract version of a DataTree,
  % non-leaf nodes can be one of: 
  % - DataTree.IdMapNode,
  % - DataTree.TpartNode or
  % - DataTree.PpartNode.
  % and leaf elements are always of type DataTree.ILeafNode.
  %
  % Each of these nodes specify information about the data stored in the leaf
  % nodes.
  %
  % Considering e.g. the tree configuration
  % @dot
  % digraph example {
  %    node [shape=record, fontname=Helvetica, fontsize=10];
  %    nIdMapNode [label="{DataTree.IdMapNode|{implicit|explicit}}"URL="\ref DataTree.IdMapNode"];
  %    nTpartNode [label="{DataTree.TpartNode|{[0:10]|[11:30]|[31:50]}}"URL="\ref DataTree.TpartNode"];
  %    l1 [label="Leaf"];
  %    l2 [label="Leaf"];
  %    l3 [label="Leaf",color=red];
  %    l4 [label="Leaf"];
  %    nIdMapNode -> nTpartNode [label = "1"];
  %    nIdMapNode -> l1 [label = "2"];
  %    nTpartNode -> l2 [label = "[1,1]"];
  %    nTpartNode -> l3 [label = "[1,2]"];
  %    nTpartNode -> l4 [label = "[1,3]"];
  % }
  % @enddot
  % the red leaf element is tagged with the id "implicit" and valid inside the
  % time slice interval `[11,30]`. Children are numbered consecutively and can
  % be received by using a concatenation of indices. The read leaf element
  % could for example be reached via
  % @code
  %   red_leaf = get(idmap_root, [1,2]);
  % @endcode
  %
  % where the index vector is obtainable via a call to the get_index() method
  % @code
  %   index = get_index(idmap_root, "implicit", [], 23);
  % @endcode
  %
  % There exist generic specializations for DataTrees representing detailed
  % data (Greedy.DataTree.Detailed.INode, Greedy.DataTree.Detailed.ILeafNode) and reduced data
  % (Greedy.User.RbReducedDataDefault) which have no extra functionality for non-leaf node
  % elements.

  methods(Abstract)

    % function data     = get(this, index);
    % Access to a child of the current node
    %
    % Access a children node by an index which is usually retrieved by a call
    % to get_index()
    %
    % Parameters:
    %  index: vector describing the father-child relation
    %
    % Return values:
    %  data: the children node of type INode
    data     = get(this, index);

    % function index    = get_index(this, id, mu, nt);
    % Obtains the leaf index vector that best fits the child description given
    % by the three arguments.
    %
    % @todo add get_indices method returning indices in a range
    %
    % The leaf child description consists of an
    %  - id string,
    %  - a parameter vector and
    %  - a time step number.
    %
    % Parameters:
    %  id: a string id filtered through an DataTree.IdMapNode in the tree hierarchy.
    %  mu: a parameter vector filtered through a DataTree.PpartNode instance in the
    %      tree hierarchy.
    %  nt: an integer corresponding to a time step index filtered through a
    %      DataTree.TpartNode instance in the tree hierarchy.
    %
    % Return values:
    %  index: the most-specific (longest possible) index vector leading to a
    %         DataTree.ILeafNode element matching the child description.
    index    = get_index(this, id, mu, nt);

    % function tree     = create_tree(this, creator, ids, mu_cube, tslice, basepath);
    % Creates a new tree from a subtree specified by ids, parameter and time index
    % regions
    %
    % The method creates a new DataTree for all nodes tagged by an id in
    % \a ids, lying in the time slice given by \a tslice and inside the
    % parameter space region given by \a mu_rect. At each of these nodes a
    % method from a \a creator is called to build the tree.
    %
    % Parameters:
    %  creator: an object of type DataTree.ICreator creating the new tree.
    %  ids: a cell array of ids which shall be filtered. An empty cell array
    %       means that all ids are accepted. (default = [])
    %  mu_cube: a '1x2'-cell array of vectors '{ lower_left, upper_right }'
    %           specifying the lower left and the upper right corner of a cube
    %           in the parameter space for filtering parameter vectors. An
    %           empty array disables the filtering (default = []).
    %  tslice:  a 2D vector specifying an interval of time step indices for
    %           time slicing. An empty vector disables the filtering (default =
    %           [])
    %  basepath: a vector specifying the relation of the current node to the
    %            parent node at which the merge began.
    %
    % Return values:
    %  tree: the newly created tree of type DataTree.INode
    tree     = create_tree(this, creator, ids, mu_cube, tslice, basepath);

    % function children = length(this);
    % Returns the number of children of the node
    %
    % For leaf elements this method should return 0.
    %
    % Return values:
    %  children: the number of childres of the current node
    children = length(this);

    % function this     = set(this, index, value);
    % Sets a child at the given path in the tree hierarchy.
    %
    % Usually this method is used to set a leaf data node with attached data.
    %
    % Parameters:
    %  index: the path index where the node shall be injected
    %  value: the node that shall be attached as a child
    %
    % Return values:
    %  this: the modified DataTree node.
    this     = set(this, index, value);

  end

  methods

    function leaf_func(this, funcptr, ids, mu_cube, tslice)
      % applies a function to all leafs of a DataTree
      %
      % Parameters:
      %   funcptr: function handle of the function to be applied to all leaf elements.
      %   ids:     ID filter. See create_tree() for details.
      %   mu_cube: parameter filter. See create_tree() for details.
      %   tslice:  time filter. See create_tree() for details.

      if nargin < 3
        ids = [];
      end
      if nargin < 4
        mu_cube = [];
      end
      if nargin < 5
        tslice = [];
      end
      if nargin < 6
        basepath = [];
      end

      create_tree(this, DataTree.NullCreator(funcptr), ids, mu_cube, tslice, basepath);

    end

    function tree = create_scalar_tree(this, funcptr, ids, mu_cube, tslice)
      % function tree = create_scalar_tree(this, funcptr, ids, mu_cube, tslice)
      % copies the current trees with different leafs. These leafs are computes
      % by a function returning scalar values.
      %
      % For example, one can extract a field available in all leafs with this
      % function, like the reduced basis size 'N' in a reduced data structure.
      %
      % Parameters:
      %   funcptr: function handle of the function to be applied to all leaf elements.
      %   ids:     ID filter. See create_tree() for details.
      %   mu_cube: parameter filter. See create_tree() for details.
      %   tslice:  time filter. See create_tree() for details.

      if nargin < 3
        ids = [];
      end
      if nargin < 4
        mu_cube = [];
      end
      if nargin < 5
        tslice = [];
      end
      basepath = [];

      tree = create_tree(this, DataTree.ScalarCreator(funcptr), ids, mu_cube, tslice, basepath);
    end

    function start_index = traverse_start(this)
      % function start_index = traverse_start(this)
      % Start iterator for a full traverse of the DataTree.
      %
      % Use this method to get a start index for a tree traversal.
      % Subsequently, indices can be obtained by calls to traverse_next().
      % Every node is touched during a traversal, until an empty index is
      % returned.
      %
      % Return values:
      %  start_index: the start index vector for tree traversal.
      if length(this) > 0
        start_index = [1, traverse_start(get(this, 1))];
      else
        start_index = [];
      end
    end

    function next_index = traverse_next(this, this_index)
      % function next_index = traverse_next(this, this_index)
      % iterator for a full traverse of the DataTree.
      %
      % Use this method to get the next index for a tree traversal.
      % Every node is touched during a traversal, until an empty index is
      % returned.
      %
      % Parameters:
      %  this_index: previous index.
      %
      % Return values:
      %  next_index: the next index vector for tree traversal. Empty vector
      %              after the last node.
      if length(this_index) > 1
        next_index = [this_index(1), traverse_next(get(this, this_index(2)), this_index(2:end))];
        if length(next_index) > 1
          return;
        else
          this_index = next_index;
        end
      end
      next_index = [this_index, traverse_start(get(this, 1))];
      if length(next_index) > 1
        return;
      end
      if this_index < length(this)
        next_index = this_index + 1;
      else
        next_index = [];
      end
    end

%    function first = first_leaf_index(this, ids, mu_cube, tslice)
%      % function first = first_leaf_index(this)
%      % returns the first (left-most) index for an iteration of the leafs of the data tree.
%      %
%      % For a full leaf iteration use next_leaf_index().
%      %
%      % Return values:
%      %   first: index of the first leaf element


%      if nargin < 2
%        ids = [];
%      end
%      if nargin < 3
%        mu_cube = [];
%      end
%      if nargin < 4
%        tslice = [];
%      end

%      if ~isa(this, 'INode') || isa(this, 'DataTree.ILeafNode')
%        first = [];
%      else
%        nextchild_index = get_first_index_match(this, ids, mu_cube, tslice);
%        if nextchild_index == -1
%          first = -1;
%          return;
%        end
%        nextchild = get(this, nextchild_index);
%        if ~isa(nextchild, 'INode') || isa(nextchild, 'DataTree.ILeafNode')
%          first = nextchild_index;
%        else
%          next_part = first_leaf_index(nextchild, ids, mu_cube, tslice);
%          first = [nextchild_index, next_part];
%          if next_part == -1
%            first = 1;
%          end
%        end
%      end
%    end

%    function next = next_leaf_index(this, current, ids, mu_cube, tslice)
%      % function next = next_leaf_index(this, current, ids, mu_cube, time_slice)
%      % returns indices for a leaf element iteration
%      %
%      % Get the first index with first_leaf_index()
%      %
%      % Parameters:
%      %   current: index of last leaf element returned by next_leaf_index()
%      %            respectively first_leaf_index()
%      %
%      % Return values:
%      %   next: index of leaf element right of current.
%      %


%      if nargin < 2
%        ids = [];
%      end
%      if nargin < 3
%        mu_cube = [];
%      end
%      if nargin < 4
%        tslice = [];
%      end

%      if isempty(current)
%        % current is a root and leaf element => no more leafs
%        next = -1;
%      else
%        next = [];
%        % are we _not_ directly above the current leaf?
%        if length(current) > 1
%          next_tmp = next_leaf_index(get(this, current(1)), current(2:end-i), ids, mu_cube, tslice);
%          if next_tmp ~= -1
%            next = [current(1), next_tmp];
%          end

%        end

%        % 2. here we are: all children of current(1) are already iterated or
%        % current(1) is a leaf, so we can find the next child of 'this'.
%        if isempty(next)
%          % get the next candidate...
%          nextchild_index = get_first_index_match(this, ids, mu_cube, tslice, current(1));
%          if nextchild_index == -1
%            % there is no candidate on this level...
%            next = -1;
%          else
%            % get the candidate
%            nextchild = get(this, nextchild_index);

%            if ~isa(nextchild, 'INode') || isa(nextchild, 'DataTree.ILeafNode')
%              % it is a leaf element
%              next = nextchild_index;
%            else
%              % another tree, find all its leafs...
%              next = [ nextchild_index, first_leaf_index(nextchild, ids, mu_cube, tslice) ];
%            end
%          end
%        end
%      end

%    end

%    function indices = get_indices(this, ids, mu_cube, tslice)

%      if nargin < 2
%        ids = [];
%      end
%      if nargin < 3
%        mu_cube = [];
%      end
%      if nargin < 4
%        tslice = [];
%      end

%      indices = {};
%      index = first_leaf_index(this, ids, mu_cube, tslice);
%      while index ~= -1
%        indices = [indices, { index }];
%        index = next_leaf_index(this, index, ids, mu_cube, tslice);
%      end
%    end
%

    function description = get_active_leaf_description(this, model, ids)
      % function description = get_active_leaf_description(this, model, ids)
      % returns an enumeration of all leaves' basepath index vectors with a
      % description of their parents.
      %
      % Parameters:
      %   model: a reduced or detailed model of type .IModel holding
      %           information about the selected parameters and maybe the time
      %           instant.
      %   ids:     ID filter. See create_tree() for details.
      %
      % Optional fields of model:
      %   descr:   ModelDescr object specifying the problem discretization
      %   descr.t: current time step number

      tslice = [];
      if isfield(model.descr, 't')
        tslice = [model.descr.t, model.descr.t];
      end
      mu_cube = [get_mu(model), get_mu(model)];
      if nargin <= 2
        ids = [];
      end

      description = create_tree(this, DataTree.LeafDescription, ids, mu_cube, tslice, []);
    end

    function description = get_leaf_description(this, ids, mu_cube, tslice)
      % function description = get_leaf_description(this, ids, mu_cube, tslice)
      % returns an enumeration of all leaves' basepath index vectors with a
      % description of their parents.
      %
      % Parameters:
      %   ids:     ID filter. See create_tree() for details.
      %   mu_cube: parameter filter. See create_tree() for details.
      %   tslice:  time filter. See create_tree() for details.

      if nargin < 2
        ids = [];
      end
      if nargin < 3
        mu_cube = [];
      end
      if nargin < 4
        tslice = [];
      end
      basepath = [];

      description = create_tree(this, DataTree.LeafDescription, ids, mu_cube, tslice, basepath);
    end

%    function leaf_func(this, funcptr, ids, mu_cube, time_slices)

%      leaf_indices = get_indices(this, ids, mu_cube, time_slices);
%      for i = 1:length(leaf_indices)
%        leaf = get(this, leaf_indices(i));
%        funcptr(leaf);
%      end
%    end

    function tstop = index_valid_till(this, index)
      % function tstop = index_valid_till(this, index)
      % Returns the last valid time step index of a time slice
      %
      % This method can be used to obtain the last time slice index for the
      % node given by 'get(this, index)'
      %
      % Parameters:
      %  index: the index vector of the child for which the time slice shall be
      %         analyzed.
      %
      % Return values:
      %  tstop: last valid time step index
      if ~isempty(index)
        tstop = index_valid_till(get(this, index(1)), index(2:end));
      else
        tstop = Inf;
      end
    end

    function data = get_by_description(this, id, mu, nt)
      % function data = get_by_description(this, id, mu, nt)
      % A combination of get_index() and get()
      %
      % This methods gets the child node described by \a id, \a mu and \a nt.
      %
      % Parameters:
      %  id: a string id filtered through an DataTree.IdMapNode in the tree hierarchy.
      %  mu: a parameter vector filtered through a DataTree.PpartNode instance in the
      %      tree hierarchy.
      %  nt: an integer corresponding to a time step index filtered through a
      %      DataTree.TpartNode instance in the tree hierarchy.
      %
      % Return values:
      %  data: the children node of type INode

      if nargin < 3
        mu = [];
      end
      if nargin < 4
        nt = [];
      end
      data = get(this, get_index(this, id, mu, nt));
    end

    function active_leaf_index = get_active_leaf_index(this, model, id)
      % function active_leaf_index = get_active_leaf_index(this, model[, id])
      % retuns the leaf element index for the current IDetailedModel configuration.
      %
      % Parameters:
      %   model: a reduced or detailed model of type ::IModel holding
      %           information about the selected parameters and maybe the time
      %           instant.
      %   id:     optional parameter defining a special ID that shall be
      %           attached to the leaf element.
      %
      % Return values:
      %   active_leaf_index: leaf element index to be returned.
      %
      % Optional fields of model:
      %   descr:   ModelDescr object specifying the problem discretization
      %   descr.t: current time step number
      %
      % @todo rename this method to get_leaf_index
      nt = [];
      if isfield(model.descr, 't')
        nt = model.descr.t;
      end
      if nargin <= 2
        id = [];
      end
      active_leaf_index = get_by_description(this, id, get_mu(model), nt);
    end

    function active_leaf = get_active_leaf(this, model, id)
      % function active_leaf = get_active_leaf(this, model[, id])
      % retuns the leaf element for the current IDetailedModel configuration.
      %
      % Parameters:
      %   model: a reduced or detailed model of type ::IModel holding
      %           information about the selected parameters and maybe the time
      %           instant.
      %   id:     optional parameter defining a special ID that shall be
      %           attached to the leaf element.
      %
      % Return values:
      %   active_leaf: leaf element of type ::DataTreeLeafNode to be
      %                returned.
      %
      % Optional fields of model:
      %   descr:   ModelDescr object specifying the problem discretization
      %   descr.t: current time step number
      %
      % @todo rename this method to get_leaf

      nt = [];
      if isfield(model.descr, 't')
        nt = model.descr.t;
      end
      if nargin <= 2
        id = [];
      end
      active_leaf = get_active_leaf(get_by_description(this, id, get_mu(model), nt), model);
    end

    function display(this, fn, basepath, name)
      % function display(this, fn, basepath, name)
      % overwrites the standard display method for DataTree objects
      %
      % Parameters:
      %   fn: Optional filename under which a dot-file depicting the tree
      %       structure is stored.
      %   basepath: only used in recursive calls of this method
      %   name:     only used in recursive calls of this method
      if nargin == 1
        fn = [];
      end
      if nargin <= 2
        basepath = [];
      end
      if nargin <= 3
        name = inputname(1);
      end
      lines = disp_node(this, basepath, fn);
      disp([repmat(' |', 1, length(basepath)),'-- <a href="matlab: htdoc(''', class(this), ''')">', class(this), '</a>']);
      disp('');
      if length(lines) > 8
        disp([repmat(' |', 1, length(basepath)), ...
          '   <a href="matlab: display(get(',...
          name, ',', mat2str(basepath), ...
          '))">get(', name, ',',  mat2str(basepath), ')</a>']);
      else
        for i = 1:length(lines)
          lfind = strfind(lines{1}, '<a href');
          if i == 1 && lfind(1) == 1
            continue
          end
          disp([repmat(' |', 1, length(basepath)), '  ', lines{i}]);
        end
      end
      for i = 1:length(this)
        child = get(this, i);
        if isa(child, 'DataTree.INode')
          display(child, fn, [basepath, i], name);
        else
          disp(child);
        end
      end
    end

    function lines = disp_node(this, basepath, fn)
      % function lines = disp_node(this, basepath, fn)
      % returns a cell array of strings with information on the node.
      %
      % The default implementation adds the output of the 'disp' command.
      %
      % Parameters:
      %   basepath: the index path needed to reach this element from the root.
      %   fn:       a file name string for a dot file that can be generated
      %
      % Return values:
      %   lines: the cell array of strings

      disp_text = evalc('disp(this)');
      lno = 1;
      while(~isempty(disp_text))
        [lines{lno}, disp_text] = strtok(disp_text, sprintf('\n'));
        lno = lno + 1;
      end

    end

  end

end