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: either as a Unix-style TAR file compressed with GZip (.tar.gz) or as a ZIP archive (.zip). The archive can be extracted from within MATLAB using the untar or unzip functions. The MRST developers recommend extracting the archive to a subdirectory of your user's home directory. Using unzip, this would be a command like

  unzip mrst-2020a.zip

which would create a new directory mrst-2020a 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-2020a/

or on Windows,

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

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-2020a/startup

You will then see a welcome message that starts with "Welcome to the Matlab Reservoir Simulation Toolbox (MRST)!"

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.

Please note that MRST is only activated for your current Matlab/Octave session. You will have to repeat the startup function when starting a new session. MRST does not permanently modify your path or Matlab installation.

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?
It depends on what you want to use. MRST developers use the updated Matlab releases during development, but we aim to be five years backwards compatible. Some of the older parts of MRST (incompressible solvers and consistent discretization) work as far back as Matlab 2010a. Newer solvers require modern "classdef" classes and perform the best in Matlab versions from 2012 on.

 

 

Does MRST support Octave?

We aim to be compatible with the free software alternative to Matlab, GNU Octave. Octave has had greatly improved support for many of the key language features used in MRST over the last few years. The AD solvers work in Octave, as do the compiled linear solvers. 3D visualization is also supported, but the graphical user interfaces are not. https://www.gnu.org/software/octave/

We recommend Octave 5.2.0 and newer. You may need the Octave compatibility module for MRST.

 

Does MRST have a user guide?

The MRST User Guide is a freely available book, released as open access. The book describes most aspects of MRST from both a practical and a mathematical perspective. Please see our documentation page. In addition, there are several other sources of documentation:

  • 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. You can also use the "mrstExample" function to see the available examples. "mrstExamples ad-core" will list all examples in the ad-core module.
  • 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. For running an Eclipse-type input file directly, we suggest you take a look at the "simulateSPE1" example under ad-blackoil for a minimal working example of this.

 

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

MRST has a large number of different solvers. We list a few of the major categories:

  • ad-blackoil: fully-implicit solvers for up to three phases (water, oil, gas) with support for both immiscible and blackoil type flow (dissolved gas / vaporized oil).
  • compositional: K-value or equation-of-state multi-component flow. Up to three phases, with the third phase assumed to be a "simple" water phase only made up of H2O.
  • co2lab: Solvers specialized for the simulation of geological storage of CO2. Includes many types of vertical-equilibrium formulations (sequential schemes, fully-implicit schemes)
  • ad-mechanics: Coupled mechanics and flow. Uses the Virtual Element Method.
  • blackoil-sequential: Sequential variations of the fully implicit solvers in the ad-blackoil and compositional modules.
  • geochemistry: Surface chemistry (geochemical reactions)
  • incomp: Legacy solvers for incompressible two and single-phase flow based on sequential splitting.
  • mimetic/mpfa: Incompressible consistent discretizations (see incomp) for the pressure equation.

Most solvers support flow driven by wells, source terms and boundary conditions.

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. Note that Matlab-BGL and AMGCL are automatically downloaded by MRST when needed - no installation required.
  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. AMGCL - https://github.com/ddemidov/amgcl General-purpose iterative linear solver library. See the linearsolvers module in MRST for examples of usage. Permissible license - recommended solvers to use for larger models.
  5. AGMG - 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/
I use Matlab 2015a. Do I need to download MRST 2015a?
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. We try to to support at least five years of backwards compatibility.
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