Release Notes for MRST 2020b

Highlights of MRST 2020b

The new release comes with the addition of several new internal and externally contributed modules from the upcoming second MRST book. There are some minor changes to existing modules described in the release notes below. In particular we would like to highlight the following:

  • The addition of seven new modules (described further down): dual-continuum-mech, ensemble, fractures, fv-unsat, hybrid-ve, mpsaw, shale.
  • More advanced workflow examples from the upcoming second MRST book included in several modules.
  • The name of the blackoil-sequential module has been changed to sequential.
  • Some class names have been changed in the ad-blackoil module. See the notes under ad-blackoil for more details.

We have also introduced a new category system for modules where modules have been given a classification based on the type of development they are currently undergoing. This is to help users determine how likely the code is to change in future releases. The main benefit of this is that users can be confident that their own code based on e.g. stable modules is unlikely to need updating much between releases whereas code based on experimental modules is much more likely to need updating to be compatible with future versions of these modules.

The full category list for all modules can be found on our website at The categories are as follows:


Mature code, stable, bug-fix mode only, not under active development.


Feature complete, well tested, changes are thoroughly documented and subject to strict testing.


Under active development, internal interfaces / algorithms may change without notice, major interface changes documented.


Recently added functionality, may change significantly between releases or disappear entirely if not sufficiently matured.


Has been / will be removed in future releases.

New modules

Module dual-continuum-mech

This module is for the modelling of multiscale poroelastic materials within a dual-continuum setting. We have incorporated material anisotropy up to orthotropy, which is reflected in the poroelastic constitutive equations, and allowed for both materials to have intrinsic mechanical properties.

The module itself was developed by Mark Ashworth of the Multiscale / Multiphysics Group in the Institutite of GeoEnergy Engineering, Heriot-Watt University. In the module we leverage the Dual-Porosity module developed by Rafael March and Victoria Spooner, as well as the AD-mechanics module developed at Sintef.

It is strongly suggested to look at the examples to see how the model is instantiated and used for the various levels of physical detail required (i.e. isotropy, anisotropy, etc).

The included examples are:

  • example_voidfractures: How to setup a simple 2D test case using the isotropicVoidCoefficientModels.
  • example_stifffractures: How to setup a simple 2D test case using the isotropicStiffCoefficientModels.
  • example_anisotropicfractures: How to setup a simple 2D test case using the anisotropicStiffCoefficientModels.
  • DC_NorneExample: 3D dual-continuum-mech example on a geological grid.

Please see the module README for more information.

Module ensemble

This module aims to introduce a common framework for working with ensembles and ensemble simulations within MRST. The ensembles are defined through a highly generic API, and specific ensembles are defined by a combination of three components:

  • Base problem – containing all parameters/configurations that are common and shared across all the ensemble members.
  • Stochastic samples – The uncertain/stochastic elements of the ensemble are defined through instances of sample classes, either directly by values, read from files, or generated on the fly. These classes also contain functionality for mapping such samples to the base problem and thereby generating unique ensemble members.
  • Quantity of interest – Class instances for various individual and statistical post-processing of the simulation results.

The module also provides functionality for parallel simulation of ensemble members, either by use of the parallel computing toolbox, or by spawning background MATLAB sessions.

This is an experimental module, and in the future, the module will be extended to be applicable for problems such as uncertainty quantification, optimization under uncertainty, and history matching.

Module hybrid-ve

A new module that implements partitioning algorithms for hybrid, multi-resolution grids for the simulation of vertical equilibrium (VE) coupled to regular finite-volume discretizations. The module supports complex layered structures, and can drop down to fine-scale solvers in e.g. near well regions.

For more details, see: Møyner and Nilsen, Multiresolution coupled vertical equilibrium model for fast flexible simulation of CO 2 storage, Computational Geosciences 23.1 (2019): 1-20.

Module fractures

MRST Fractures Module is a package for simulating multi-phase flow in fractured porous media using single- and multi-continuum concepts. Version v2020.

Documentation can be found in the upcoming MRST book:

March et al., A Unified Framework for Flow Simulation in Fractured Reservoirs, 2021 (Chapter in the upcoming MRST book 'Advanced Modelling with MATLAB Reservoir Simulation Toolbox (MRST)', preprint available upon request).

This module was contributed by Rafael March, Christine Maier, Florian Doster and Sebastian Geiger from the Institute of GeoEnergy Engineering, Heriot Watt University. Please see the module README for more information.

Module fv-unsat

This module implements a discretization of the (three-dimensional) equations of unsaturated poroelasticity using cell-centered finite volume methods, specifically MPFA-O and MPSA-W. Note that if mechanical effects are neglected, the set of equations reduce to the well-known Richards' equation. The module is written based on the Automatic Differentiation framework provided by MRST.

There are four numerical examples accompanying this module:

  • convAnalysisRE.m
  • convAnalysisUnsatBiot.m
  • waterInfiltrationRE.m
  • desiccationUnsatBiot.m

The first two are convergence tests and the last two are practical applications. Even though the numerical tests are well documented, they are not meant as tutorials, but rather included for demonstrative purposes. To learn the basics regarding the module usage, we recommend waterInfiltrationRE.m.

This module was largely based on:

  • Varela, Jhabriel. Implementation of an MPFA/MPSA-FV Solver for the Unsaturated Flow in Deformable Porous Media. MS thesis. The University of Bergen, 2018.

This module was contributed by Jhabriel Varela from the University of Bergen.

Please see the module README for more information.

Module mpsaw

This module implements the multipoint-stress approximation using weakly imposed stress symmetry, as developed by Nordbotten and Keilegavlen (see complete reference in module). An advantage of this discretization scheme is that it leads to a cell-centered method (as MPFA in the case of flow) and can be used on general grids. The module contains a set of convergence test cases (2D/3D, different types of grids) and examples of couplings with flow simulations.

This module was developed jointly by the University of Bergen and SINTEF Digital.

Module shale

This MATLAB package was developed to facilitate the compositional modeling of naturally-fractured reservoirs, such as shale gas/oil reservoirs. It implements the 3D Projection-based Embedded Discrete Fracture Model (pEDFM) presented in the following journal:

O. M. Olorode, B. Wang, H. U. Rashid. “Three-Dimensional Projection-Based Embedded Discrete Fracture Model for Compositional Simulation of Fractured Reservoirs”. SPE Journal, 2020, Volume 25, Issue 04, 2143–2161 (

This module was contributed by Prof. Femi Olorode and coworkers at Louisiana State University.

Please see the module README for more information.

Changes to existing modules


  • Add well_temperature as a possible primary variable for wells.
  • BlackOil pressure reduction: Correct the weighting factors that form the pressure equation for the undersaturated state
  • New example for comparing AD backends and benchmarking, exampleBenchmarkBackends.m, parallelScalingAD.m, showADBenchmarkAssembly.m, assemblyBenchmarkAD.m.
  • Added support for E300 blackoil declaration in ECLIPSE deck.
  • Added support for processing simulation output before storing data in simulateScheduleAD.m, thus allowing selective storage of simulation output.
  • The “FluxProps” state function grouping storage field has been renamed to “FluxDisc”.


  • Renamed ExtendedReservoirModel class to GenericReservoirModel.
  • Renamed ExtendedFacilityModel class to GenericFacilityModel.
  • Renamed FluxDiscretization class to FlowDiscretization.
  • Minimal SPE3 example added.


  • Two new example scripts, presenting the Terzaghi and Mandel problems (terzaghi.m and mandel.m)
  • Added function for automatic computation of poroelastic parameters (poroParams.m)


  • This module has been renamed sequential.


  • CompositionalFluid has been renamed to CompositionalMixture. The new class has greatly improved display (“disp”) functionality. Consequently, the EoS model now has a mixture field instead of a compositional fluid field.
  • Any phase can now be designed as vapor and liquid (no longer limited to oil+gas)
  • Several improvements to variable naming and various internal functions
  • Default scaled mass balance tolerance has been tightened to 1e-3 (was 1e-2)
  • Several previously hardcoded parameters are now class properties
  • The names of primary variables in the natural variables formulations have changed slightly. This should only concern users who are working directly with their own linearization (for more details, see the commit log on bitbucket)


  • Add support for recognizing well-name patterns in the “COMPDAT” keyword.
  • Fix a bug that led to attempting to read an incorrect number of records in the “PVTW” keyword—especially if some records were defaulted.
  • Fix a bug that led to incorrect mistaking mixing ratios for bubble point pressures in the “PVCO” keyword.


  • Added Egg model example.


  • This is the module formerly known as black-oil sequential.

Changes to third-party modules



  • Add optional property ‘submodelFn’. If non-empty, this function handle will be used to set up the subdomain models. Useful for pre- and postprocessing a SubdomainModel, or for using something different altogether. If empty, the class defaults to using SubdomainModel.
  • Output reports from subdomain solves to enable fine-grained analysis of solver performance.


  • Add optional input argument ‘includeExternal’ for mapping external cell values.


Major revision, including

  • Migrate to generic framework, so that we now have a single ‘GeothermalModel’.
  • Support for arbitrary number of salt components
  • Several new state functions
  • Dedicated facility model for proper support discretization of well heat fluxes, consistent with well flow flux discretization.
  • Thermal boundary conditions are now assigned by setting temperature or heat flux on existing BCs. This removes the need for adding a separate BC struct for heat.

New example

  • Enhanced geothermal system in a small, artificial fracture network constructed using the UPR module.

Published November 30, 2020