Detailed Description

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 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
reduced_data = gen_detailed_data(r_model, model_data)
Generate reduced data
reduced_data = gen_reduced_data(r_model, detailed_data)
(Optionally) extract a subset from this reduced_data
reduced_data = extract_reduced_data_subset(r_model, reduced_data)
Compute one or more reduced simulations by
1. Setting the active parameter
  set_mu(r_model, mu)
  
  and
2. executing the simulation
  rb_sim_data = rb_simulation(r_model, reduced_data)
Optionally reconstruct the reduced simulation snapshots \(u_{\text{red}}(\cdot; t^k, \mu) \in {\cal W}_{\text{red}}\)
rb_sim_data = rb_reconstruction(r_model, detailed_data, rb_sim_data)

Definition at line 17 of file IReducedModel.m.

Inheritance diagram for IReducedModel:

[legend]

Collaboration diagram for IReducedModel:

[legend]

Public Member Functions
	IReducedModel (IDetailedModel dmodel, bg_descr)
	Constructor of a reduced model.

function iseq =	eq (IReducedModel other)
	Comparison operator checking whether the underlying detailed_model members of `this` and `other` are equal.

function IReducedData reduced_data =	gen_reduced_data (detailed_data)
	Constructs the `reduced_data` object holding low dimensional data needed for efficient reduced simulations with rb_simulation().

function reduced_data_subset =	extract_reduced_data_subset (IReducedData reduced_data)
	Extracts a subset of the `reduced_data` generated by gen_reduced_data().

virtual function rb_sim_data =	rb_simulation (reduced_data)
	Executes a reduced simulation and optionally an error estimation.

virtual function rb_sim_data =	rb_reconstruction (detailed_data, rb_sim_data)
	reconstructs the reduced simulation snapshots generated by rb_simulation() in the reduced space \({\cal W}_{\text{red}}\).

virtual function IReducedModel c =	copy ()
	function that deep copies this handle class

function U =	get_dofs_from_sim_data (sim_data)
	extracts the \(H\) dimensional Dof vector from the `sim_data` structure

function IDetailedData detailed_data =	gen_detailed_data (model_data)
	initiates the reduced basis generation process

function p =	plot_sim_data (model_data, sim_data, plot_params)
	plots the simulation data as returned by detailed_simulation()

function model_data =	gen_model_data ()
	generates large model data.

function sim_data =	detailed_simulation (model_data)
	executes a detailed simulation for a given parameter

function this =	set_mu (mu)
	Sets the active parameter vector \(\mu \in {\cal M}\) used for simulations on this model.

function mu =	get_mu ()
	returns the active parameter vector \(\mu \in { \cal M }\)

function rb_size =	get_rb_size (detailed_data)
	returns the size of the generated reduced basis by the IDetailedData class.

function	couple_N_and_M (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.

function this =	set_Mratio (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.

function Mratio =	get_Mratio (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.

function ret =	subsref (S)
	forwarding of fieldnames access to the underlying detailed_model description

Static Public Member Functions
static function Delta =	get_estimators_from_sim_data (rb_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().

static function Delta =	get_estimator_from_sim_data (rb_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().

Static Public Member Functions inherited from IModel
static function ok =	struct_check (descr, checks)
	executes checks on the fields of a structure object

Public Attributes
	descr
	The description structure holding information about the analytical parametrized problem and its discretization.

	decomp_mode

	mu_names
	cell array of strings describing the parameters of the model

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

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

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

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

::IDetailedModel	detailed_model
	an object which shall be reduced

::BasisGenDescr	bg_descr
	a structure defining the basis generation routines and data structures.

	enable_error_estimator
	boolean flag indicating whether during an rb_simulation() an a posteriori error estimator shall be computed.

	N = 0
	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.

	M = 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.

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

Public Attributes inherited from IModel
	num_cpus = 4
	The number of CPUs used for parallel sessions.

	decomp_mode
	Decomposition operation mode.

	mu_names
	cell array of strings describing the parameters of the model

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

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

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

Additional Inherited Members
Static Public Attributes inherited from IModel
static const	time_checks
	This constant can be used for a consistency check of time evolution members in the ModelDescr with help of IModel.struct_check()

Constructor & Destructor Documentation

IReducedModel.IReducedModel	(	IDetailedModel	dmodel,
			bg_descr
	)

Constructor of a reduced model.

Parameters

dmodel	the object for which the reduced model shall be constructed.
bg_descr	bg descr

Definition at line 210 of file IReducedModel.m.

Member Function Documentation

function IReducedModel c = IReducedModel.copy ( )

pure virtual

function that deep copies this handle class

The suggested implementation in the implementation class should call a copy constructor which might look as follows:

// 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

Return values

c	an object which is a deep copy of this object.

Implemented in NonlinEvol.ReducedModel, LinStatDune.ReducedModel, LinEvolDune.ReducedModel, LinEvol.ReducedModel, Test.ReducedModel, TwoPhaseFlow.ReducedModel, and LinStat.ReducedModel.

function IReducedModel.couple_N_and_M	(	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

detailed_data	detailed data
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)

Definition at line 595 of file IReducedModel.m.

function sim_data = IReducedModel.detailed_simulation ( model_data )

virtual

executes a detailed simulation for a given parameter

This function call is forwarded to the underlying detailed_model.

Parameters

model_data model data

Return values

sim_data structure holding the detailed simulation result.

Implements IModel.

Definition at line 525 of file IReducedModel.m.

function iseq = IReducedModel.eq ( IReducedModel other )

Comparison operator checking whether the underlying detailed_model members of this and other are equal.

Parameters

other an object we want to compare with.

Return values

iseq	a boolean value indicating whether `this` and `other` are equal.

Required fields of other:

detailed_model — detailed model

Definition at line 313 of file IReducedModel.m.

function reduced_data_subset = IReducedModel.extract_reduced_data_subset ( IReducedData reduced_data )

Extracts a subset of the reduced_data generated by gen_reduced_data().

Parameters

reduced_data reduced data

Return values

reduced_data_subset	reduced data subset
reduced_data	object holding a subset of the reduced data fields as they were generated by gen_reduced_data().

Definition at line 347 of file IReducedModel.m.

function IDetailedData detailed_data = IReducedModel.gen_detailed_data ( 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..

Parameters

model_data model data

Return values

detailed_data constructed detailed data object

Definition at line 475 of file IReducedModel.m.

function model_data = IReducedModel.gen_model_data ( )

virtual

generates large model data.

This function call is forwarded to the underlying detailed_model.

Return values

model_data model data

Implements IModel.

Definition at line 509 of file IReducedModel.m.

function IReducedData reduced_data = IReducedModel.gen_reduced_data ( detailed_data )

Constructs the reduced_data object holding low dimensional data needed for efficient reduced simulations with rb_simulation().

Parameters

detailed_data detailed data

Return values

reduced_data reduced data object

Definition at line 331 of file IReducedModel.m.

function U = IReducedModel.get_dofs_from_sim_data ( sim_data )

extracts the \(H\) dimensional Dof vector from the sim_data structure

Parameters

sim_data matlab struct with simulation data generated e.g. by detailed_simulation() or rb_reconstruction() methods.

Return values

U	\(H\) dimensional Dof vector

Definition at line 461 of file IReducedModel.m.

function Delta = IReducedModel.get_estimator_from_sim_data ( rb_sim_data )

staticpure virtual

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.

Implemented in NonlinEvol.ReducedModel, TwoPhaseFlow.ReducedModel, LinStatDune.ReducedModel, LinEvolDune.ReducedModel, LinEvol.ReducedModel, Test.ReducedModel, and LinStat.ReducedModel.

function Delta = IReducedModel.get_estimators_from_sim_data ( rb_sim_data )

staticpure virtual

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)\)

Implemented in NonlinEvol.ReducedModel, TwoPhaseFlow.ReducedModel, LinStatDune.ReducedModel, LinEvolDune.ReducedModel, Test.ReducedModel, LinEvol.ReducedModel, and LinStat.ReducedModel.

function Mratio = IReducedModel.get_Mratio ( 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\).

Parameters

detailed_data detailed data

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.

Required fields of detailed_data:

datatree — datatree

Definition at line 668 of file IReducedModel.m.

function mu = IReducedModel.get_mu ( )

virtual

returns the active parameter vector \(\mu \in { \cal M }\)

Return values

mu	The parameter vector \(\mu\)

Implements IModel.

Definition at line 566 of file IReducedModel.m.

function rb_size = IReducedModel.get_rb_size ( 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...

Parameters

detailed_data detailed data

Return values

rb_size rb size

Definition at line 577 of file IReducedModel.m.

function p = IReducedModel.plot_sim_data	(	model_data,
		sim_data,
		plot_params
	)

plots the simulation data as returned by detailed_simulation()

This method actually calls the plot_sim_data() method on the detailed_model member.

Parameters

sim_data	simulation data structure as returned by detailed_simulation()
plot_params	structure which controls the plot output
model_data	model data

Return values

p	GUI handle to the created MATLAB figure

Definition at line 496 of file IReducedModel.m.

function rb_sim_data = IReducedModel.rb_reconstruction	(	detailed_data,
		rb_sim_data
	)

pure virtual

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() .
detailed_data	detailed data

Return values

rb_sim_data struct holding the reduced simulation results and their reconstructions.

function rb_sim_data = IReducedModel.rb_simulation ( reduced_data )

pure virtual

Executes a reduced simulation and optionally an error estimation.

Parameters

reduced_data reduced data

Return values

rb_sim_data structure holding the coefficient vectors of the reduced simulations and optional error estimators.

function this = IReducedModel.set_Mratio	(	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

detailed_data	detailed data
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.

Return values

this this

Required fields of detailed_data:

datatree — datatree

Generated fields of this:

M — M

Definition at line 631 of file IReducedModel.m.

function this = IReducedModel.set_mu ( mu )

virtual

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

Generated fields of this:

detailed_model — detailed model

Implements IModel.

Definition at line 541 of file IReducedModel.m.

function ret = IReducedModel.subsref ( 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.

Parameters

S S

Return values

ret ret

Definition at line 703 of file IReducedModel.m.

Member Data Documentation

IReducedModel.crb_enabled = false

flag indicating whether this model depends on collateral reduced basis spaces.

Default: false

Definition at line 130 of file IReducedModel.m.

IReducedModel.debug

an integer defining the debugging level controlling error output and extra tests during basis generation

Note: This property has the MATLAB attribute Dependent set to true.; This property has non-standard access specifiers: SetAccess = Private, GetAccess = Public; Matlab documentation of property attributes.; [readonly]

Definition at line 115 of file IReducedModel.m.

IReducedModel.descr

The description structure holding information about the analytical parametrized problem and its discretization.

Note: This property has the MATLAB attribute Dependent set to true.; This property has non-standard access specifiers: SetAccess = Private, GetAccess = Public; Matlab documentation of property attributes.; [readonly]

Definition at line 58 of file IReducedModel.m.

IReducedModel.enable_error_estimator

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.

Note: This property is an abstract property without implementation.; Matlab documentation of property attributes.

Definition at line 159 of file IReducedModel.m.

IReducedModel.M = 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.

Default: 0

Definition at line 187 of file IReducedModel.m.

IReducedModel.Mstrich = 0

control variable for the number of (collateral) reduced basis vectors used for error estimation. By default this is equal to zero.

Default: 0

Definition at line 198 of file IReducedModel.m.

IReducedModel.mu_names

cell array of strings describing the parameters of the model

Note: This property has the MATLAB attribute Dependent set to true.; This property has non-standard access specifiers: SetAccess = Private, GetAccess = Public; Matlab documentation of property attributes.; [readonly]

Definition at line 77 of file IReducedModel.m.

IReducedModel.mu_ranges

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

Note: This property has the MATLAB attribute Dependent set to true.; This property has non-standard access specifiers: SetAccess = Private, GetAccess = Public; Matlab documentation of property attributes.; [readonly]

Definition at line 89 of file IReducedModel.m.

IReducedModel.N = 0

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.

Default: 0

Definition at line 176 of file IReducedModel.m.

IReducedModel.verbose

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

Note: This property has the MATLAB attribute Dependent set to true.; This property has non-standard access specifiers: SetAccess = Private, GetAccess = Public; Matlab documentation of property attributes.; [readonly]

Definition at line 102 of file IReducedModel.m.

The documentation for this class was generated from the following file:

rbasis/problem_types/oop/interface/IReducedModel.m

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation