IDetailedModel.m

classdef IDetailedModel < IModel
  % This is the interface for a detailed model providing methods to compute
  % high dimensional simulation snapshots.
  %
  % An IDetailedModel implementation can be combined used as a basis for
  % reduced basis generation routines and a reduced model as described in the
  % section on the @ref rbm_interface "main interfaces".
  %
  % Some basis generation algorithms, however, depend on models with a
  % specialized interface. For example the Greedy.Algorithm class comes with a
  % derived interface class Greedy.User.IDetailedModel.

  properties (GetAccess = public, SetAccess = protected)
    % The description structure holding information about the analytical
    % parametrized problem and its discretization
    descr;

  end

  properties (Dependent)
    decomp_mode;
  end

  properties(Constant)
    % this structure holds variable names that need to be defined by the
    % descr structure.
    base_checks = struct('mu_names',              {{@iscell}}, ...
                         'mu_ranges',             {{@iscell}}, ...
                         'debug',                 {{@isscalar}},...
                         'verbose',               {{@isscalar}} );
  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


  methods
    function dmbif = IDetailedModel(descr)
      % constructor
      %
      % Parameters:
      %  descr:        The underlying description of the analytical problem and
      %                its discretization.

      dmbif.descr = descr;
      if ~IDetailedModel.struct_check(descr, ...
                                      IDetailedModel.base_checks)
        error('Consistency check for IDetailedModel failed');
      end
      if ~isfield(descr, 'decomp_mode')
        dmbif.descr.decomp_mode = 0;
      end
    end

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

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

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

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

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

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

    function isequal      = eq(this, other)
    % function eq(this, other)
    % overloaded equality ('==') operator, by default comparing the #descr variables
    %
    % This can be used as ' this == other ' and returns whether the two
    % DetailedModels are identical.
    %
    % Parameters:
    %   other:   The object of type IDetailedModel to compare with
    %
    % Return values:
    %  isequal: boolean value indiciating whether ' this == other '
      ignorelist = { 'filecache_ignore_fields_in_model', 'decomp_mode', 't', ...
                     'tstep' };
      ignorelist = [ ignorelist, this.descr.mu_names ];
      if isfield(this.descr, 'filecache_ignore_fields_in_model')
        ignorelist = [ ignorelist, this.descr.filecache_ignore_fields_in_model ];
      end
      [isequal, a, b, c] = structcmp(this.descr, other.descr, ignorelist);
      if ~isequal
        disp('fields of model and stored model differs:')
        disp('differing fields:');
        cellfun(@disp,a);
        disp('additional fields in model:');
        cellfun(@disp,b);
        disp('additional fields in stored model:');
        cellfun(@disp,c);
      end
    end

    function this         = set_mu(this, mu)
      % function this = set_mu(this, mu, propagate)
      % sets the active parameter vector `\mu \in {\cal M}`
      %
      % The parameter set here, is used by the detailed_simulation() function.
      %
      % The default implementation sets all fieldnames 'descr.mu_names' in the
      % #descr struct.
      %
      % Parameters:
      %   mu: The parameter vector `\boldsymbol\mu`.
      %
      % Return values:
      %  this: handle of type IDetailedModel to the changed DetailedModel

      assert(length(mu) == length(this.descr.mu_names));

      for i = 1:length(this.descr.mu_names)
        this.descr.(this.descr.mu_names{i}) = mu(i);
      end
    end

    function mu           = get_mu(this)
      % function mu = get_mu(this)
      % returns the active parameter vector `\boldsymbol\mu \in {\cal M}`
      %
      % The default implementation returns a vector of the values of the fields
      % of the #descr structure with names 'descr.mu_names'.
      %
      % Return values:
      %   mu: The parameter vector `\boldsymbol\mu`



      mu = cellfun(@(x) this.descr.(x), this.descr.mu_names, 'UniformOutput', true);
    end
  end

  methods (Abstract)

    % function model_data = gen_model_data(this)
    % generates large model data.
    %
    % This function generates e.g. a grid, which is not to be stored in the
    % model, but required for numerics.
    %
    % Return values:
    %  model_data: Matlab structure of type ModelData storing high dimensional
    %              data needed by detailed_simulation().
    model_data   = gen_model_data(this);

    % function sim_data = detailed_simulation(this, model_data)
    % executes a detailed simulation for a given parameter
    %
    % This function computes a numerical scheme defined by the #descr for the
    % parameter set via the set_mu() method.
    %
    % Return values:
    %  sim_data:  structure holding the `H`-dimensional simulation data.
    sim_data     = detailed_simulation(this, model_data);


    % function p = plot_sim_data(dmodel, model_data, sim_data, plot_params)
    % plots the simulation data as returned by detailed_simulation()
    %
    % Parameters:
    %   sim_data:    simulation data structure as returned by detailed_simulation()
    %   plot_params: structure which controls the plot output
    %
    % Return values:
    %   p:           GUI handle to the created MATLAB figure
    p = plot_sim_data(dmodel, model_data, sim_data, plot_params);
  end

  methods (Static, Abstract)

    % function U = get_dofs_from_sim_data(sim_data)
    % extracts the `H` dimensional Dof vector from the 'sim_data' structure
    %
    % Return values:
    %  U: `H` dimensional Dof vector
    U            = get_dofs_from_sim_data(sim_data);
  end

end