Introduction

MRST's module system is a simple facility for extending and modifying the feature set. Specficially, the module system enables on-demand activation of advanced features like black-oil simulators, flow diagnostics, or multiscale finite-volume method.

The module system is split in two parts; one which handles mapping module names to system paths and one which uses that mapping to manipulate MATLAB's search path.

Function mrstPath

Function mrstPath maintains the mapping between module names and paths on the local computer system. 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. Note that individual sub-commands in function mrstPath are collectively referred to as "verbs" or "keywords". The two terms are used interchangeably.

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 the command

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 lst 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
   
   
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')
   
   As a special case, typing only mrstPath will output the complete list of current module mappings to the command window and will produce output of the form
   mrstPath
   Currently registered modules
     * ad-blackoil        -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-blackoil
     * ad-core            -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-core
     * ad-fi              -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-fi
     * ad-props           -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-props
     * ad-refactor        -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-refactor
     * ad-unittest        -> S:\repo\mrst\gitbucket\mrst-autodiff\ad-unittest
     * adjoint            -> S:\repo\mrst\gitbucket\mrst-solvers\adjoint
     * agglom             -> S:\repo\mrst\gitbucket\mrst-multiscale\agglom
     * co2lab             -> S:\repo\mrst\gitbucket\co2lab\co2lab
     * co2lab-ad          -> S:\repo\mrst\gitbucket\co2lab\co2lab-ad
     * coarsegrid         -> S:\repo\mrst\gitbucket\mrst-multiscale\coarsegrid
     * deckformat         -> S:\repo\mrst\gitbucket\mrst-model-IO\deckformat
     * dfm                -> S:\repo\mrst\gitbucket\mrst-solvers\dfm
     * diagnostics        -> S:\repo\mrst\gitbucket\mrst-visualization\diagnostics
     * impes              -> S:\repo\mrst\gitbucket\mrst-solvers\impes
     * libgeometry        -> S:\repo\mrst\gitbucket\mrst-model-IO\libgeometry
     * matlab_bgl         -> S:\repo\mrst\gitbucket\mrst-core\utils\3rdparty\matlab_bgl
     * mex                -> S:\repo\mrst\gitbucket\mrst-model-IO\mex
     * mimetic            -> S:\repo\mrst\gitbucket\mrst-solvers\mimetic
     * mpfa               -> S:\repo\mrst\gitbucket\mrst-solvers\mpfa
     * mrst-gui           -> S:\repo\mrst\gitbucket\mrst-visualization\mrst-gui
     * mrst_api           -> S:\repo\mrst\gitbucket\mrst-model-IO\mrst_api
     * msfvm              -> S:\repo\mrst\gitbucket\mrst-multiscale\msfvm
     * msmfem             -> S:\repo\mrst\gitbucket\mrst-multiscale\msmfem
     * opm_gridprocessing -> S:\repo\mrst\gitbucket\mrst-model-IO\opm_gridprocessing
     * spe10              -> S:\repo\mrst\gitbucket\mrst-model-IO\spe10
     * streamlines        -> S:\repo\mrst\gitbucket\mrst-visualization\streamlines
     * triangle           -> S:\repo\mrst\gitbucket\mrst-model-IO\triangle
     * upscaling          -> S:\repo\mrst\gitbucket\mrst-multiscale\upscaling

Function mrstModule

The mrstModule function queries and modifies the list of currently active add-on modules. A particular module feature cannot be used unless the corresponding module is active. Moreover, the module system is a simplistic wrapper around MATLAB's built-in search path feature so if two modules contain a feature (e.g., a function) with the same name, then the module that's first in the search path is the one that gets used. Individual sub-commands in function mrstModule are collectively referred to as "verbs" or "keywords"

1. Activating a particular module
   
   Function mrstModule's add