IReducedModel.m

classdef IReducedModel < IModel
  % This is the interface for a reduced model providing methods to compute low
  % dimensional reduced simulations based on a priori generated reduced basis
  % spaces.
  %
  % An IReducedModel implementation is the final puzzle piece in the reduced
  % basis framework as described the section on the @ref rbm_interface "main
  % interfaces".
  %
  % Note, that this interface implements an IDetailedModel interface, by
  % forwarding all methods to the underlying #detailed_model. By this, the
  % reduced model is the only needed. This is again for historic reasons
  % assuring compatibility with old codes which did not distinguish between
  % reduced and detailed models.
  %
  % Usually a reduced model 'r_model' is used in the following way and order:
  %  -# Generate detailed data
  %     @code reduced_data = gen_detailed_data(r_model, model_data) @endcode
  %  -# Generate reduced data
  %     @code reduced_data = gen_reduced_data(r_model, detailed_data) @endcode
  %  -# (Optionally) extract a subset from this reduced_data
  %     @code reduced_data = extract_reduced_data_subset(r_model, reduced_data) @endcode
  %  -# Compute one or more reduced simulations by
  %     -# Setting the active parameter
  %        @code set_mu(r_model, mu) @endcode
  %        and
  %     -# executing the simulation
  %        @code rb_sim_data = rb_simulation(r_model, reduced_data) @endcode
  %  -# Optionally reconstruct the reduced simulation snapshots
  %     `u_{\text{red}}(\cdot; t^k, \mu) \in {\cal W}_{\text{red}}`
  %     @code rb_sim_data = rb_reconstruction(r_model, detailed_data, rb_sim_data) @endcode
  %

  properties(Dependent, SetAccess = private)
    % @copybrief IDetailedModel.descr
    descr;
  end

  properties (Dependent)
    decomp_mode;
  end

  properties (SetAccess = private, Dependent)
    % cell array of strings describing the parameters of the model
    mu_names;

    % cell array of vectors of size two defining the allowed interval range for
    % the parameter components
    mu_ranges;

    % an integer defining the verbosity level of information output during
    % basis generation
    verbose;

    % an integer defining the debugging level controlling error output and
    % extra tests during basis generation
    debug;
  end

  properties
    % flag indicating whether this model depends on collateral reduced basis
    % spaces.
    crb_enabled = false;

    % an object of type IDetailedModel which shall be reduced
    detailed_model;

    % a structure of type BasisGenDescr defining the basis generation routines
    % and data structures.
    bg_descr;
  end

  properties(Abstract)
    % boolean flag indicating whether during an rb_simulation() an a posteriori
    % error estimator shall be computed.
    %
    % This flag needs to be set to 'true' for certain Basis generation
    % configurations.
    enable_error_estimator;
  end

  properties
    % control variable for the size of the reduced basis used for reduced
    % simulations. By default this is equal to the size of the generated
    % reduced basis.
    N       = 0;

    % control variable for the size of the (collateral) reduced basis used for
    % empirical interpolations. By default this is equal to the size of the
    % generated reduced basis.
    M       = 0;

    % control variable for the number of (collateral) reduced basis vectors
    % used for error estimation. By default this is equal to zero.
    Mstrich = 0;
  end

  methods
    function rmif = IReducedModel(dmodel, bg_descr)
      % Constructor of a reduced model
      %
      % Parameters:
      %   dmodel: the object of type IDetailedModel for which the reduced model
      %           shall be constructed.
      if nargin == 1 || isempty(bg_descr)
        copy = dmodel;
        % check if the first argument is an IReducedModel -> copy constructor
        if isa(copy, 'IReducedModel')
          % dmodel constructor
          m = metaclass(dmodel);
          fns = m.Properties(cellfun(@(x) ~isequal(x.SetAccess, 'none') && ~x.Dependent, m.Properties));
          fns = cellfun(@(x) x.Name, fns, 'UniformOutput', false);
          for i=1:length(fns)
            rmif.(fns{i}) = copy.(fns{i});
          end
        else
          error('IReducedModel copy constructor needs to get only one argument');
        end
      elseif nargin == 2
        rmif.detailed_model = dmodel;
        rmif.bg_descr       = bg_descr;
        if ~IReducedModel.struct_check(bg_descr, ...
                                       struct( ...
            'reduced_data_constructor',  {{@(x) isequal(class(x), 'function_handle')}}, ...
            'detailed_data_constructor', {{@(x) isequal(class(x), 'function_handle')}}...
                                             )...
                                       );
          error('Consistency check for IReducedModel failed');
        end
      else
        error('IReducedModel constructor needs to get two arguments');
      end
    end

    function descr = get.descr(this)
      descr = this.detailed_model.descr;
    end

    function mu_ranges = get.mu_ranges(this)
      mu_ranges = this.detailed_model.descr.mu_ranges;
    end

    function mu_names = get.mu_names(this)
      mu_names = this.detailed_model.descr.mu_names;
    end

    function decomp_mode = get.decomp_mode(this)
      decomp_mode = this.detailed_model.descr.decomp_mode;
    end

    function set.decomp_mode(this, decomp_mode)
      this.detailed_model.decomp_mode = decomp_mode;
    end

    function debug = get.debug(this)
      debug = this.detailed_model.descr.debug;
    end

    function verbose = get.verbose(this)
      verbose = this.detailed_model.descr.verbose;
    end

    function iseq = eq(this, other)
      % function iseq = eq(this, other)
      % Comparison operator checking whether the underlying #detailed_model
      % members of 'this' and 'other' are equal.
      %
      % Parameters:
      %   other:  an object of type IReducedModel we want to compare with.
      %
      % Return values:
      %   iseq:   a boolean value indicating whether 'this' and 'other' are
      %           equal.
      iseq = (this.detailed_model == other.detailed_model);
    end

    function reduced_data = gen_reduced_data(this, detailed_data)
      % function reduced_data  = gen_reduced_data(this, detailed_data);
      % Constructs the 'reduced_data' object holding low dimensional data needed
      % for efficient reduced simulations with rb_simulation().
      %
      % Return values:
      %  reduced_data:  reduced data object of type IReducedData.

      reduced_data = this.bg_descr.reduced_data_constructor(this, detailed_data);
    end

    function reduced_data_subset  = extract_reduced_data_subset(this, reduced_data)
      % function reduced_data  = extract_reduced_data_subset(this, reduced_data);
      % Extracts a subset of the 'reduced_data' generated by gen_reduced_data().
      %
      % Return values:
      %  reduced_data:  object of type IReducedData holding a subset of the
      %                 reduced data fields as they were generated by
      %                 gen_reduced_data().

      if isa(reduced_data, 'IDetailedData')
        reduced_data_subset = gen_reduced_data(this, reduced_data);
      else
        reduced_data_subset = extract_reduced_data_subset(reduced_data, this);
      end
    end
  end

  methods(Abstract)


    % function rb_sim_data   = rb_simulation(this, reduced_data);
    % Executes a reduced simulation and optionally an error estimation.
    %
    % Return values:
    %  rb_sim_data:  structure holding the coefficient vectors of the reduced
    %                simulations and optional error estimators.
    rb_sim_data   = rb_simulation(this, reduced_data);

    % function rb_sim_data   = rb_reconstruction(this, detailed_data, rb_sim_data);
    % reconstructs the reduced simulation snapshots generated by
    % rb_simulation() in the reduced space `{\cal W}_{\text{red}}`.
    %
    % Possible implementations are:
    %  - rb_reconstruction_default().
    %
    % Parameters:
    %  rb_sim_data:   struct holding reduced simulation data returned by
    %                 IReducedModel.rb_simulation() .
    %
    % Return values:
    %  rb_sim_data:   struct holding the reduced simulation results and their
    %                 reconstructions.
    rb_sim_data   = rb_reconstruction(this, detailed_data, rb_sim_data);

    % function c = copy(this);
    % function that deep copies this handle class
    %
    % The suggested implementation in the implementation class should call a
    % copy constructor which might look as follows: 
    %
    % @code
    % // this implements a copy constructor if necessary...
    % rm = rm@IReducedModel(detailed_model, bg_descr);
    % // are we NOT a copy constructor?
    % if ~isa(detailed_model, 'Implementation.ReducedModel')
    %   // do some checks and further initializations here...
    % end
    % @endcode
    %
    % Return values:
    %   c:   an object of type IReducedModel which is a deep copy of this object.
    c = copy(this);
  end

  methods(Static, Abstract)
    % function Delta        = get_estimators_from_sim_data(sim_data);
    % Static helper method returning the vectors of error estimators for each
    % reduced simulation snapshot `u_{\text{red}}(\cdot, t^k)` generated by
    % rb_simulation().
    %
    % Parameters:
    %  rb_sim_data:   struct holding reduced simulation data returned by
    %                 IReducedModel.rb_simulation() .
    %
    % Return values:
    %  Delta:   This is a '(K+1) x 1' vector of estimates `\eta^k(\mu)`
    Delta        = get_estimators_from_sim_data(rb_sim_data);

    % function Delta        = get_estimator_from_sim_data(sim_data);
    % Static helper method returning an error estimator for the whole
    % reduced trajectory `\{u_{\text{red}}(\cdot, t^k)\}_{k=0}^{K}` generated
    % by rb_simulation().
    %
    % Parameters:
    %  rb_sim_data:   struct holding reduced simulation data returned by
    %                 IReducedModel.rb_simulation() .
    %
    % Return values:
    %  Delta:   This is a scalar computed from the estimates `\eta^k(\mu)`.
    %           Usually the maximum over `k=0,\ldots,K` is returned.
    Delta        = get_estimator_from_sim_data(rb_sim_data);

  end

  methods

    function U            = get_dofs_from_sim_data(rmodel, sim_data)
      % function U            = get_dofs_from_sim_data(sim_data)
      % @copybrief IDetailedModel.get_dofs_from_sim_data()
      %
      % @copydetails IDetailedModel.get_dofs_from_sim_data()
      U = rmodel.detailed_model.get_dofs_from_sim_data(sim_data);
    end

  end

  methods
    function detailed_data = gen_detailed_data(this, model_data)
      % function detailed_data = gen_detailed_data(this, model_data)
      % initiates the reduced basis generation process
      %
      % This function calls the IDetailedData constructor specified by
      % 'bg_descr.detailed_data_constructor' and returns the generated detailed
      % data object..
      %
      % Return values:
      %   detailed_data: constructed detailed data object of type
      %                  IDetailedData.

      detailed_data = this.bg_descr.detailed_data_constructor(this, model_data);
    end

    function p = plot_sim_data(rmodel, model_data, sim_data, plot_params)
      % function p = plot_sim_data(rmodel, model_data, sim_data, plot_params)
      % @copybrief IDetailedModelplot_sim_data()
      %
      % This method actually calls the 'plot_sim_data()' method on the
      % #detailed_model member.
      % @copydetails IDetailedModel.plot_sim_data()
      p = plot_sim_data(rmodel.detailed_model, model_data, sim_data, plot_params);
    end

    function model_data = gen_model_data(this)
      % @copybrief IDetailedModelgen_model_data()
      %
      % This function call is forwarded to the underlying #detailed_model.
      %

      model_data    = gen_model_data(this.detailed_model);
    end

    function sim_data = detailed_simulation(this, model_data)
      % @copybrief IDetailedModel.detailed_simulation()
      %
      % This function call is forwarded to the underlying #detailed_model.
      %
      % Return values:
      %  sim_data: structure holding the detailed simulation result.
      sim_data = detailed_simulation(this.detailed_model, model_data);
    end

    function this     = set_mu(this, mu)
      % function this = set_mu(this, mu)
      % Sets the active parameter vector `\mu \in {\cal M}` used for simulations
      % on this model.
      %
      % The parameter set here, is also used by the rb_simulation() function.
      % So, the #detailed_model and the reduced model's internal parameter
      % vector in sync.
      %
      % Parameters:
      %   mu: The parameter vector `\mu`.
      %
      % Return values:
      %  this: handle to the changed IReducedModel

      this.detailed_model = set_mu(this.detailed_model, mu);

    end

    function mu       = get_mu(this)
      % function mu = get_mu(this)
      % returns the active parameter vector `\mu \in { \cal M }`
      %
      % Return values:
      %   mu: The parameter vector `\mu`
      mu = get_mu(this.detailed_model);
    end
    
    function rb_size = get_rb_size(this, detailed_data)
      % function rb_size = get_rb_size(this, detailed_data)
      % returns the size of the generated reduced basis by the
      % IDetailedData class.
      %
      % This method only forwards the call to the
      % IDetailedData.get_rb_size() method. So, it is pretty useless, but
      % necessary for compatibility with the old interface...
      rb_size = get_rb_size(detailed_data);
    end

    function couple_N_and_M(this, detailed_data, ratio, factor)
      % function couple_N_and_M(this, detailed_data, ratio, factor)
      % sets all the basis sizes for reduced simulations by a ratio with
      % respect to the maximum possible basis size and a factor between RB and
      % EI basis sizes.
      %
      % This method sets
      % ``(N, M^{L_1}, \dots, M^{L_q})
      %    = \left(\lfloor r N_{\max} \rfloor, \lfloor r_M M_{\max}^{'L_1} \rfloor,
      %            \dots, \lfloor r_M M_{\max}^{'L_q} \rfloor\right),``
      % where `r_M = \min\{ rf, 1 \}` and `M_{\max}^{'L} == M_{\max}^L - M'`.
      %
      % Parameters:
      %  ratio:  an integer from the interval `[0, 1]` specifying the ratio `r`
      %          by which the number of collateral reduced basis functions
      %          shall be reduced with respect to the maximum possible.
      %  factor: an (optional) positive factor `f` between RB and EI basis
      %          sizes. (default = 1)

      assert(ratio >= 0 && ratio <= 1.0);

      if nargin == 3
        factor = 1.0;
      end
      assert(factor >= 0);

      Nmax   = get_rb_size(detailed_data);
      this.N = floor(Nmax * ratio);
      set_Mratio(this, detailed_data, min(ratio*factor,1));
    end

    function this = set_Mratio(this, detailed_data, ratio)
      % function set_Mratio(this, detailed_data, ratio)
      % in case of multiple operators subject to empirical interpolation, this
      % sets number of reduced basis functions used for reduced simulations by
      % specifying a ratio.
      %
      % This method sets
      % ``M^{L} = \lfloor M_{\max}^{'L} \cdot \text{ratio} \rfloor``
      % for all operators/functions `L`, where `M_{\max}^{'L} == M_{\max}^L - M'`.
      %
      % Parameters:
      %  ratio:  an integer from the interval `[0, 1]` specifying the ratio by
      %          which the number of collateral reduced basis functions shall
      %          be reduced with respect to the maximum possible.
      assert(ratio <= 1 && ratio >= 0);
      Mmax   = get_ei_size(detailed_data.datatree);
      if isa(Mmax, 'DataTree.IdMapNode')
        for i = 1:length(Mmax)
          set(this.M,i,floor((get(Mmax,i)-this.Mstrich) * ratio));
        end
      else
        this.M = floor((Mmax-this.Mstrich) * ratio);
      end
    end

    function Mratio = get_Mratio(this, detailed_data)
      % function Mratio = get_Mratio(this, detailed_data)
      % in case of multiple operators subject to empirical interpolation, this
      % gets the mean of ratio between the number of reduced basis functions
      % used for reduced simulations and the maximum possible.
      %
      % This function gets the mean of
      % `\frac{M^{L}}{M_{\max}^{L}}` over for all operators/functions `L`.
      %
      % Return values:
      %  Mratio:  an integer from the interval `[0, 1]` specifying the ratio by
      %           which the number of collateral reduced basis functions is
      %           reduced with respect to the maximum possible.
      M    = this.M;
      if isa(M, 'DataTree.IdMapNode')
        M = scalar(M, @(x) mean([x{:}]));
      end
      Mmax = get_ei_size(detailed_data.datatree);
      if isa(Mmax, 'DataTree.IdMapNode')
        Mmax = scalar(Mmax, @(x) mean([x{:}]));
      end
      if ~isempty(Mmax)
        Mratio = M/Mmax;
      end

    end

    function ret = subsref(this, S)
      % function ret = subsref(this, S)
      % forwarding of fieldnames access to the underlying detailed_model description
      %
      % If the user calls 'r_model.parameter' and the field 'parameter' exists
      % in the underlying model, the value of 'detailed_model.descr.parameter' is
      % returned. This method is implemented for compatibility reasons, such that
      % a basis generation object can be used like an old model. Try to prevent
      % usage of this method in the future.
      %
      % @note that this method throws a 'RBmatlab:Compatibility' warning if a
      % description field is accessed.

      ddescr = this.detailed_model.descr;
      thissubs = [properties(this); methods(this)];
      fns = setdiff(fieldnames(ddescr), thissubs);
      if S(1).type(1) == '.' ...
         && ~isempty(intersect(fns, S(1).subs))
        warning('RBmatlab:Compatibility', ...
          ['Requesting the reduced_model field ''', S(1).subs, ...
           '''\nfrom a IReducedModel object! Maybe you should\n',...
           'substitute the ''rmodel'' by a ''rmodel.detailed_model''']);
        ret = this.descr.(S(1).subs);
      else
        if nargout == 1
          ret = builtin('subsref', this, S);
        else
          builtin('subsref', this, S)
        end
      end
    end
  end

end