DetailedData.m

classdef DetailedData < Greedy.User.IDetailedData
  % class generating the reduced basis space for the LinEvol problem with a
  % Greedy algorithm.
  %
  % Parameters given by the constructor argument 'bg_descr' of type
  % BasisGenDescr can control the
  %   - trainings sample (#train_sample_mode, #train_num_intervals, #train_seed)
  %   - trainings sample refinement (#refinement_mode, #max_refinement_level,
  %                      #refinement_theta, #val_size, #val_seed, #stop_max_val_train_ratio)
  %   - the error indicator (#indicator_mode)
  %   - greedy variant selection by #Mmax_small
  %     - PODEI-greedy ('Mmax_small > 0'): #small_train_num_intervals,
  %                                        #epsilon_M_by_N_r,
  %                                        #maximum_temporary_error_growth_factor,
  %                                        #ei_minimum_residual,
  %                                        #extension_M_by_N_r,
  %                                        #ei_epsilon_small
  %     - subsequent generation of EI by EI-greedy and RB by POD-greedy. ('Mmax_small == 0')
  %     .
  %   - general EI extension controls (#noof_ei_extensions) and
  %   - general greedy controls (#stop_Nmax, #stop_Mmax, #stop_timeout,
  %                              #stop_epsilon, #stop_max_val_train_ratio)

  properties (Dependent, SetAccess=private)
    % a basis generation algorithm of type Greedy.Interface used to generated
    % the reduced basis space.
    bg_algorithm;
  end

  properties (Access=private)
    rb_generator;

    ei_generators = {};
  end

  properties
    % flag indicating whether the parameter sampling for the training set
    % `M_{\text{train}}` type.
    %
    % Possible values:
    %   - 'uniform': (default) for a ParameterSampling.Uniform
    %   - 'random':  for a ParameterSampling.Random
    train_sample_mode        = 'uniform';

    % number of intervals in the ParameterSampling.Uniform respectively number
    % of vectors in the ParameterSampling.Random for the training set
    % `M_{\text{train}}` of the parameter space `{\cal M}`.
    train_num_intervals      = 3;

    % If 'train_sample_mode == random',  a ParameterSampling.Random is generated
    % for the training set `M_{\text{val}}` with size #train_num_intervals and
    % seed 'train_seed'.
    train_seed               = 4321;

    % sets the Greedy.TrainingSetAdaptation.refinement_mode option
    %
    % Possible values are:
    %  - 'uniform': the parameter sampling is refined uniformly
    %  - 'adaptive': the parameter sampling is refined adaptively, such that
    %                only regions of the parameter space with high estimated
    %                errors are refined.
    %  - 'none':     no Greedy.TrainingSetAdaptation object is created
    refinement_mode          = 'adaptive';

    % sets the Greedy.TrainingSetAdaptation.max_refinement_level option
    %
    % @copydetails Greedy.TrainingSetAdaptation.max_refinement_level
    max_refinement_level     = 5;

    % sets the Greedy.TrainingSetAdaptation.refinement_theta option
    %
    % @copydetails Greedy.TrainingSetAdaptation.refinement_theta
    refinement_theta         = 0.2;

    % If this value is non-zero, a ParameterSampling.Random is generated for the
    % validation set `M_{\text{val}}` with size #val_size and seed #val_seed.
    val_size                 = 10;

    % If the value of 'val_size' is non-zero,  a ParameterSampling.Random is
    % generated for the validation set `M_{\text{val}}` with size #val_size
    % and seed 'val_seed'.
    val_seed                 = 1234;

    % number of intervals in the ParameterSampling.Uniform for the @em small
    % training set `M_{\text{small}}` for the generation of an initial
    % collateral reduced basis space.
    %
    % See #Mmax_small for details.
    small_train_num_intervals = 2;

    % sets the Greedy.Plugin.PODEI.Mmax_small member
    %
    % In order to use the estimator of a nonlinear evolution equation for a
    % basis extension with a greedy search in the parameter space, a collateral
    % reduced basis space for all existing operators needs to be present. For
    % this reason at the beginning of the basis generation algorithm, a
    % collateral reduced bases of size at most #Mmax_small is generated
    %
    % It uses an an Greedy.Plugin.EI instance with training set of size
    % #small_train_num_intervals as extension algorithm for a
    % Greedy.Algorithm instance. The Greedy.Algorithm.stop_epsilon
    % limit is set to #ei_epsilon_small.
    %
    % If #Mmax_small is equal to '0', the initial collateral reduced bases are
    % generated with stopping parameters #stop_Mmax and #stop_epsilon '*'
    % #epsilon_M_by_N_r, and the PODGreedyAlgorithm afterwards only extends the
    % reduced basis space.
    Mmax_small                = 10;

    % ratio between the stop epsilon criterion for collateral reduced basis
    % spaces and reduced basis spaces.
    %
    % This option is only used in case 'Mmax_small == 0'. See #Mmax_small for
    % details.
    %
    % Its purpose is to make the collateral reduced basis space more refined
    % than the reduced basis space. This is necessary as the best possible
    % error for the basis generation of the reduced basis space @em depends on
    % the quality of the collateral reduced basis space.
    epsilon_M_by_N_r          = 1e-4;

    % maximum factor between the current maximum indicator and the smallest
    % maximum error indicator during previous extensions
    %
    % See Greedy.Plugin.PODEI.indicate_bad_basis_extension() for details.
    maximum_temporary_error_growth_factor = 0;

    % sets the GreedyPlugin.EI.minimum_residual
    %
    % This option is only used in case 'Mmax_small > 0'. See #Mmax_small for
    % details.
    ei_minimum_residual       = 1e-8;

    % sets the Greedy.Plugin.PODEI.M_by_N_ratio
    %
    % This option is only used in case 'Mmax_small > 0'. See #Mmax_small for
    % details.
    extension_M_by_N_r        = 4;

    % maximum error between operator interpolations at which the initial value
    % greedy is stopped.
    %
    % See #Mmax_small for details.
    ei_epsilon_small          = 1e-2;

    % sets the Greedy.Plugin.EI.stop_Mmax option
    stop_Mmax                 = 200;

    % sets the Greedy.Plugin.PODEI.stop_Nmax option
    stop_Nmax                 = 50;

    % @copybrief Greedy.Plugin.PODEI.indicator_mode
    indicator_mode            = 'estimator';

    % sets the Greedy.Algorithm.stop_epsilon option
    stop_epsilon              = 1e-5;

    % sets the Greedy.Algorithm.stop_max_val_train_ratio option
    stop_max_val_train_ratio  = 1.2;

    % sets the Greedy.Algorithm.stop_timeout option
    stop_timeout              = 12*60*60;

    % sets the number of ei extensions
    %
    % See Greedy.Plugin.EI.noof_ei_extensions for details.
    noof_ei_extensions       = 1;
  end

  methods
    function dd = DetailedData(rmodel, model_data)
      % function dd = DetailedData(rmodel, model_data)
      % constructor constructing the reduced basis spaces and storing it in a
      % DataTree.
      %
      % Parameters:
      %   rmodel: of type LinEvol.ReducedModel

      dd              = dd@Greedy.User.IDetailedData(rmodel.bg_descr, model_data);

      dd.rb_generator = SnapshotsGenerator.Trajectories(rmodel.detailed_model);

      dmodel = rmodel.detailed_model;

      opstrings      = cellfun(@func2str, dmodel.descr.ei_space_operators, 'UniformOutput', false);
      opcandidates(1).id = 'implicit';
      opcandidates(1).op = dmodel.descr.L_I_local_ptr;
      opcandidates(2).id = 'explicit';
      opcandidates(2).op = dmodel.descr.L_E_local_ptr;

      for i = 1:length(opcandidates)

        if ~isempty(intersect(opstrings, func2str(opcandidates(i).op)))
          ei_generator = SnapshotsGenerator.SpaceOpEvals(dmodel, opcandidates(i).id, dd.rb_generator, opcandidates(i).op);
          dd.ei_generators = [ dd.ei_generators, ei_generator  ];
        end
      end

      dd.datatree     = gen_detailed_data(dd.bg_algorithm, rmodel, model_data);
    end

  end

  methods

    function basis_gen = get.bg_algorithm(this)
      % generates a default @ref Greedy.Interface "basis generation object" for
      % linear evolution problems as given by a DetailedModel.
      %
      % This function generates a Greedy.Interface implementation, with either
      % a subsequent generation of empirical interpolation bases spaces for all
      % operators and a reduced basis space afterwards, @b or a combined
      % generation of all reduced spaces with the GreedyPlugin.PODEI variant
      % of the GreedyAlgorithm.
      %

      if isequal(this.train_sample_mode, 'uniform')
        M_train = ParameterSampling.Uniform(this.train_num_intervals);
      elseif isequal(this.train_sample_mode, 'random')
        M_train = ParameterSampling.Random(this.train_num_intervals, this.train_seed);
      else
        error('unknown train_sample_mode');
      end
      if this.val_size > 0
        M_val = ParameterSampling.Random(this.val_size, this.val_seed);
      else
        M_val = [];
      end

      rb_ext                = Greedy.Plugin.POD(this.rb_generator);
      rb_ext.indicator_mode = this.indicator_mode;
      rb_ext.stop_Nmax      = this.stop_Nmax;

      ei_ext_array = cell(1, length(this.ei_generators));
      for i = 1:length(this.ei_generators)
        ei_ext_array{i} = Greedy.Plugin.EI(this.ei_generators(i));
      end
      if length(ei_ext_array) > 1
        ei_ext                = [ ei_ext_array{:} ];
      else
        ei_ext                = ei_ext_array{1};
      end

      ei_ext.stop_Mmax       = this.stop_Mmax;

      ei_ext.noof_extensions = this.noof_ei_extensions;



      if this.Mmax_small > 0

        ei_ext.minimum_residual = this.ei_minimum_residual;

        M_train_small                = ParameterSampling.Uniform(this.small_train_num_intervals);
        ei_greedy_small              = Greedy.Algorithm(ei_ext, M_train_small);
        ei_greedy_small.stop_epsilon = this.ei_epsilon_small;

        all_ext                                       = Greedy.Plugin.PODEI(rb_ext, ei_ext, ei_greedy_small, this.Mmax_small);
        all_ext.M_by_N_ratio                          = this.extension_M_by_N_r;
        all_ext.maximum_temporary_error_growth_factor = this.maximum_temporary_error_growth_factor;

        if this.extension_M_by_N_r > 0
          all_ext.skip_rb_after_bad_extension         = false;
          all_ext.discard_last_rb_after_bad_extension = false;
          all_ext.skip_ei_after_bad_extension         = false;
        end

        pod_greedy             = Greedy.Algorithm(all_ext, M_train, M_val);

        pod_greedy.val_train_ratio_seq_for_break = 2;
      else
        ei_greedy              = Greedy.Algorithm(ei_ext, M_train);
        ei_greedy.stop_epsilon = this.stop_epsilon * this.epsilon_M_by_N_r;

        pod_greedy             = Greedy.Algorithm(rb_ext, M_train, M_val);

        pod_greedy.val_train_ratio_seq_for_break = 1;
      end

      pod_greedy.stop_epsilon             = this.stop_epsilon;
      pod_greedy.stop_max_val_train_ratio = this.stop_max_val_train_ratio;
      pod_greedy.stop_timeout             = this.stop_timeout;

      if isa(M_train, 'ParameterSampling.IRefineable')

        if ~isequal(this.refinement_mode, 'none')
          pod_greedy                      = Greedy.TrainingSetAdaptation(pod_greedy);
          pod_greedy.refinement_mode      = this.refinement_mode;
          pod_greedy.max_refinement_level = this.max_refinement_level;
        end

        if isequal(this.refinement_mode, 'adaptive')
          pod_greedy.refinement_theta = this.refinement_theta;
        end

      end

      if this.Mmax_small > 0
        basis_gen = pod_greedy;
      else
        basis_gen = [ei_greedy, pod_greedy];
      end

    end

    function rb_size = get_rb_size(this, rmodel)
      leaf_dd = get_leaf(this, rmodel);
      rb_size = get_rb_size(leaf_dd);
    end

  end
end