IModel.m

classdef IModel < dynamicprops
  % This is the common interface for all models, detailed and reduced ones.
  %

  properties (Constant)

    % This constant can be used for a consistency check of time evolution
    % members in the ModelDescr with help of IModel.struct_check()
    time_checks = struct('t',       {{@isscalar}}, ...
                         'tstep',        {{@isscalar}}, ...
                         'nt',           {{@isscalar}}, ...
                         'dt',           {{@isscalar, ...
                         'own', @(model) model.dt == model.T/model.nt,...
                                'model.dt ~= model.T/model.nt'}} ...
                        );
  end

  properties (Access = public)
    % The number of CPUs used for parallel sessions.
    %
    % @todo: This flag should move to the FakeMPI sigleton control structure.
    num_cpus = 4;
  end

  properties (Abstract, Dependent)
    % Decomposition operation mode
    %
    % A scalar flag indicating the operation mode of functions:
    %   - 0 (complete)     : no affine parameter dependence or decomposition
    %                        is performed.
    %   - 1 (components)   : for each output argument a cell array of output
    %                        matrices is returned representing the `q`-th
    %                        component independent of the parameters given
    %                        in 'mu_names'.
    %   - 2 (coefficients) : returns a vector where each coordinate represents
    %                        the `q`-the coefficient
    %                        `\boldsymbol\sigma_{\cdot}^{q}(\boldsymbol\mu)`
    %                        dependent on the parameters given in 'mu_names'.
    %
    % This flag is only needed if the detailed model makes use of @ref datafunc
    % "affinely parameter dependent functions".
    decomp_mode;
  end

  properties (Abstract, 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 (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 a ModelDescr 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 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.
    %
    % Parameters:
    %   mu: The parameter vector `\boldsymbol\mu`.
    %
    % Return values:
    %  this: handle of type IDetailedModel to the changed DetailedModel
    this         = set_mu(this, mu);

    % function mu = get_mu(this)
    % returns the active parameter vector `\boldsymbol\mu \in {\cal M}`
    %
    % Return values:
    %   mu: The parameter vector `\boldsymbol\mu`
    mu           = get_mu(this);

  end

  methods (Static, Hidden)

    function ok  = struct_check(descr, checks)
    % function ok  = struct_check(descr, checks)
    % executes checks on the fields of a structure object
    %
    % This function can be used to check whether the structure 'descr' fulfills
    % some constraints defined by the second argument 'checks'
    %
    % The following checks can be executed:
    %   - 'def(fn)':                    Checks whether a field 'fn'
    %                                   exists and is set to a non-empty value.
    %   - 'type(fn, typecheck)':        Checks whether the field 'fn' fullfils
    %                                   a typecheck defined by a function
    %                                   'isokay = typecheck(X)' Useful choices
    %                                   for 'typecheck' are e.g. <tt> @@isscalar,
    %                                   @@iscell,  @@isstruct </tt>
    %   - 'values(fn, candidates)':     Checks whether the field 'fn' is set to
    %                                   one of the values given by the cell
    %                                   array of strings 'candidates'
    %   - 'minmax(fn, range)':          Checks whether the field 'fn' is set to
    %                                   a value in a given range 'range', which
    %                                   is a 2-dimensional vector.
    %   - 'own(fn, usr_check, msg)':    Checks whether the field 'fn' is set to
    %                                   a value that fulfills a user-defined
    %                                   check 'isokay = usr_check(descr)'. If
    %                                   it fails, a message 'msg' is printed
    %                                   for explanation.
    %
    % Parameters:
    %   descr:   The structure to be checked.
    %   checks:  A structure defining which of the above described checks shall
    %            be executed.
    %            - All fieldnames 'fn' of this structure are used for
    %              definition checks 'def(fn)'.
    %            - The field values must be set to a cell array whose first
    %              element is set to a function pointer 'typecheck' used for a
    %              mandatory check 'type(fn, typecheck)'.
    %            - The following fields of the cell array are strings defining
    %              a check followed by an optional and fixed number of
    %              arguments for this check. Possible command strings are:
    %              - 'values' followed by one argument 'candidates' executing
    %                the check 'values(fn, candidates)'.
    %              - 'minmax' followed by one argument 'range' executing the
    %                check 'minmax(fn, range)'.
    %              - 'own' followed by two arguments 'usr_check' and 'msg'
    %                executing the check 'own(fn, usr_check, msg)'.
    %              .
    %            .
    %
    % Return values:
    %   ok:    boolean flag indicating whether all checks passed.
      ok = true;
      fns = fieldnames(checks);
      for i = 1:length(fns)
        % definition checks
        if ~isfield(descr, fns{i})
          disp(['Field ', fns{i}, ' is not defined in descr.']);
          ok = false;

        elseif isempty(descr.(fns{i}))
          disp(['Field ', fns{i}, ' is empty!']);
          ok = false;
        else
          mval = descr.(fns{i});
          % further checks:
          checkdef = checks.(fns{i});
          % 1. type check:
          if length(checkdef) > 1 && ~isempty(checkdef{1}) && ~checkdef{1}(mval)
            disp(['Field ', fns{i}, ' failed the type check ', func2str(checkdef{1}), '.']);
            ok = false;
          end

          cdi = 2;
          while cdi <= length(checkdef) && ok
            switch(checkdef{cdi})
              case 'values'
                values = checkdef{cdi+1};
                if isempty(intersect(mval, values))
                  disp(['Field ', fns{i}, ' needs to be one of:']);
                  if ~iscell(values)
                    celldisp(values, 'values');
                  else
                    fprintf('%s ', values{:});
                  end
                  ok = false;
                end
                cdi = cdi + 2;
              case 'minmax'
                range = checkdef{cdi+1};
                if mval < range(1) || mval > range(2)
                  disp(['Field ', fns{i}, ' does not lie in range ', num2str(range), '.']);
                  ok = false;
                end
                cdi = cdi + 2;
              case 'own'
                testfun = checkdef{cdi+1};
                message = checkdef{cdi+2};
                if ~testfun(descr)
                  disp(['Field ', fns{i}, ' failed a consistency check:']);
                  disp(message);
                  ok = false;
                end
                cdi = cdi + 3;
            end
          end
        end
      end
    end
  end
end