Highlights of MRST 2014a

The 2014a release of MRST features

• A completely rewritten module for fully implicit solvers based on automatic differentiation, with robust handling of changing well controls and variable switching to handle presence or absence of a free gas phase.
• A completely reorganised module for studying carbon capture and storage.
• A completely rewritten module system that removes the distinction between "blessed" modules developed by SINTEF and modules developed by other parties (and users).

Please review the Upgrade Notes at the end of this document if you're upgrading from a previous edition of MRST.

Acknowledgements

 Work by the following people constitutes the 2014a release of MRST

• Stein Krogstad
• Knut-Andreas Lie
• Olav Møyner
• Halvor Møll Nilsen
• Xavier Raynaud
• Bård Skaflestad 

Primary release manager for MRST 2014a: .

New developments in MRST 2014a

Core (module system)

The module system has been completely rewritten for MRST 2014a. This release splits the system in two parts. The new facility mrstPath is a registry that maps module names to system paths whereas the responsibility of the existing function mrstModule becomes solely to activate and deactivate modules and to manipulate MATLAB's function search path.

This change allows greater user control of module locations and removes the distinction between "blessed" modules distributed as part of MRST (located in the 'modules' directory) and user or third-party modules. The release package still locates official MRST modules in the 'modules' directory but the new module system encourages independent module development.

There is a downside to the reorganisation and users need to be aware of this fact. As function mrstModule now uses mrstPath as its only source of module mappings, one cannot activate a module (say, the diagnostics module) without first establishing a path mapping for that module. If no mapping exists in mrstPath, then function mrstModule produces an error message of the form

>> mrstModule add diagnostics
No module mapping found for
  * diagnostics

and fails to load the module.

There is a short tutorial on the behaviour and use of the new module system at the end of this document.

Core (ADI class)

• Support all varieties of the POWER function. Thanks to: Sindre Hilden
• Fix a programming error in operator interpRegPVT that produced wrong results in the case of (ADI,DOUBLE) input parameters.

Core (example grids)

Pinch layers of negative thickness in makeModel3. Thanks to: Jostein Natvig

Core (TPFA-based solvers)

Add experimental support for non-neighbouring connections.

Core (Time-of-flight)

Rewrite function computeTimeOfFlight to transparently handle single- and two-phase flow problems. In earlier release, the function would scale source terms with the injected (water) saturation which produced wrong results in the single-phase case.

Fully Implicit Solvers based on Automatic Differentiation (ad-fi)

• Complete rewrite of the well handling to more robustly handling changing variables in the middle of a non-linear loop. We now implement most of ECLIPSE's well behaviour.
  
  This rewrite changes the structure of the "ad-fi" well solution so that it is no longer compatible with the 'state' object produced by other MRST solvers.
• Implement "discrete row sum" option for deriving the pressure equation from a set of material balance relation in the CPR preconditioner.
• Implement three-phase models with volatile oil.
• Implement region support for imbibition curves.

CO₂ Laboratory (co2lab)

A module that was previously distributed as a separate package has been integrated into MRST. In doing so, the layout has been completely reorganised into packages for analysing trapping structures and doing simulations in the vertical equilibrium framework.

Agglomeration/Amalgamation module (agglom)

Split refinement function refineSuccessivePart into two functions, applySuccessivePart and refineRecursivePart.

Deck input support module (deckformat)

• Add support for wells that change roles during the simulation. It is possible, although rare, for a well to be introduced as a (shut) producer only to be converted into an injector at some later time.
• Explicitly use first region only when constructing PVT calculators from a scenario featuring multiple PVT regions.
• New function initEclipseModel constructs fundamental MRST objects from an ECLIPSE input deck. Note that the fluid, state, and well objects so produced are NOT compatible with the solvers based on automatic differentiation in the 'ad-fi' module. This function is mostly for use with the old black-oil solvers.

Coarse grids (coarsegrid)

• Function processPartition now accepts a third parameter that specifies particular interfaces that should be excluded from the connection lists when deciding whether or not a particular coarse block is connected.
• New function explosionView plots coarse blocks with an additional separating physical distance to highlight the structure of the coarse grid.

Multiscale finite volume ('msfvm')

Add examples to demonstrate use of the method

Upscaling (upscaling)

Fix a programming error resulting from failure to check the return value of function fopen. Thanks to: Andreas Olsen.

Visualisation (mrst-gui)

New function plotGridBarchart plots bar-charts on top of grids.

Upgrade notes

• Solver module mimetic is no longer activated (loaded) by default.
• The gridtools module that was distributed as part of MRST 2013b has been integrated into MRST Core. Consequently, there is no longer a need to call mrstModule add gridtools to use features of the erstwhile module.
• Function processPartition of the coarsegrid module no longer accepts a Verbose option.
• The grid generator functions (e.g., functions processGRDECL and cartGrid) no longer use integer types (e.g., int32) to represent indices.

Tutorial on the New Module System

The mrstPath function maintains a mapping from module names to system paths. The paths are expected to be full paths to existing directories on the local computer system. Module names can be arbitrary strings, but are typically single words consisting of alphanumeric characters.

Function mrstPath supports three different, though related, modes of operation. The first mode establishes new module mappings. This mode is intended for end-users of MRST. The second mode manipulates the current module mapping list. The third mode is primarily intended for MRST itself. This is the query mode that is used by function mrstModule during mrstModule add to manipulate MATLAB's search path. End users will typically use the third mode to inspect the current list of module mappings.

1. Registering/creating module mappings
   
   Creating a new module mapping is accomplished through the register keyword/verb. As an example, a module named AGMG, located in the S:\mrst\modules\3rdparty\agmg directory, can be registered using the syntax
   
   mrstPath register AGMG S:\mrst\modules\3rdparty\agmg
   
   Once the mapping is established, the module can be activated using
   
   mrstModule add AGMG
   
   Multiple module mappings can be established with a single call to function mrstPath provided the parameters to the register verb constitutes a 2*n-element list of strings in which the odd-numbered elements are interpreted as module names and the even-numbered elements are interpreted as system path names.
   
   As a convenience, function mrstPath supports a special keyword, addroot, that accepts a directory name or a list of directory names and automatically registers module mappings for each of the immediate sudirectories. Specifically, if the directory /repo/mrst/model-IO contains the immediate subdirectories
   • deckformat
   • libgeometry
   • mrst_api
   • spe10
   • triangle
   then the call

   mrstPath addroot /repo/mrst/model-IO
   

   behaves as if the user called

   mrstPath register ...
       deckformat  /repo/mrst/model-IO/deckformat  ...
       libgeometry /repo/mrst/model-IO/libgeometry ...
       mrst_api    /repo/mrst/model-IO/mrst_api    ...
       spe10       /repo/mrst/model-IO/spe10       ...
       triangle    /repo/mrst/model-IO/triangle
   

   Immediate subdirectories named data, deprecated, or experimental (subject to platform conventions) are excluded from this automatic treatment. Therefore, if the MRST user wants to use modules with such names, the module mappings must be input using the register verb.
   
   
2. Manipulating and inspecting the current module mappings
   
   The verbs clear and list respectively removes or outputs (to the Command Window) the currently registered module mapping. The verb remove is a refinement of clear in which only selected modules are removed from the module mapping.
   
   There are two more convenience verbs for manipulating the current mapping. The reregister verb is intended to replace the mapping of one or more modules, e.g., if you're developing a replacement for another module and want to switch between the two for testing purposes. Similarly, the reset verb clears the registry for all modules except those specified as parameters.
   
   
3. Quering the current module mappings
   
   The search keyword queries the module mapping. Its parameters are module names and the return values are the respective system paths. This is the mode that's used during mrstModule add. When called as a command, the mapping is output to the Command Window. When called using function syntax, mrstPath returns a cellstring of corresponding system paths.
   
   We make a special concession to module and script writers. When mrstPath is called without a known verb, the function behaves as if the caller uses search. This enables using mrstPath as a component in more elaborate constructs. A typical use case is to create full, system independent, paths to module-specific data files of the form

   fullfile(mrstPath('ad-fi'), 'data', 'spe1.data')