ICreator.m

classdef ICreator < handle
  % interface for a class used to create a new (sub-)tree from an old one with the
  % DataTree.INode.create_tree() method.
  %
  % @section data_tree_creator_restriction Sub-tree definition
  %
  % The copied tree can be defined as a sub-tree of the original by restricting it to certain
  %  - IDs,
  %  - parameters,
  %  - or time instants.
  %
  % This can be useful if you want to reorder your tree. For the computation of
  % a single trajectory of an instationary problem for example, you are
  % interested in the reduced basis spaces for all time instants, but a
  % specific parameter only.
  %
  % All three restrictions can be optionally added as arguments to the
  % DataTree.INode.create_tree() method.
  %   - The IDs are restricted by a cell array of allowed ID strings. (c.f.
  %     .DataTree::IdMapNode)
  %   - The parameters are restricted by a cell array of two parameter vectors
  %     describing two points of a cube in the parameter space. All DataTree
  %     nodes for parameters in this cube are allowed. (c.f.
  %     .DataTree::PpartNode)
  %   - The time instants are restricted by a '1x2' vector of time instants
  %     defining a time interval. All time instants lying in this interval are
  %     allowed. (c.f. .DataTree::TpartNode)


  methods (Abstract)
    % function node = create_tpart_node(this, t_part_map, initvalues);
    % is called on @ref DataTree.PpartNode elements of a DataTree and
    % returns a new p-part node out of it.
    %
    % Parameters:
    %   t_part_map: the DataTree.TpartNode.tpart_map of the original
    %               t-part node. Optionally this map can be restricted by a
    %               time interval as described in
    %               @ref data_tree_creator_restriction.
    %   initvalues: the @ref DataTree.TpartNode.values "children vector" of the original
    %               t-part node. Optionally this map can be restricted by a
    %               time interval as described in
    %               @ref data_tree_creator_restriction.
    %
    % Return values:
    %   node:     the freshly generated p-part element of type .DataTree.PpartNode
    node = create_tpart_node(this, t_part_map, initvalues);

    % function node = create_idmap_node(this, id_map, initvalues);
    % is called on @ref DataTree.IdMapNode elements of a DataTree and
    % returns a new ID mapped node out of it.
    %
    % Parameters:
    %   id_map:     the @ref DataTree.IdMapNode.idmap "ID map" of the
    %               original node. Optionally this map can be restricted by a
    %               cell array of restricted IDs as described in
    %               @ref data_tree_creator_restriction.
    %   initvalues: the @ref DataTree.IdMapNode.values "children vector" of the original
    %               node. Optionally this map can be restricted by a
    %               cell array of restricted IDs as described in
    %               @ref data_tree_creator_restriction.
    %
    % Return values:
    %   node:     the freshly generated p-part element of type .DataTree.IdMapNode
    node = create_idmap_node(this, id_map, initvalues);

    % function node = create_ppart_node(this, p_part_map, initvalues);
    % is called on @ref DataTree.PpartNode elements of a DataTree and
    % returns a new p-part node out of it.
    %
    % Parameters:
    %   p_part_map: the DataTree.PpartNode.ppart_map of the original
    %               p-part node. Optionally this map can be restricted by a
    %               parameter cube as described in
    %               @ref data_tree_creator_restriction.
    %   initvalues: the @ref DataTree.PpartNode.values "children vector" of the original
    %               p-part node. Optionally this map can be restricted by a
    %               parameter cube as described in
    %               @ref data_tree_creator_restriction.
    %
    % Return values:
    %   node:     the freshly generated p-part element of type .DataTree.PpartNode
    node = create_ppart_node(this, p_part_map, initvalues);

    % function node = create_leaf_node(this, arg_node, basepath, mu_cube, tslice);
    % is called on @ref .DataTree.ILeafNode "leaf elements" of a DataTree and
    % returns a new leaf out of it.
    %
    % Parameters:
    %   arg_node: original leaf of type DataTree.ILeafNode which shall be used
    %             as basis for the creation of a new one.
    %   basepath: path from the root element to the current leaf.
    %   mu_cube:  restriction of the parameter as described in
    %             @ref data_tree_creator_restriction
    %   tslice:   restriction of the time domain as described in
    %             @ref data_tree_creator_restriction
    %
    % Return values:
    %   node:     the freshly generated leaf element of type .DataTree.ILeafNode.
    node = create_leaf_node(this, arg_node, basepath, mu_cube, tslice);
  end
end