User-defined plugins page

This is the Next >> page accessed in WizGen (in "Flexible project" mode) from the Fault Seal Potential Variables page or by selecting the Goto... button for Add and modify user-defined calculation modules (plugins) from the Contents page.

The User-defined plugins page of WizGen allows the user to:-

create plugin(s) that manipulate the values of cell and connection properties, e.g. to input user-specific algorithms for defining fault rock thickness and fault rock permeability.

optionally create up to nine 2Phase plugins to calculate fault rock properties (the user can specify if a particular two-phase relationship should be based on an equation or a plugin via the Two phase flow - page 2 of WizGen).

optionally create DRAG and/or FZONE plugins to define drag on fault traces and/or to model sub-grid block fault effects based on user-defined criteria.

Initially this page of WizGen opens with the current THICK plugin displayed which will either be that copied from the automatically generated THICK plugin having converted the current TransGen project from "Basic" to "Flexible project" mode or the default THICK plugin for a TransGen project created from new in "Flexible project" mode as shown below.

A Plugin is a macro, written in C++, that manipulates the value of existing cell and connection properties. There are four types of plugin which can be used during TransGen calculations (in Flexible project mode), i.e. CELLPROP, THICK, PERM, AREA plugins, of which two (THICK and PERM plugins) are essential, i.e. Fault-rock thickness and fault permeability MUST be calculated at each vertex in a fault connection via the THICK and PERM plugins in order to calculate the faulted transmissibilities. ViewGen will stop with an error message if the THICK and PERM plugins are not supplied. The CELLPROP and AREA plugins are not essential.

It is important to appreciate the order in which plugins are run: first CELLPROP, then THICK, then PERM and finally AREA.

CELLPROP plugin

The principle purpose of the CELLPROP plugin is to specify user-defined algorithms for determining:-
(a) the effective Vshale of cells for a particular FSP calculation
(b) the cells designated as the shale faces for a particular FSP calculation
However, any user-defined cell property can be modified in the plugin, e.g. a user-defined cell property could be created by combining other cell data.
See example of using the CELLPROP plugin.

NOTE:- The CELLPROP plugin runs early on in the TransGen calculation, after all the include files have been read in and the geometry of the cells has been calculated, but before any faults have been identified. Therefore, fault properties cannot be used in a CELLPROP plugin.

THICK & PERM plugins

These plugins are called at every vertex of every active faulted connection in the model, i.e. only cells adjacent to faults are used in calculations in these plugins.  
The THICK plugin calculates the thickness of the fault rock at each vertex of a fault connection.
The PERM plugin calculates the permeability of the fault rock at each vertex in a fault connection.

Both these plugins MUST be included in the TGDATA run file.

The THICK AND PERM plugins should operate principally on vertices. Fault connection information is available if required (e.g. the direction of the connection, user-defined connection properties).

HINT:- As a general rule, user-defined cell properties should not be updated in the THICK and PERM plugins.

NOTE:- Most connection properties calculated by TransGen are stored internally both as connection vertex properties (e.g. v.fsp1) and as average connection properties (e.g. c.thick). The exception is the connection area, for which a value at the vertex is meaningless. However, user-defined connection properties are only stored as connection averages (e.g. as c.user_defined_connection). There is therefore no v.user_defined_connection definition for use in plugins.

AREA plugin

This plugin allows manipulation of the area of fault connection in the model and is called just prior to calculation of faulted transmissibility.
An AREA plugin cannot access vertex properties as they are not referenced at this point of the TransGen calculations.

See section on Using Plugins in TransGen for further details.

2Phase plugins

When the Include two-phase fault rock calculations option is toggled "on" (via the Title page), three extra pages are added to WizGen and on the second page of these (Two phase flow - FAULT ROCK PROPERTIES) the user can specify if a particular two-phase relationship should be based on an Equation or a user-defined Plugin. When the user selects the Plugin option to define a particular fault rock property, the relevant new plugin complete with default code (i.e. using the equation setting) is added to the User-defined plugins page.

Any or all of the following 9 user-defined plugins can be used in the two-phase flow module:-

PORO_FR plugin - to calculate fault rock porosity

SWOR plugin - to calculate water saturation at irreducible oil

SWC plugin - to calculate connate water saturation

PC_D and PC_I plugins - to calculate capillary pressure in the drainage and imbibition cycles respectively

KRW_D and KRW_I plugins - to calculate relative permeability of water in the drainage and imbibition cycles respectively

KRO_D and KRO_I plugins - to calculate relative permeability of oil in the drainage and imbibition cycles respectively

See the section on Defining Two-phase flow plugins for further details.

Fault drag and hierarchical zone effect plugins

When the Include fault drag and hierarchical zone effect plugins option is toggled "on" (via the Title page), two extra pages (Drag applied to fault traces & Hierarchical fault zone definition) are added to WizGen. On these new pages, the user can choose to define either drag on fault traces and/or to model sub-grid block fault effects according to user-defined criteria in the DRAG and/or FZONE plugin(s). When the user selects the Use a plugin option, the following new plugins complete with default code are added to the User-defined plugins page:-

FZONE plugin - to allow the incorporation of sub-grid block fault effects

DRAG plugin - to allow modelling of drag on fault traces

Fault permeability and fault rock thickness, which are essential to the transmissibility calculations performed in TransGen, MUST be calculated in the PERM and THICK plugins respectively. Other properties can also be calculated in plugins, but there is no obligation to do so. There are default THICK and PERM plugins which can be used as un-edited or modified as required.

1. Select Function

Click on the arrow key to the right of the current Function to access and select from the list, e.g. the THICK function has been chosen to create a plugin to calculate fault rock thickness from displacement.

2. View/edit default THICK plugin

With the Function set to THICK, the default THICK plugin is displayed as shown below.

The default THICK macro displayed in the User-defined plugins window, as shown above, will act in the same way as the default THICK plugin automatically written by WizGen in "Basic project" mode, i.e. fault rock thickness is calculated at each vertex of each faulted connection according to the following expressions:-

If the displacement is less than the defined minimum of 0.001 (i.e. 1mm in metric units), then:-

This cutoff value is included to prevent a thickness at a vertex with zero displacement being set to zero, which would in turn prevent an area-weighted harmonic average being calculated for this connection.

Otherwise fault rock thickness is calculated at each connection vertex as a function of displacement
where the constants `a' and `b' are 0.005882 and 1 respectively:-

You can use the default code unaltered or modify it using section on C++ language use in plugins for guidance.

Cell and Fault variables must be referred to in plugins using the correct format. This is prefix.property where the prefix identifies which internally stored array is being referenced and the property tells C++ which of the internally stored values associated with a particular cell or fault connection is being referenced, e.g. v.displ is the vertex property fault displacement and v.thick is the vertex property fault thickness (see section on Prefix options and properties available to different plugins for further details).

The currently selected Function determines which of the 3 boxes at the bottom right of the page (as shown below) are active for the selection of allowed 2Phase, Cell or Fault variables which can be used in the plugins. So for example, with the plugin Function set to THICK, only the Cell or Fault buttons are active.  To include the Fault variable for displacement in the plugin code, select the relevant position in the code after the relevant fault prefix (e.g. v. for vertex property) and then click on the Fault displ option as shown below.

3. Build Plugin

When the plugin appears to be correct, click on the Build button at the top of the User-defined plugins page.
If there are any identifiable errors in the C++ code or if incorrect variable(s) and/or illegal variable prefixes have been used, error message(s) will be displayed in the window. Click on Return to code to re-display and correct the code.

On successful completion, the "Build Successful" message will be displayed (as shown below).

Click on Return to code to re-display code.

4. Save Plugin

Click on the Save File option to save the compiled plugin to the default file name (<project_name>THICK.cpp) in the subdirectory <project_name>INPUT/.plugin of the current project area.

The File menu contains 4 options:-

Open - to choose an existing plugin file and to display the source code in the User-defined plugins window. This source code can be associated with another plugin type, i.e. CELLPROP, THICK, PERM or AREA and/or edited, compiled (via Build option) and saved to a different plugin filename.

Save - to save any changes to the plugin source code to the file name currently displayed bottom left of the page (e.g. Triangle_PERM.cpp) in the <Project_name>_INPUT/.plugins subdirectory of the current TransGen Project area.

Save As - to save the plugin source code to a different user-defined filename and/or directory. By default, the file selection dialog opens at a directory under the user's home directory called .transgen/plugins. This directory is created the first time TransGen is executed and simply provides a convenient place to store plugins - they may be stored anywhere including a directory common to a group of users who might want to share plugins.

Remove - to erase the contents of the text edit window for either a AREA or CELLPROP Function plugin. The *.cpp file is not deleted and can be re-accessed via the Open option. This option cannot be used for either a THICK or PERM Function plugin as both are needed for a successful TransGen run as shown in the Error message pop-up.

5. Repeat process to create PERM plugin

Select the PERM Function to access the current plugin code. The default code (as shown below) simply sets all fault rock permeabilities to 1mD.

You can use this default code or you can input different code to calculate fault rock permeability as a function of, for example, Shale Gouge Ratio (SGR) using the following expression:-

NOTE:- The SGR must be defined as a FSP measure via the Fault Seal Potential Variables page of WizGen.

HINT:- If the PERM plugin uses any FSP measure which does NOT use all faces as shale faces (i.e. all models in which the Shale definition is NOT set to Based on all cells), care must be taken to ensure permeabilities for undefined (i.e. incalculable) FSP values are assigned appropriate values. Refer to Inactive FSP values in the section on Issues associated with FSP calculations for further details.

Click on Build to compile the newly input code.

When the new plugin has been successfully compiled, click on Return to code and then on Save to save the plugin as <project_name>_PERM.cpp in the <project_name_INPUT/.plugin subdirectory of the project area.  

6. Save plugin settings to TGDATA file

When all the required Plugin(s) have input, built and saved to file(s), click on the Save button (bottom right of window) to add the TGPLUGIN Keyword to the <Project>.TGDATA file, as shown below.
The TGPLUGIN Keyword is followed by single quotes (one string to a line) that associate a plugin name with the full C++ source filename, where the source file contains the plugin code, e.g.

--<PLUGINS+>
`THICK=/home/TGprojects/<project_name>/<project_name>_INPUT/.plugins/<project_name>THICK.cpp'
`PERM=/home/TGprojects/<project_name>/<project_name>_INPUT/.plugins/<project_name>PERM.cpp'
/
--<PLUGINS->

Optionally defining Two-phase flow plugins

If any of the petrophysical fault rock properties in the Two phase flow module are set to be calculated via Plugin (rather than via the default Equation - as set on the Two phase flow - FAULT ROCK PROPERTIES page), refer to the following section to define these plugin(s).

Optionally defining Drag applied to Fault Traces and/or Fault Zone hierarchy via plugins

If the Use a plugin option is selected on either or both of the new WizGen pages (Drag applied to fault traces and/or Hierarchical fault zone definition) to apply stochastic and/or deterministic drag to fault traces and/or define sub-grid block fault zone structure, refer to the following sections to define these plugin(s).

When the THICK and PERM Plugins and optionally any other Plugin the user wants to use in the current TransGen run are set as required, click on Save and then on the Next>> button in the User-defined plugins page to view/edit the Output - simulator input page.

Alternatively, click on the << Back button to return to the Fault Seal Potential Variables page.

Or click on the Contents button to access the Contents page to view/edit any of the current TGDATA file settings, inspect the project's TGDATA file and/or inspect the log generated by last ViewGen calculation.