MRST - MATLAB Reservoir Simulation Toolbox

Frequently Asked Questions
We get a lot of different questions about MRST. On this page, we try to summarize the most commonly asked questions. However, please do not hesitate to contact us if you do not find an answer to your question below.
How do I install MRST?

MRST is provided as a self-contained archive file (a Unix-style TAR file compressed with GZip). The archive can be extracted from within MATLAB using the untar function. The MRST developers recommend extracting the archive to a subdirectory of your user's home directory. Using untar, this would be a command like

  untar mrst-2015a.tar.gz

which would create a new directory mrst-2015a in your current working directory. Once MRST has been extracted to some directory, you must navigate MATLAB there, either using the builtin file browser, or by using the cd command,

On Linux/Mac OS,

    cd /home/username/mrst-2015a/

or on Windows,

    cd C:\Users\username\mrst-2015a\

Assuming that the files were extracted to the home directory. The startup.m file must then be run to activate MRST,

    startup;

Alternatively, if do not want to navigate to the MRST root directory, for instance in an automated script, you can call startup directly

    run /home/username/mrst-2015a/startup

To verify that MRST is active, you can run a simple example, for example by writing 'flowSolverTutorial1' (the example is named 'gravityColumn' for versions prior to MRST 2016a). A simple gravity pressure problem should be solved and plotted.

 We also have a Jolt tutorial that goes through the process of getting MRST up and running:

How to download and getting started with MRST

Which version of MATLAB does MRST require?

The minimal requirement of MRST is MATLAB version 7.4 (R2007a). However, certain modules use features that were not present in R2007a:

  • The functionality for automatic differentiation (which module 'ad-fi' relies upon) uses new-style classes (classdef) that were introduced in R2008a.
  • Various scripts and examples use new syntax for random numbers introduced in R2007b.
  • Some script may use the tilde operator to ignore return values (e.g, [~,i]=max(X,1)) that was introduced in R2009b.
  • Some solvers like the fully implicit solvers from the 'ad-core' module will run but may not be efficient on versions older than R2011b.

Note that the naming convention for MRST simply refers to the time of the release (2016a was released in the first half of 2016, for instance). It does not imply a specific MATLAB version for a specific release, even though the naming conventions for MATLAB is similar to that of MRST.

A related question is also to what extent MRST can be used with Octave. Here, the primary difficulty is the lack of visualization. (The interested user may, however, check out a simple MRST-geared backend developed by Lars Jahr Røine). In addition, Octave does not yet offer the new-style classes (classdef) used in the implementation of automatic differentiation.

 

Does MRST have a user guide?

There is a preliminary user guide that describes the grid structure, generation of petrophysical properties, various single-phase solvers (two-point, mimetic/MPFA), as well as how to use automatic differentiation to make your own solvers for nonlinear single-phase models. For the remaining parts of MRST, we suggest you use the following sources of information:

  • Example scripts - the core module offers a set of example scripts located in the subdirectory 'examples' that describe grid generation and basic one-phase and two-phase solvers. Some of these example scripts are available on the tutorial pages.
  • Module examples - many of the modules contain a set of scripts (located in the subdirectory 'examples' of the module) that outline functionality provided in the module. Some of these examples are available on the module overview pages.
  • Manual pages for individual routines - all routines in MRST are documented using a style similar to standard Matlab that describes synopsis, input/output parameters, and how the routine works. In most cases, the documentation also offers simple examples of usage and list related routines.
  • The source code itself - all parts of MRST are available as open source code. However, MRST is a research tool that was developed primary to provide a flexible development platform, and some parts of the software may admittedly be quite hard to digest for those unfamiliar with our way of writing efficient Matlab.

 

Is MRST a reservoir simulator / where is the reservoir simulator?

MRST is, as the name implies, a toolbox that contains many of the features associated with reservoir simulators such as visualization, solvers, and grid processing/generation, but it is not a stand-alone/black-box simulator. It assumes that the user is comfortable working "under the hood" and knows how to choose the right tools for the right job. It is not meant as a replacement to commercial simulators.

 

Which solver should I use?I am interested in studying a specific problem. Which solver / module should I use in MRST?

MRST has several different solvers for both pressure and transport problems. Choosing the correct solver depends on the physical effects involved as well as other features in your problem. The table below lists the main solvers used for general flow problems and their features.

Solver name No. phases Model type Compressibility Solver type Wells Multiple well limits Boundary conditions Source terms Seq. splitting Complexity Gas dissolution Discretization Module name
incompTPFA 1-3 fractional flow No Pressure Yes No Yes Yes Yes Low No TPFA

incomp

incompMimetic 1-3 fractional flow No Pressure Yes No Yes Yes Yes Low No Mimetic mimetic
incompMPFA* 1-3 fractional flow No Pressure Yes No Yes Yes Yes Low No MPFA mpfa
implicitTransport 2 fractional flow No Transport Yes No Yes Yes Yes Low No (any) incomp
explicitTransport 2 fractional flow No Transport Yes No Yes Yes Yes Low No (any) incomp
simulateScheduleAD 2-3 black oil ++ Yes Pressure / Transport Yes Yes Yes Yes No Moderate Yes TPFA ad-core, ad-blackoil, co2lab
* Does not support all grids

 

In addition to this, there are several specialized solvers such as multiscale solvers for pressure (MsMFEM / MsFVM), vertical equilibrium solvers for CO2 segregation problems, time-of-flight solvers, and so on. The table may indicate which solver is the most applicable for your problem. As a rule of thumb, the sequential splitting solvers support less physical effects than the fully implicit solvers, but they may be easier and faster to use. For most simple problems, we recommend the use of incompTPFA / implicitTransport. For including additional effects, such as three-phase black-oil or polymer injection with more complex well controls, the ad-blackoil module is the best choice. Here, the use of automatic differentiation ensures that the part of a solver that implements the model equations is quite transparent and simple to understand. On the other hand, if you decide to dive deep into the details of the advanced 'ad-fi' solvers, you will probably find that the control logic is more involved since the solvers support more complex effects (well descriptions, in particular). Likewise, additional complexity is added by the preconditioning used to make a solver efficient and the adjoint formulation used to compute sensitivities.

For more specialized solvers and applications we refer to the modules overview page.

 

What external packages are commonly used with MRST?
Several third party packages and libraries have proven useful with MRST. We list some of the most useful below.
  1. MATLAB-BGL -  MATLAB Boost Graph Library is a useful set of utilities which contains MATLAB-compatible binaries of the useful Boost Graph Library. Functions such as connected components, depth first search etc are not included in standard MATLAB and are often inefficient when implemented in pure MATLAB. BSD License. http://www.mathworks.com/matlabcentral/fileexchange/10922
  2. METIS  -  partitioning of fully unstructured grids is easily done by translating the problem to sparse matrices and calling existing routines. METIS is one such library that is released under a permissive Apache License 2.0. http://glaros.dtc.umn.edu/gkhome/metis/metis/overview 
  3. Export_fig -  to produce high quality figures for publications the custom export utility export_fig is extremely useful. Some key features include arbitrary resolution rendering and automatic cropping of figure axes. BSD License. http://www.mathworks.com/matlabcentral/fileexchange/23629-exportfig 
  4. Algebraic Multigrid - specialized solvers for elliptic problems arising from the discretization of e.g. the pressure equation can greatly speed up simulation times. We often use AGMG because it has convenient MATLAB bindings included, but the current version is unfortunately no longer released under the GPL license, but free licenses are provided for academic purposes. http://homepages.ulb.ac.be/~ynotay/AGMG/

 

Why does plotting using transparency result in crashes? Is this a bug in MRST?

Several users have experienced that MATLAB crashes or locks up when MRST plots figures involving transparency or when plotting on multi-monitor setups. This is a known issue with some graphics drivers in MATLAB and has nothing to do with MRST as such.  The primary two issues are:

  • If using multiple monitors, the issue may be related to the DefaultFigureRenderer. When plotting a new figure with a patch object, the figure immediately switches from 'painters' to 'OpenGL' and this may result in a crash. A fix is to call set(0, 'DefaultFigureRenderer', 'OpenGL') so that the default is changed. Note that this changes the default behavior until MATLAB is restarted and not all MATLAB features are supported in OpenGL, for instance logarithmic axes.
  • When transparent plots such as plotCellData(G, 'FaceAlpha', 0.5) results in a crash, a common fix is to change the default render mode from "normal" to "fast". This may cause strange effects for some composite plots where several layered patches are plotted, but the crashes should stop. Calling set(0, 'DefaultAxesDrawMode', 'fast') may solve the problem.

These two issues make up most of the issues encountered with OpenGL. Because of this, the fixes are specifically incorporated in the function 'setRenderFixes'. If you are having issues, try activating it:

    mrstModule add mrst-gui

    setRenderFixes(true);

The defaults can be reset using

    setRenderFixes(false);

For more info on OpenGL and possible workarounds, see Mathworks' own page on the subject. Updating your graphics adapter drivers may also help.

 

How can I do LGR/well refinement in MRST?

Although we have plots showing for example radial well refinement, MRST does not currently include functions for doing so on general grids. For other types of dynamic coarsening / refinement, see the agglom module.

 

What do I do if I have a question that is not listed here?
Send an e-mail with your question to the MRST mailing list or, if your question is not suitable for public display, mrst@sintef.no.

Published October 15, 2013