Interface.m

classdef Interface < handle
  % %Interface class for extension algorithms which define the basis extension
  % routines used by the abstract Greedy algorithm class Greedy.Algorithm
  %
  % Here, we usually assume, that we have
  %   - @em detailed algorithms producing high dimensional solutions
  %     `v_h(t^k;\mu) \in {\cal W}_h` and
  %   - @em reduced algorithms producing corresponding low dimensional
  %     solutions `v_{\text{red}}(t^k;\mu) \in {\cal W}_{\text{red}} \subset {\cal W}_h`.
  %
  % By enriching the subspace `{\cal W}_{\text{red}}`, we can improve the
  % reduced algorithms.
  %
  % Most prominent examples of Interface implementations are the classes
  % Greedy.Plugin.EI and Greedy.Plugin.POD

  properties(SetAccess = private, Dependent)
    % a string identifying the basis extension algorithm, should be unique over
    % all instances of Interface implementations.
    id;
  end

  properties(Abstract)
    % boolean flag specifying whether we want to use the relative error for
    % error_indicators() and compute_error() methods.
    relative_error;

    % string specifying which indicators shall be used by the
    % error_indicators() method.
    %
    % Possible values are:
    %   'error'      for an error between the detailed and the reduced computation.
    %   'estimator'  for an a posteriori error estimator
    indicator_mode;
  end

  properties(Abstract, Dependent)

    % boolean indicating whether the prepare_reduced_data() method needs to be
    % computed before error_indicators can be computed.
    needs_preparation;
  end

  properties(Abstract, Constant)
    % @copybrief GreedyInterfacegenerated_basis_type
    %
    % @copydetails GreedyInterfacegenerated_basis_type
    generated_basis_type;
  end

  properties

    % an object of type SnapshotsGenerator.Cached generating possible (high dimension)
    % basis functions
    generator;
  end

  methods
    function gei = Interface(generator)
      % function gei = Interface(generator)
      % constructor for a greedy extension object
      %
      % Parameters:
      %   generator: object of type SnapshotsGenerator.Cached generating the (high
      %              dimensional) basis functions

      gei.generator = generator;
    end

    function id = get.id(this)
      id = this.generator.id;
    end

  end

  methods(Abstract)
    % function detailed_data = init_basis(this, rmodel, model_data, M_train);
    % creates an initial detailed data node storing an initial reduced basis
    %
    % Parameters:
    %   rmodel: an object of type ::GreedyUser::IReducedModel specifying the
    %           basis generation process.
    %   M_train: an object of type ParameterSampling.Interface specifying the parameter
    %            vector set `{\cal M}_{\text{train}}` from which the basis
    %            functions are obtained.
    %
    % Return values:
    %   detailed_data: an object of type Greedy.DataTree.Detailed.INode storing the initial
    %                  reduced basis vectors.
    detailed_data = init_basis(this, rmodel, model_data, M_train);

    % function prepare_reduced_data(this, rmodel, detailed_data);
    % prepares reduced data that is necessary for the execution of other
    % methods if indicated by needs_preparation.
    %
    % Methods that might depend on the execution of this method are:
    %   - compute_error()
    %   - generate_reduced()
    %   - Greedy.Plugin.Default.error_estimators()
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the
    %           basis generation process.
    %   detailed_data: of type .Greedy.User.IDetailedData
    prepare_reduced_data(this, rmodel, detailed_data);

    % function [max_errs, max_err_sequence, max_mu_index] = error_indicators(this, rmodel, detailed_data, parameter_set, reuse_reduced_data);
    % computes error indicators for the reduced simulations for every parameter
    % vector from a given parameter set `{\cal M}_{\text{train}}`.
    %
    % An error indicator estimates an error
    %   ``\eta^k(\mu) \geq \| v_h(t^k;\mu) - v_{\text{red}}(t^k;\mu) \|``
    % for every time step `0\leq t^0, \ldots, t^K = T` and every parameter `\mu
    % \in {\cal M}`. The norm is a problem specific norm determined by the
    % options in 'rmodel'.
    %
    % This function's main use is to find a parameter vector
    % ``\mu_{\max} = \arg \sup_{\mu \in {\cal M}_{\text{train}} } \max_{k=0,\ldots,K} \eta^k(\mu)``.
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the
    %           basis generation process.
    %   detailed_data: of type .Greedy.User.IDetailedData
    %   parameter_set: a set of parameter vectors `{\cal M}_{\text{train}}` as
    %                  returned by ParameterSampling.Interface.space .
    %   reuse_reduced_data: optional flag indicating whether the reduced data needed for
    %            reduced simulations or computation of error estimators is
    %            still valid since its last generation. (default = 'false')
    %
    % Return values:
    %   max_errs: a matrix of size 'n_parameters x model.nt+1' storing the
    %             error indicator `\eta^k(\mu)` for every `k=0,\ldots,K` and
    %             `\mu \in {\cal M}_{\text{train}}`.
    %   max_err_sequence: a sequence of error indicators `\eta^k(\mu_{\max})`
    %                     for every `k=0,\ldots,K`.
    %   max_mu_index: the index of the parameter vector `\mu_{\max}` in the
    %                 'parameter_set' matrix.
    %
    [max_errs, max_err_sequence, max_mu_index] = error_indicators(this, rmodel, detailed_data, parameter_set, reuse_reduced_data);

    % function errs = compute_error(this, rmodel, detailed_data);
    % computes the "true" error between a reduced and a detailed function `\|
    % v_h(t^k;\mu) - v_{\text{red}}(t^k;\mu) \|`.
    %
    % @note This function might depend on a previous execution of prepare_reduced_data().
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the
    %           basis generation process. The parameter `\mu` for which the
    %           error shall be computed must be set by 'set_mu(rmodel, mu)'
    %           before.
    %   reduced_data: of type .Greedy.User.ReducedData
    %   detailed_data: of type .Greedy.User.IDetailedData
    %
    % Return values:
    %   errs: a sequence of errors at every time step `k=0,\ldots,K`.
    errs = compute_error(this, rmodel, reduced_data, detailed_data);

    % function Uapprox = generate_reduced(this, rmodel, reduced_data, detailed_data, U);
    % generates a reduced function `v_{\text{red}}(\mu)`.
    %
    % @note This function might depend on a previous execution of prepare_reduced_data().
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the basis
    %           generation process. The parameter `\mu` for which the error
    %           shall be computed must be set by 'set_mu(rmodel, mu)' before.
    %   reduced_data: an object of type .Greedy.User.ReducedData storing all
    %                 (low-dimensional) reduced matrices and vectors needed for
    %                 reduced simulations.
    %   detailed_data: of type .Greedy.User.IDetailedData
    %   U: optional DOF vector, for example operator evaluations.
    %
    % Return values:
    %   Uapprox: A sequence of Dof vectors of the functions
    %            `v_{\text{red}}(\cdot;t^k,\mu)`.
    Uapprox = generate_reduced(this, rmodel, reduced_data, detailed_data, U);

    % function [breakloop, reason] = pre_check_for_end(this, rmodel, detailed_data);
    % checks whether the basis generation process has come to an end.
    %
    % Global break conditions (error_tolerance, timeout and validation ratio)
    % are handled by Greedy.Algorithm .
    %
    % Parameters:
    %   rmodel: of type .Greedy.User.IReducedModel
    %   detailed_data: of type .Greedy.User.IDetailedData
    %
    % Return values:
    %   breakloop: boolean flag indicating whether the basis generation process
    %              is finished for this reduced basis space.
    %   reason:    descriptive text telling about the reasons why, the
    %              extension process needs to break.
    [breakloop, reason] = pre_check_for_end(this, rmodel, detailed_data);

%    breakloop = post_check_for_end(this, detailed_data);

    % function detailed_data = basis_extension(this, rmodel, detailed_data, max_err_seq, mu);
    % extends the reduced basis space from a given function `v_{h}(\mu)`.
    %
    % This generates a new basis function `\varphi_{n+1} \in {\cal W}_h` from
    % the sequence of detailed functions `v_h(t^k,\mu)` for `k=0,\ldots,K` as
    % returned by the SnapshotsGenerator.Cached generator.
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the
    %           basis generation process.
    %   detailed_data: of type .Greedy.User.IDetailedData
    %   max_err_seq: sequence of error indicators as returned as second return
    %                argument of error_indicators()
    %   mu:     paramter vector `\mu`.
    %
    % Return values:
    %   detailed_data:  updated data tree node of type Greedy.DataTree.Detailed.INode .
    detailed_data = basis_extension(this, rmodel, detailed_data, max_err_seq, mu);

    % function detailed_data = finalize(this, rmodel, detailed_data);
    % function called after the last extension process
    %
    % Parameters:
    %   rmodel: an object of type .Greedy.User.IReducedModel specifying the
    %           basis generation process.
    %   detailed_data: of type .Greedy.User.IDetailedData
    %
    % Return values:
    %   detailed_data:  updated data tree node of type Greedy.DataTree.Detailed.INode .
    detailed_data = finalize(this, rmodel, detailed_data);

  end
end