Release Notes for MRST 2019a

Highlights of MRST 2019a

  • Extensions of the ad-framework to use more general function relations. This makes it easier to change the discretizations, functional dependencies and obtain sensitivities with respect to any variable. This includes adaptive implicit, explicit and fully-implicit support in all solvers, as well as new solvers such as higher-order WENO-discretizations. See the stateFunctionTutorial.m and wenoExampleAD.m in ad-core for more information and demonstrations of usage.
  • Support for Mex-acceleration has been added to most AD-solvers. Compiled versions of all standard discrete operators (discrete gradient, upwinding, discrete divergence, face average etc). This can be orders of magnitude faster for larger problems and execute in parallel through OpenMP. For instance, assembling a residual on the form Accumulation + Div(flux) for a 3D grid with 1,000,000 cells and 5 variables per cell is sped up a factor 30 from the pure Matlab implementation on the same computer, a reduction from 5.2 seconds to 0.17 seconds. The example blackoilTutorialMexAcceleration.m in ad-blackoil demonstrates how to make use of this functionality.
  • Support for many additional features useful for simulation of petroleum recovery from Eclipse-type decks: Two and three-point relative permeability endpoint scaling, threshold pressures, multiple PVT regions and a few other smaller points

Below follows a brief overview of important changes. In addition, full commit logs can be found at the MRST bitbucket pages:

Upgrade notes

The 2019a release of MRST is a major release with many new features and fixes. Consequently, there are a few changes which require attention for returning users who wish to keep existing third-party code running.

  • AD-solvers: Instead of the fluid regions being fixed into the fluid, we now produce multiple distinct functions in a cell array when regions are present. This is done instead of giving for example a single relative permeability function where the function being used would change based on the internal knowledge of the grid dimensions. This interface change makes it much easier to work with upscaling/refinement of test problems.
  • We have added a warning when calling double on ADI objects. You should instead use the new function "value". We do this to avoid the unfortunate implicit conversion behavior that occurs in expressions of this form:
    A = ones(10, 1);
    A(5) = b % Where b is some AD object, will then evaluate as A(5) = double(b).
  • NewAD has been renamed to GenericAD. If your functions use NewAD directly, you will have to update the corresponding calls.
  • The ad-fi module has been removed, after several releases with deprecation warnings.
  • addWell/verticalWell now defaults to the top of the formation for the reference depth. If you rely on bottom-hole-pressures with defaulted refDepth field in your wells, you must now add ..., 'refDepth', 0, ... to your input arguments to restore earlier behavior.


  • ADI.subsref: Support multiple indices for the special case A(index, :) for ADI variables.
  • ADI: interpPVT function added for ADI variables.
  • readGRDECL: Provide unrecognized keywords in primary output. Output has new UnhandledKeywords field containing a list of unrecognized keywords.
  • readGRDECL: Added support for keyword PERMH.
  • readGRDECL: Added recognition of keywords VSH and GDORIENT.
  • MRST Module: Detect duplicated module names in 'add'
  • Startup: Fix to avoid passing an empty list to mrstPath when running startup.m.
  • addWell: remove warnings about reference depth unless gravity is enabled.
  • convertHorizonsToGrid: Improvements to interpolation plus support for max/min of intersecting layers.
  • wells: Unify support for compi/Comp_i: Routines now accept either as keyword options. Giving different non-empty values for both will result in an error.
  • addWell: Add option to include line segments as input to 'addWell' for more accurate computation of connection factors.
  • computeTrans: Allow users to disable "fixing" of negative transmissibilities.
  • New SPE9 dataset with surfactant added.

Module changelog

Module ad-core

  • PhysicalModel now has a default implementation of getEquations and can store/retrieve AD-variables from the state. This implementation uses several new functions:
  • getStateAD: Get initialized AD-state with default primary variables.
  • initStateAD: Set up AD-state for a given set of initialized primary variable set
  • getPrimaryVariables: Get the models preferred primary variables.
  • getModelEquations: Get the model equations, given the state itself. This makes it possible to differentiate the residual equations with respect to any variable, not just the solution variables as in earlier versions of MRST.
  • reduceState: Remove AD-variables from state.
  • New framework for modular and efficient evaluation of AD functions. Generalized in the StateFunction and StateFunctionGrouping classes, this allows for easily swapping out solvers components on the fly. A few key member functions in PhysicalModel enable these features:
  • initStateFunctionContainers: Add storage to state for state function groupings
  • getStateFunctionGroupings: Get function groupings attached to this specific model (see ad-blackoil changelog for examples)
  • Standard operators now support problems with no internal faces (e.g. single-cell problems, or problems with disconnected domains)
  • Several logic fixes to CPR-type solvers for general block systems
  • getBoundaryConditionFluxesAD is more consistent when upwinding in the presence of strong gravity effects at the boundary of the domain.
  • Framework for simulation management: Multiple improvements to robustness, documentation and features. We highlight the capability of launching multiple simulations in parallel with only a basic Matlab license. See the example demoPackedProblems.m.
  • plotWellSols will be more robust when matching wells based on names from different solvers. The routine can now also visualize changes in the well controls as a function of time.
  • Support for Mex-acceleration in discrete operators when the DiagonalAutoDiffBackend is used (with backend-useMex flag set to true).
  • The testbed for new automatic differentiation features "NewAD" is no longer new and has been given the more permanent name "GenericAD".
  • Added ExtendedFacilityModel for use with new generic models, a new and faster facility model with vectorized assembly for wells and much leaner interfaces than the standard FacilityModel. Supports reservoir volume, RESV and historical RESV rates, as well as separators for compositional models.
  • makeScheduleConsistent: Several improvements to merging of complex wells present in different steps with varying perforations. New strategies for merging, including "direction" which minimizes distance based on the well perforation direction.
  • Fix in derivatives for PVT-interpolation which could result in convergence issues for vapoil models.
  • simulateScheduleAD now displays the full simulation progress in the header when restarting simulations, rather than using the restart step as the first step in a truncated schedule.
  • initEclipseProblemAD has added support for diagonal-mex AD backend.
  • ReservoirModel: Added getNubmerOfComponents and getNumberOfPhases member functions.
  • getBoundaryConditionFLuxesAD: Corrected mobility outside of domain when using .sat.
  • PhysicalModel.getVariableField/getProp(s): Numerous improvements to support getting AD-values from state.
  • PhysicalModel has taken over schedule validation from simulateScheduleAD, and should give better error messages for common errors (validateSchedule).
  • NonLinearSolver previously gave warnings when time-steps were cut. Timestep cuts are unfortunately a fact of life for nonlinear problems and consequently the warning has been changed to a more informative message when verbosity is enabled.

Module ad-blackoil

  • A new model GenericBlackOilModel which handles any combination of water, gas and oil, with and without both disgas and vapoil. As a consequence, ThreePhaseBlackOilModel no longer supports not having a water phase present. ThreePhaseBlackOilModel has a more readable single self-contained equations function while GenericBlackOilModel has more functionality.
  • All models have been rewritten to use the new property system. This means that the functions getFluxAndProps_* will be deprecated in a future release.
  • Numerous fixes to corner-cases and removal of minor inconsistencies. Especially cases with significant capillary pressure will see improved convergence.
  • blackoilTutorialMexAcceleration: New example demonstrating faster assembly and parallel support.

Module ad-eor

  • Bug-fixes in computeRelPermSft. We thank Xin Sun from China University of Petroleum for these updates.

Module ad-props

  • Parsing of fluid properties with multiple regions has been rewritten. See upgrade notes for more details.

Module compositional

  • New models GenericOverallCompositionModel and GenericNaturalVariablesModels with full support for mex-acceleration, variable implicitness and the state function system.
  • Equilibration-based initialization of initial state now supports compositional models (getInitializationRegionsCompositional)
  • The sequential models have support for additional strategies for pressure reduction and its derivatives.
  • The FastAD function has been removed. It is no longer needed, as DiagonalAutoDiffBackend together with a full rewrite of getPhaseFractionAsADI gives better performance.
  • EquationOfState has had an internal cleanup. A major change is that getProperties is now more accurately named getCompressibilityAndFugacity.
  • As a consequence of using the new property system, the number of redundant evaluations has been greatly reduced (e.g. gas density is no longer evaluated in cells where gas does not exist by default).
  • Fixed a bug where x, y would not match state.compositions in the single-phase regions for the first step of a simulation.
  • The solvers now always store the current "best-estimate" K-values for a cell in state instead of restarting with Wilson's estimate every time flash is called from a single-phase state. This should significantly reduce the amount of iterations spent in flash and stability tests.

Module optimization

  • Improved behavior for lineSearch in presence of very small gradients.

Module blackoil-sequential

  • Will now output updated phase fluxes in transport solvers
  • multiphaseUpwind no longer gives errors for models without any interior faces.

Module solvent

  • Improved backwards compatibility for older Matlab versions.

Module diagnostics

  • Added support for input of MRST simulations into flow diagnostics postprocessing GUI.
  • Total well rates are now output from computeRTD and estimateRTD.
  • More thorough timestepping is used for computeRTD.

Module mrst-gui

  • Improved performance for 2D coarse grids in plotToolbar.

Module streamlines

  • Pollock: Bug fix to avoid "forever-tracing" streamlines for some grids. If a cell only contains infinite departure time-of-flights then the streamline is terminated.
  • Pollock: Expose "blocksize" parameter so block size for processing can be adjusted.
  • Pollock: Allow explicit termination criteria in cells (useful for weak sources).

Module deckformat

  • Account for EoS regions in 'EOS' keyword.
  • Extended support for endpoint scaling, max relperms, initial water saturation.
  • Added distinction RESV_HISTORY for historical RESV controls.
  • Added support for WELOPEN with non-defaulted ranges.
  • Improved support for multisegment wells.
  • convertDeckUnits: A few missing units added - area, invarea, volume.
  • convertSummaryToWellSols: Account for missing output via ratios. Added verbose output when things are not present.

Module incomp

  • Support both "wells" and "W" as keyword arguments for solvers but not both at the same time.

Module linearsolvers

  • New example showOptionsAMGCL.m which interactively demonstrates main features of AMGCL setup.
  • Added support for block matrices in MRST interface to AMGCL.
  • AMGCL build script: Only link to MATLAB's builtin OpenMP implementation.

Module mimetic

  • Support both "wells" and "W" as keyword arguments for solvers but not both at the same time.

Module mpfa

  • Support both "wells" and "W" as keyword arguments for solvers but not both at the same time.

Module mrsb

  • reconstructPressure: Add a tiny bit of matrix noise to fix UMFPACK behavior in newer Matlab versions. This fixes non-finite values in the reconstructed velocity field on R2018b+.

Published July 31, 2018