IRefineable.m

classdef IRefineable < ParameterSampling.Interface
  % Interface class for parameter sample classes that allow the adaptive
  % refinement of the sampling

  properties
    % cell array of samples that are generated during refinement cycle
    sample_history   = {};

    % cell array of elements which are refined at each refinement step
    refined_elements = {};
  end

  methods (Abstract)

    cogs = cogs(this);
    % function cogs = cogs(this);
    % returns the center of gravity of sample cells (in case the sample can be
    % viewed as a grid)
    %
    % Usually the center of gravity of grid cells is a new sample vector in
    % case the element is refined.
    %
    % Return values:
    %   cogs: a matrix with sample vectors as row vectors
    %
    % @todo Maybe this should be renamed to refinement_candidates, because
    % otherwise it is restricted to grids.

    max_vertex = elementwise_maximum_of_vertex_values(this, values);
    % function max_vertex = elementwise_maximum_of_vertex_values(this, values);
    % returns `\max_{v \in V(e)} \text{val}_v` for each sample cell `e` (in
    % case the sample can be viewed as a grid with vertices as sample vectors)
    %
    % Return values:
    %   max_vertex: vector of maxima as described above

    this = refine(this, elems);
    % function this = refine(this, elems);
    % refines the object at the the given elements
    %
    % At each refinement, the refined elements and the previous sample is added
    % to the cell arrays #sample_history and #refined_elements
    %
    % Parameters:
    %   elems: A vector of element indices to be refined
    %
    % Return values:
    %   this: the updated object of type IRefineable

    level = get_refinement_levels(this);
    % function level = get_refinement_levels(this);
    % returns the number of refinement steps for each sample element
    %
    % Return values:
    %   level: a vector with number of refinement steps for each sample element

    skips = skipped_refinements(this);
    % function skips = skipped_refinements(this);
    % determines for every sample element how often it was skipped during the
    % last refinement steps.
    %
    % Return values:
    %   skips: a vector of the number of skips for each sample element.

  end
  methods

    function sample = get_sample_at_ref_level(this, ref_level)
      % function sample = get_sample_at_ref_level(this, ref_level)
      % helper function returning the sample at a given refinement level
      %
      % Parameters:
      %   ref_level: the refinement level
      %
      % Return values:
      %   sample:    the parameter sample how it looked like before refinement
      %              step 'ref_level'

      if ref_level > length(this.sample_history)
        sample = this.sample;
      else
        sample = this.sample_history{ref_level};
      end
    end

  end
end