Info.m

classdef Info < handle
  % a DataTree.INode extension for data nodes that can store information on
  % their generation process.

  properties
    % a dynamically growing structure of information fields
    fields = [];

    % a cell array of strings describing why the generation of this node
    % terminated.
    stop_flags = {};
  end

  methods

    function append_field(this, fieldname, value)
      % function append_field(this, fieldname, value)
      % appends a value to an information field storing a vector
      %
      % Parameters:
      %   fieldname: the name of the information field
      %   value: the value to be appended (scalar or column vector)

      if ~isfield(this.fields, fieldname)
        this.fields.(fieldname) = [];
      end
      this.fields.(fieldname) = [ this.fields.(fieldname), value ];
    end

    function set_field(this, fieldname, value)
      % function set_field(this, fieldname, value)
      % sets an information field
      %
      % Parameters:
      %   fieldname: the name of the information field
      %   value: the new value

      this.fields.(fieldname) = value;
    end

    function value = get_field(this, fieldname, default)
      % function value = get_field(this, fieldname, default)
      % returns the value of an information field
      %
      % Parameters:
      %   fieldname: the name of the information field
      %   default: optional default value in case the information field does
      %            not exist.
      %
      % Return values:
      %   value:  the stored value
      if nargin == 2
        assert(isfield(this.fields, fieldname))
      end
      if isfield(this.fields, fieldname)
        value = this.fields.(fieldname);
      else
        value = default;
        this.fields.(fieldname) = default;
      end
    end

    function value = get_field_on_active_child(this, fieldname, model, id)
      % function value = get_field_on_active_child(this, fieldname, model, id)
      % returns the value of an information field from the active leaf node
      %
      % Parameters:
      %   fieldname: the name of the information field
      %   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.
      %
      % Optional fields of model:
      %   t:  the current time step
      %
      % Return values:
      %   value:  the stored value
      if nargin <=3
        id = [];
      end
      if isfield(model, 't')
        nt = model.t;
      else
        nt = [];
      end
      mu = get_mu(model);


      leaf_index = get_index(this, id, mu, nt);

      cur_elem = this;
      iind     = 1;
      value    = [];

      while isempty(value)
        value = get_field(cur_elem, fieldname, []);
        if iind <= length(leaf_index)
          cur_elem = get(cur_elem, leaf_index(iind));
          iind = iind + 1;
        else
          break;
        end
      end

    end

%    function set_field_on_all_leaves(this, field, value)

%      if isa(value, 'DataTree.INode')
%    end

    function set_fields(this, other, fns)
      % function set_fields(this, other, fns)
      % copies fields from another struct
      %
      % Parameters:
      %   other: another struct whose fields shall be copied as information
      %          fields.
      %   fns:   a cell array of strings which acts as a filter for the field
      %          names of 'other'.

      real_fns = intersect(fieldnames(other), fns);
      for i=1:length(real_fns)
        this.fields.(real_fns{i}) = other.(real_fns{i});
      end
    end

    function set_stop_flag(this, flag, on_off)
      % function set_stop_flag(this, flag, on_off)
      % sets the stop flag in this node
      %
      % Parameters:
      %   flag: the flag name,
      %   on_off: boolean flag specifying whether the flag shall set or unset.

      if nargin <=2 || isempty(on_off) || on_off
        this.stop_flags = union(this.stop_flags, {flag});
      else
        this.stop_flags = setdiff(this.stop_flags, {flag});
      end
    end

    function propagate_stop_flag(this, flag, on_off)
      % function propagate_stop_flag(this, flag, on_off)
      % updates the stop flag in all children nodes of the current one.
      %
      % Parameters:
      %   flag: the flag name,
      %   on_off: boolean flag specifying whether the flag shall set or unset.

      if nargin <= 2
        on_off = [];
      end

      set_stop_flag(this, flag, on_off);

      for i = 1:length(this)
        child = get(this, i);
        propagate_stop_flag(child, flag, on_off);
      end

    end

    function stopped_flags = stopped_on_active_child(this, flags, model, id)
      % function stopped_flags = stopped_on_active_child(this, flags, model, id)
      % returns stop flags set on the active child
      %
      % Parameters:
      %   flags: a cell array of flag strings for filtering
      %   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.
      %
      % Optional fields of model:
      %   t:  the current time step
      %
      % Return values:
      %   stopped_flags: a cell array of stop flags found after filtering. If
      %                  only one flag is given in the argument 'flags', a
      %                  boolean value is returned, indicating whether the flag
      %                  is set.

      if nargin <=3
        id = [];
      end
      if isfield(model, 't')
        nt = model.t;
      else
        nt = [];
      end

      if ~iscell(flags)
        flags = {flags};
      end

      mu = get_mu(model);

      leaf_index = get_index(this, id, mu, nt);

      cur_elem      = this;
      stopped_flags = intersect(this.stop_flags, flags);

      for iind = 1:length(leaf_index)
        cur_elem = get(cur_elem, leaf_index(iind));
        stopped_flags = union(stopped_flags, intersect(cur_elem.stopped_flags, flags));
      end

      if length(flags) == 1
        stopped_flags = ~isempty(stopped_flags);
      end
    end

    function stopped_flags = stopped_on_any_child(this, flags)
      % function stopped_flags = stopped_on_any_child(this, flags)
      % returns stop flags set on any child of the current node
      %
      % Parameters:
      %   flags: a cell array of flag strings for filtering
      %
      % Return values:
      %   stopped_flags: a cell array of stop flags found after filtering. If
      %                  only one flag is given in the argument 'flags', a
      %                  boolean value is returned, indicating whether the flag
      %                  is set.


      if ~iscell(flags)
        flags = {flags};
      end

      stopped_flags = intersect(this.stop_flags, flags);

      for i = 1:length(this);
        child = get(this, i);
        stopped_flags = union(stopped_flags, intersect(child.stopped_flags, flags));
      end

      if length(flags) == 1
        stopped_flags = ~isempty(stopped_flags);
      end
    end

    function stopped_flags = stopped_on_all_leafs(this, flags)
      % function stopped_flags = stopped_on_all_leafs(this, flags)
      % returns stop flags set on all children nodes of the current node
      %
      % Parameters:
      %   flags: a cell array of flag strings for filtering
      %
      % Return values:
      %   stopped_flags: a cell array of stop flags found after filtering. If
      %                  only one flag is given in the argument 'flags', a
      %                  boolean value is returned, indicating whether the flag
      %                  is set.

      if ~iscell(flags)
        flags = {flags};
      end

      if length(this) == 0
        stopped_flags = intersect(this.stop_flags, flags);
      else
        stopped_flags = flags;
        for i = 1:length(this)
          child = get(this, i);
          stopped_flags = intersect(stopped_flags, stopped_on_all_children(child, flags));
        end
      end
      if length(flags) == 1
        stopped_flags = ~isempty(stopped_flags);
      end

    end

  end
end