rbmatlab  1.16.09
 All Classes Namespaces Files Functions Variables Modules Pages
RBmatlab software

Introduction

RBmatlab is a MATLAB library for model order reduction with Reduced Basis Methods for various discretizations types and application settings.

The package comprises:

Installation

After unpacking (or git checkout) of the package, you need to adjust your MATLAB startup script to load the RBmatlab package. Under UNIX-like environments, the MATLAB startup file is located in $HOME/matlab/startup.m. This file is run on every start of MATLAB and can be used to load specific packages such as RBmatlab.

If your matlab installation supports the "setenv" command, installation is very simple:

Make sure, that the following code is executed during MATLAB startup, e.g. by putting it into the $HOME/matlab/startup.m file or by executing it every time you start MATLAB by cut'n paste. Of course replace the pathname by your local version. In particular you must set the path to the RBmatlab directory and choose the temporary-data directory, where some GB of space are available for intermediate and cached data.

  %-------- start of init code ---------
  setenv('RBMATLABHOME','/path/to/your/rbmatlab/instance/matlab/RBmatlab');
  setenv('RBMATLABTEMP','/tmp/matlab');
  addpath(getenv('RBMATLABHOME'));
  startup_rbmatlab
  %-------- end of init code ---------

First Start

After starting matlab, have a look at the "demos" and start them one by one to get an impression of the package. In particular the following demos are suggested. View their source to see the use of the package's routines:

  1. Example of a detailed simulation (finite volume time evolution) demo_explicit_FV()
  2. Steps of model reduction (inspect source-code while executing!) demo_rb_steps()
  3. Interactive Gui demo_rb_gui()

Many further demos are available, see the corresponding directory or the script rbmatlabdemos().

Basic Overview

The overall idea of the RBmatlab software is to define global interfaces that can be used for applying the application of the Reduced Basis method. As a simple example, consider the following code for a simple thermal-block example:

 % Define the model. In this example, we use a simple structure-based
 % definition of the model. For a more detailed description of the 
 % model and its properties, please check the file directly.
 model = thermalblock_model_struct;

 % The idea of RBmatlab is to use so-called model_data structures, that
 % contain all "expensive" components, such as the grid or the information
 % about the discrete functions:
 model_data = gen_model_data(model);

 % Perform a detailed (expensive, high dimensional) simulation:
 dsim = detailed_simulation(model, model_data);

 % Construction of the reduced basis
 detailed_data = gen_detailed_data(model, model_data);

 % Construction of the redued data (for error estimation, ...)
 reduced_data = gen_reduced_data(model, detailed_data);

 % Performing a reduced basis simulation:
 rbsim = rb_simulation(model, reduced_data);

 % Reconstructing the full solution (if needed)
 rbrec = rb_reconstruction(model, detailed_data, rbsim);

In general, all models in RB matlab should be callable with the above interface functions. Please make sure that your model follows this principle by either implementing the AbstractModel interfaces, or by providing function handels in the structure returned by your model constructor. The function gen_model_data(model) for example is just a wrapper that calls model.gen_model_data(). All other interfaces work in the same manner.

There are two different types of approaches, both are supported and serve different goals:

RB-Tutorial

The package is used for RB summerschools and the RB-Tutorial book chapter

B. Haasdonk: Reduced Basis Methods for Parametrized {PDE}s --  
A Tutorial Introduction for Stationary and Instationary Problems.
Chapter in P. Benner, A. Cohen, M. Ohlberger and K. Willcox (eds.): 
"Model Reduction and Approximation: Theory and Algorithms", SIAM, Philadelphia, 2016

A Preprint version of this chapter is available at: http://www.simtech.uni-stuttgart.de/publikationen/prints.php?ID=938.

We suggest to read that chapter and "play along" the presented experiments with the script rb_tutorial.m. In particular the commands rb_tutorial(1) until rb_tutorial(17) reproduce the experiments/plots of that tutorial comprising thermal diffusion and advection-diffusion problems.

As special variant of that MATLAB script we offer scripts/rb_tutorial_standalone.m which is decoupled from RBmatlab in the sense that only that file together with the file data_rb_tutorial_standalone.mat is sufficient to reproduce the experiments for the thermal diffusion in the tutorial.

Documentation

The documentation of the package is generated by Doxygen - an automatic documentation tool. Although designed for C-like languages, Doxygen allows to pre-process the source code by a filter programm that makes Matlab-code parseable by Doxygen as well. This generates a browsable html documentation of the files, classes and dependencies. The corresponding starting file is doxygen/html/index.html or can simply be accessed by htdoc() in the matlab command window.

In order to extend and re-build this documentation by your own, you therefore

  1. need to download and install
    • a recent version of Doxygen available from its website. and
    • the filter program mtoc++ currently available from here.
  2. you can execute the script make_docu.sh in the base directory of your RBmatlab installation.

Running the Tests

RBmatlab ships with unit tests for many different functions and classes. The testing framework relies on the Matlab built-in testing framework, which is available for Matlab versions after R2013b. In order to execute the tests, simply run

 run_all_tests

or call them individually by running for instance

 runtests('test_ldgfunc')

Please feel free to extend the test suite by adding your own tests. Ideally, when you create a new model, write a simple test that checks that at least the model can be instantiated and detailed simulations can be performed.

Contact

The package is jointly developed by the University of Stuttgart, the University of Muenster, the University of Ulm and the Sandia Lawrence Livermore National Research Laboratory.

The package is available via the website http://www.morepas.org.

Please send remarks/comments/questions to rbmatlab developers mailing list: rbmat.nosp@m.lab@.nosp@m.lists.nosp@m.erv..nosp@m.uni-s.nosp@m.tutt.nosp@m.gart..nosp@m.de