2 % This is the
interface for a reduced model providing methods to compute low
3 % dimensional reduced simulations based on a priori generated reduced basis
6 % An
IReducedModel implementation is the
final puzzle piece in the reduced
7 % basis framework as described the section on the @ref rbm_interface
"main
10 % Note, that
this interface implements an
IDetailedModel interface, by
11 % forwarding all methods to the underlying #detailed_model. By
this, the
12 % reduced model is the only needed. This is again
for historic reasons
13 % assuring compatibility with old codes which did not distinguish between
14 % reduced and detailed models.
16 % Usually a reduced model
'r_model' is used in the following way and order:
17 % -# Generate detailed data
18 % @code reduced_data = gen_detailed_data(r_model, model_data)
@endcode
19 % -# Generate reduced data
20 % @code reduced_data = gen_reduced_data(r_model, detailed_data) @endcode
21 % -# (Optionally) extract a subset from this reduced_data
22 % @code reduced_data = extract_reduced_data_subset(r_model, reduced_data) @endcode
23 % -# Compute one or more reduced simulations by
24 % -# Setting the active parameter
25 % @code set_mu(r_model, mu) @endcode
27 % -# executing the simulation
28 % @code rb_sim_data = rb_simulation(r_model, reduced_data) @endcode
29 % -# Optionally reconstruct the reduced simulation snapshots
30 % `u_{\text{red}}(\cdot; t^k, \mu) \in {\cal W}_{\text{red}}`
31 % @code rb_sim_data = rb_reconstruction(r_model, detailed_data, rb_sim_data)
@endcode
34 properties(Dependent, SetAccess =
private)
39 properties (Dependent)
43 properties (SetAccess = private, Dependent)
44 % cell array of strings describing the parameters of the model
47 % cell array of vectors of size two defining the allowed interval range for
48 % the parameter components
51 % an integer defining the verbosity level of information output during
55 % an integer defining the debugging level controlling error output and
56 % extra tests during basis generation
61 % flag indicating whether this model depends on collateral reduced basis
68 % a structure of type
BasisGenDescr defining the basis generation routines
69 % and data structures.
74 %
boolean flag indicating whether during an rb_simulation() an a posteriori
75 % error estimator shall be computed.
77 % This flag needs to be set to 'true' for certain Basis generation
79 enable_error_estimator;
83 % control variable for the size of the reduced basis used for reduced
84 % simulations. By default this is equal to the size of the generated
88 % control variable for the size of the (collateral) reduced basis used for
89 % empirical interpolations. By default this is equal to the size of the
90 % generated reduced basis.
93 % control variable for the number of (collateral) reduced basis vectors
94 % used for error estimation. By default this is equal to zero.
100 % Constructor of a reduced model
103 % dmodel: the
object of type
IDetailedModel for which the reduced model
104 % shall be constructed.
105 if nargin == 1 || isempty(bg_descr)
107 % check if the first argument is an
IReducedModel -> copy constructor
110 m = metaclass(dmodel);
111 fns = m.Properties(cellfun(@(x) ~isequal(x.SetAccess, 'none') && ~x.Dependent, m.Properties));
112 fns = cellfun(@(x) x.Name, fns, 'UniformOutput', false);
114 rmif.(fns{i}) = copy.(fns{i});
117 error(
'IReducedModel copy constructor needs to get only one argument');
120 rmif.detailed_model = dmodel;
121 rmif.bg_descr = bg_descr;
124 'reduced_data_constructor', {{@(x) isequal(
class(x),
'function_handle')}}, ...
125 'detailed_data_constructor', {{@(x) isequal(
class(x),
'function_handle')}}...
128 error(
'Consistency check for IReducedModel failed');
131 error(
'IReducedModel constructor needs to get two arguments');
135 function descr =
get.descr(
this)
136 descr = this.detailed_model.descr;
139 function mu_ranges =
get.mu_ranges(
this)
140 mu_ranges = this.detailed_model.descr.mu_ranges;
143 function mu_names =
get.mu_names(
this)
144 mu_names = this.detailed_model.descr.mu_names;
147 function decomp_mode =
get.decomp_mode(
this)
148 decomp_mode = this.detailed_model.descr.decomp_mode;
151 function set.decomp_mode(
this, decomp_mode)
152 this.detailed_model.decomp_mode = decomp_mode;
155 function debug =
get.debug(
this)
156 debug = this.detailed_model.descr.debug;
160 verbose = this.detailed_model.descr.verbose;
163 function iseq = eq(
this, other)
164 %
function iseq = eq(
this, other)
165 % Comparison
operator checking whether the underlying #detailed_model
166 % members of
'this' and
'other' are equal.
169 % other: an
object of type
IReducedModel we want to compare with.
172 % iseq: a
boolean value indicating whether
'this' and
'other' are
174 iseq = (this.detailed_model == other.detailed_model);
177 function reduced_data = gen_reduced_data(
this, detailed_data)
178 %
function reduced_data = gen_reduced_data(
this, detailed_data);
179 % Constructs the
'reduced_data' object holding low dimensional data needed
180 %
for efficient reduced simulations with rb_simulation().
183 % reduced_data: reduced data
object of type
IReducedData.
185 reduced_data = this.bg_descr.reduced_data_constructor(
this, detailed_data);
188 function reduced_data_subset = extract_reduced_data_subset(
this, reduced_data)
189 %
function reduced_data = extract_reduced_data_subset(
this, reduced_data);
190 % Extracts a subset of the
'reduced_data' generated by gen_reduced_data().
193 % reduced_data:
object of type
IReducedData holding a subset of the
194 % reduced data fields as they were generated by
195 % gen_reduced_data().
197 if isa(reduced_data,
'IDetailedData')
198 reduced_data_subset = gen_reduced_data(this, reduced_data);
200 reduced_data_subset = extract_reduced_data_subset(reduced_data, this);
208 % function rb_sim_data = rb_simulation(this, reduced_data);
209 % Executes a reduced simulation and optionally an error estimation.
212 % rb_sim_data: structure holding the coefficient vectors of the reduced
213 % simulations and optional error estimators.
214 rb_sim_data = rb_simulation(this, reduced_data);
216 % function rb_sim_data = rb_reconstruction(this, detailed_data, rb_sim_data);
217 % reconstructs the reduced simulation snapshots generated by
218 % rb_simulation() in the reduced space `{\cal W}_{\text{red}}`.
220 % Possible implementations are:
224 % rb_sim_data: struct holding reduced simulation data returned by
225 % IReducedModel.rb_simulation() .
228 % rb_sim_data: struct holding the reduced simulation results and their
230 rb_sim_data = rb_reconstruction(this, detailed_data, rb_sim_data);
232 %
function c = copy(
this);
233 %
function that deep copies
this handle
class
235 % The suggested implementation in the implementation
class should call a
236 % copy constructor which might look as follows:
242 %
if ~isa(detailed_model,
'Implementation.ReducedModel')
248 % c: an
object of type
IReducedModel which is a deep copy of
this object.
252 methods(Static, Abstract)
253 % TODO: Andreas Schmidt, WHY IS THIS NECESSRY IN A GENERIC INTERFACE???
255 %
function Delta = get_estimators_from_sim_data(sim_data);
256 % Static helper method returning the vectors of error estimators
for each
257 % reduced simulation snapshot `u_{\text{red}}(\cdot, t^k)` generated by
261 % rb_sim_data:
struct holding reduced simulation data returned by
265 % Delta: This is a
'(K+1) x 1' vector of estimates `\eta^k(\mu)`
266 % Delta = get_estimators_from_sim_data(rb_sim_data);
268 %
function Delta = get_estimator_from_sim_data(sim_data);
269 % Static helper method returning an error estimator
for the whole
270 % reduced trajectory `\{u_{\text{red}}(\cdot, t^k)\}_{k=0}^{K}` generated
271 % by rb_simulation().
274 % rb_sim_data:
struct holding reduced simulation data returned by
278 % Delta: This is a scalar computed from the estimates `\eta^k(\mu)`.
279 % Usually the maximum over `k=0,\ldots,K` is returned.
280 Delta = get_estimator_from_sim_data(rb_sim_data);
286 function U = get_dofs_from_sim_data(rmodel, sim_data)
287 %
function U = get_dofs_from_sim_data(sim_data)
291 U = rmodel.detailed_model.get_dofs_from_sim_data(sim_data);
297 function detailed_data = gen_detailed_data(this, model_data)
298 % function detailed_data = gen_detailed_data(this, model_data)
299 % initiates the reduced basis generation process
301 % This function calls the
IDetailedData constructor specified by
302 % 'bg_descr.detailed_data_constructor' and returns the generated detailed
306 % detailed_data: constructed detailed data
object of type
309 detailed_data = this.bg_descr.detailed_data_constructor(this, model_data);
312 function p =
plot_sim_data(rmodel, model_data, sim_data, plot_params)
316 % This method actually calls the '
plot_sim_data()' method on the
317 %
#detailed_model member.
319 p =
plot_sim_data(rmodel.detailed_model, model_data, sim_data, plot_params);
322 function model_data = gen_model_data(this)
325 % This function call is forwarded to the underlying
#detailed_model.
328 model_data = gen_model_data(this.detailed_model);
331 function sim_data = detailed_simulation(
this, model_data)
334 % This
function call is forwarded to the underlying #detailed_model.
337 % sim_data: structure holding the detailed simulation result.
338 sim_data = detailed_simulation(this.detailed_model, model_data);
341 function this = set_mu(
this, mu)
342 %
function this = set_mu(
this, mu)
343 % Sets the active parameter vector `\mu \in {\cal M}` used
for simulations
346 % The parameter set here, is also used by the rb_simulation() function.
347 % So, the
#detailed_model and the reduced model's internal parameter
351 % mu: The parameter vector `\mu`.
356 this.detailed_model = set_mu(this.detailed_model, mu);
360 function mu = get_mu(
this)
361 %
function mu = get_mu(
this)
362 % returns the active parameter vector `\mu \in { \cal M }`
365 % mu: The parameter vector `\mu`
366 mu = get_mu(this.detailed_model);
369 function rb_size = get_rb_size(
this, detailed_data)
370 %
function rb_size = get_rb_size(
this, detailed_data)
371 % returns the size of the generated reduced basis by the
374 % This method only forwards the call to the
376 % necessary
for compatibility with the old interface...
377 rb_size = get_rb_size(detailed_data);
380 function couple_N_and_M(
this, detailed_data, ratio, factor)
381 %
function couple_N_and_M(
this, detailed_data, ratio, factor)
382 % sets all the basis sizes
for reduced simulations by a ratio with
383 % respect to the maximum possible basis size and a factor between RB and
387 % ``(N, M^{L_1}, \dots, M^{L_q})
388 % = \left(\lfloor r N_{\max} \rfloor, \lfloor r_M M_{\max}^{
'L_1} \rfloor,
389 % \dots, \lfloor r_M M_{\max}^{'L_q} \rfloor\right),``
390 % where `r_M = \min\{ rf, 1 \}` and `M_{\max}^{
'L} == M_{\max}^L - M'`.
393 % ratio: an integer from the interval `[0, 1]` specifying the ratio `r`
394 % by which the number of collateral reduced basis functions
395 % shall be reduced with respect to the maximum possible.
396 % factor: an (optional) positive factor `f` between RB and EI basis
397 % sizes. (default = 1)
399 assert(ratio >= 0 && ratio <= 1.0);
406 Nmax = get_rb_size(detailed_data);
407 this.N = floor(Nmax * ratio);
408 set_Mratio(this, detailed_data, min(ratio*factor,1));
411 function this = set_Mratio(this, detailed_data, ratio)
412 % function set_Mratio(this, detailed_data, ratio)
413 % in case of multiple operators subject to empirical interpolation, this
414 % sets number of reduced basis functions used for reduced simulations by
415 % specifying a ratio.
418 % ``M^{L} = \lfloor M_{\max}^{
'L} \cdot \text{ratio} \rfloor``
419 % for all operators/functions `L`, where `M_{\max}^{'L} == M_{\max}^L - M'`.
422 % ratio: an integer from the interval `[0, 1]` specifying the ratio by
423 % which the number of collateral reduced basis functions shall
424 % be reduced with respect to the maximum possible.
425 assert(ratio <= 1 && ratio >= 0);
426 Mmax = get_ei_size(detailed_data.datatree);
427 if isa(Mmax,
'DataTree.IdMapNode')
428 for i = 1:length(Mmax)
429 set(this.M,i,floor((get(Mmax,i)-this.Mstrich) * ratio));
432 this.M = floor((Mmax-this.Mstrich) * ratio);
436 function Mratio = get_Mratio(this, detailed_data)
437 % function Mratio = get_Mratio(this, detailed_data)
438 % in case of multiple operators subject to empirical interpolation, this
439 % gets the mean of ratio between the number of reduced basis functions
440 % used for reduced simulations and the maximum possible.
442 % This function gets the mean of
443 % `\frac{M^{L}}{M_{\max}^{L}}` over
for all operators/functions `L`.
446 % Mratio: an integer from the interval `[0, 1]` specifying the ratio by
447 % which the number of collateral reduced basis functions is
448 % reduced with respect to the maximum possible.
450 if isa(M,
'DataTree.IdMapNode')
451 M = scalar(M, @(x) mean([x{:}]));
453 Mmax = get_ei_size(detailed_data.datatree);
454 if isa(Mmax,
'DataTree.IdMapNode')
455 Mmax = scalar(Mmax, @(x) mean([x{:}]));
463 function varargout = subsref(this, S)
464 % function ret = subsref(this, S)
465 % forwarding of fieldnames access to the underlying detailed_model description
467 % If the user calls 'r_model.parameter' and the field 'parameter' exists
468 % in the underlying model, the value of 'detailed_model.descr.parameter' is
469 % returned. This method is implemented for compatibility reasons, such that
470 % a basis generation
object can be used like an old model. Try to prevent
471 % usage of this method in the future.
473 % @note that this method throws a 'RBmatlab:Compatibility' warning if a
474 % description field is accessed.
475 ddescr = this.detailed_model.descr;
476 thissubs = [properties(this); methods(this)];
477 fns = setdiff(fieldnames(ddescr), thissubs);
479 if S(1).type(1) == '.' ...
480 && ~isempty(intersect(fns, S(1).subs))
481 warning('RBmatlab:Compatibility', ...
482 ['Requesting the reduced_model field ''', S(1).subs, ...
484 'substitute the ''rmodel'' by a ''rmodel.detailed_model''']);
485 [varargout{1:nargout}] = this.descr.(S(1).subs);
488 [varargout{1:nargout}] = builtin(
'subsref',
this, S);
490 varargout = {builtin(
'subsref',
this, S)};
static function U = get_dofs_from_sim_data(sim_data)
extracts the dimensional Dof vector from the sim_data structure
function r = verbose(level, message, messageId)
This function displays messages depending on a message-id and/or a level. Aditionally you can set/res...
virtual function rb_size = get_rb_size(IReducedModel rmodel)
returns the dimension of the stored reduced basis space.
function rb_sim_data = rb_reconstruction_default(model, detailed_data, rb_sim_data)
(trivial) function computing a detailed reconstruction by linear combination of the coefficients in t...
This is the common interface for all models, detailed and reduced ones.
virtual function p = plot_sim_data(model_data, sim_data, plot_params)
plots the simulation data as returned by detailed_simulation()
virtual function sim_data = detailed_simulation(model_data)
executes a detailed simulation for a given parameter
static function ok = struct_check(descr, checks)
executes checks on the fields of a structure object
Struct with control fields for the reduced basis generation.
descr
The description structure holding information about the analytical parametrized problem and its discr...
This is the interface for a reduced model providing methods to compute low dimensional reduced simula...
virtual function rb_sim_data = rb_simulation(reduced_data)
Executes a reduced simulation and optionally an error estimation.
This is the interface for a detailed model providing methods to compute high dimensional simulation s...
function p = plot_sim_data(model, model_data, sim_data, plot_params)
function performing the plot of the simulation results as specified in model.
Interface class for the generation and storage of offline matrices and vectors as described in Module...
Interface class for the generation and storage of reduced basis spaces as described in Module (M2)...