Using Plugins in TransGen

A plugin is a macro, written in C++, that manipulates the values of cell and connection properties. Plugins are essential to even the most simple TransGen v3 run. The absolute minimum requirement of a "Basic" TransGen project are the automatically generated plugins which calculate fault thickness and permeability, i.e. the THICK and PERM plugins. In a "Flexible" project, the user must include both the THICK and PERM plugins and can use another two plugins (CELLPROP and AREA), while the addition of two-phase functionality to a "Flexible" project can potentially introduce another nine plugins (see Defining Two-phase flow plugins). Alternatively, when using the new option to include fault drag and hierarchical zone effects in a "Flexible" project, the drag applied to fault traces can be defined via the DRAG plugin and/or the FZONE plugin can be used to place fault zones on fault traces.

A TransGen "Basic" project does not allow direct interaction with the plugin source code. The Fault Rock Properties page in WizGen Basic contains relationships governed by equations. The constants contained in the equations can be edited. When the project is saved, two plugins called _AUTO_THICK_PLUGIN.cpp and _AUTO_PERM_PLUGIN.cpp (incorporating these constants) are saved in the <project_name>_INPUT/.plugin sub-directory of the current project directory.

When a TransGen project is converted from "Basic" to "Flexible", the default plugins used to control fault thickness and permeability are copied to new file names, i.e. <project_name>_THICK.cpp and <project_name>_PERM.cpp stored in the same <project_name>_INPUT/.plugin directory. The contents of the two plugins are initially unchanged and therefore the converted "Flexible" project will produce the same results as the preceding "Basic" project. When using TransGen in "Flexible project" mode, any of the plugins can subsequently be edited and re-built via the User-defined plugins page of WizGen.

When a TransGen project is created from new in "Flexible project" mode, a full default suite of plugins are automatically accessed and stored in the <project_name>_INPUT/.plugin directory. Any or all of them can be edited via the User-defined plugins pag e of WizGen.

In summary, each project contains a plugin directory which contains the TransGen default plugin suite and may also contain plugins derived from these defaults and subsequently edited within a "Flexible project". In addition, a directory is provided within the user's home directory to store plugins for general application across several projects.

The four standard plugins are shown below. Both the THICK and PERM plugins are essential to calculate fault rock thickness and fault permeability - ViewGen will stop with an error message if the THICK and PERM plugins are not supplied (except when the Do not calculate fault properties option is toggled "on" via the Miscellaneous Options page in WizGen). The CELLPROP and AREA plugins are not essential.

Summary of the TransGen calculations

The objective of a plugin is to calculate cell or connection properties, based on existing cell or connection properties, using user-defined algorithms. In order to design efficient and numerically robust plugins, it is vital to have some understanding of the TransGen calculations. This section summarises how TransGen calculates fault connection properties and the order in which the various calculations are performed.

Each faulted connection between active cells is stored internally within TransGen as polygons of connected 3D vertices for both cells associated with the connection. Each vertex contains geometric information and fault property data. TransGen automatically calculates and stores displacement, and up to five FSP measures at each vertex of the connection. Fault rock thickness and permeability are also defined at each connection vertex, their values are calculated in the THICK and PERM plugins.

In the diagram below, the two triangular coincident connections A and B perfectly share an edge but the three vertices in A are distinct from the three vertices in B although two vertices from either connection share the same geometric position. The values of the FSP measures calculated at the geometrically similar vertices may be different.

Connection average properties are also calculated and stored. For all vertex properties with the exception of fault rock thickness, the area-weighted arithmetic average is used. For fault rock thickness, an area-weighted harmonic average is used. The graphics viewer provides two options to display some of the items in the fault properties menu - `smooth' or `averaged'. The two displays are drawn directly from the vertex and (averaged) connection values stored within the model respectively.

For certain fault properties (e.g. the area of the connection or its direction) a value at a vertex is meaningless, and only "average" values are stored. User-defined connection properties introduced with the TGNEWKEY keyword are only present in TransGen as connection averages.

The CELLPROP plugin cannot access fault connection information. Only cell properties can be used.

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

The AREA plugin should operate on connection properties as it is called just prior to the transmissibility calculation step and vertex properties are not referenced at this point.

Fault displacement and all FSPs are averaged before the THICK plugin is run. The objective of this plugin is to calculate fault rock thickness at each vertex of each connection. Since it is possible to modify the FSP values at connection vertices, all FSPs as well as fault rock thickness are averaged after the THICK plugin is run (i.e. immediately before the PERM plugin is run). There is no need to average fault displacement again at this stage since it cannot be edited in a plugin.

Similarly, all FSPs as well as both fault rock thickness and fault rock permeability are averaged before running the AREA plugin. Since it is impossible to change connection vertex values in the AREA plugin, no more averaging needs to be done prior to calculating the transmissibilities of the connections.

The CELLPROP plugin

The principle purpose of the CELLPROP plugin is to specify user-defined algorithms for determining (a) the effective Vshale values of cells, and (b) which cells to use to define the shale faces - used in particular FSP calculations. However, any user-defined cell property can be modified in the plugin.

The CELLPROP plugin runs quite early on in the TransGen calculation, after all 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 the CELLPROP plugin.

Only cell properties can be used in this plugin and only with the general "cell" prefix.

The CELLPROP plugin is called once for every grid-block in the model.

The THICK and PERM plugins

The THICK plugin should be used to calculate fault rock thickness and the PERM plugin used to calculate fault rock permeability. Both these plugins MUST be included in the TransGen run file. These plugins are called at every vertex of every active faulted connection in the model. Only cells adjacent to faults are used in calculations in these plugins.

Thickness and permeability MUST be calculated on connection vertices, i.e. v.thick defined as a fraction of v.displ, v.perm calculated as a function of v.sgr.

When using cell properties in the THICK or PERM plugins, any of the 5 cell prefixes (i.e. up, down, min, max, ave) are available for use (but NOT the general "cell" prefix which MUST be used in a CELLPROP plugin and can be used in an AREA plugin).

If a fault property is used to modify the values of a user-defined cell property, the connection average prefix should be used rather than the vertex prefix to define the fault property. This is because these plugins are run on every vertex of the connections, so code such as:-

up.cell_prop1 = v.fsp1;

would continually update the value of cell_prop1 as each vertex is processed and the final value of up.cell_prop1 would simply be assigned the value of fsp1 of the last vertex processed.

The following code is more appropriate as it assigns the same (i.e. the average) value of fsp1 to the cell as each vertex is processed:-

up.cell_prop1 = c.fsp1;

There are, however, exceptions to this advice, similar to those discussed under Outputting properties stored only as connection averages.

As a general rule, however, we recommend that user-defined cell properties are not updated in the THICK and PERM plugins, for the reason discussed in the section on the AREA plugin below.

The AREA plugin

The optional inclusion of the AREA plugin allows modification of the Area term used in the faulted transmissibility equation. For further details refer to the Introduction of the AREA term in the Technical Description of what TransGen does. It can also be used to update user-defined cell properties.

Unlike the THICK and PERM plugins, the AREA plugin is called once per connection. Therefore, only connection average fault properties (e.g. c.area, c.user_connection, c.fsp1) should be used as both input and output.

When using cell properties in the AREA plugin, all 5 cell prefixes (i.e. up, down, min, max, ave) plus the general "cell" prefix (i.e. only cell property prefix useable in a CELLPROP plugin) are available for use.

The reason why user-defined cell properties should be updated in the AREA plugin rather than the THICK or PERM plugins is explained below, with reference to a simple 8 grid-block model.

Cell (1,2,1) is bounded by a fault on two sides and forms connections with 4 other cells. Each of these 4 connections is rectangular and therefore has 4 vertices. Assume we have a particular property for each connection, that this property is additive, and that we want to report the sum of this property as a user-defined cell property (GB1). An example might be the total area of the X and Y edges of each cell that are faulted.

Provided we have not included any values for GB1 and it has not been used in any previous plugins, its value in all cells will be 0.0 (the default). Assume that the area of all the connections in this example is 100 sq.m .

We include the following code in the AREA plugin:-

up.GB1 = up.GB1 + c.area;
down.GB1 = down.GB1 + c.area;

The plugin will be called once for every faulted connection in the model. The first connection involving block (1,2,1) to be called is the one to block (2,2,1). (1,2,1) is the "down" grid-block, and (2,2,1) is the "up" one with respect to this connection. The first line of code will add 100 to the value of GB1 for cell (2,2,1), and the second will update the value of cell (1,2,1). The next connection (between blocks (1,2,2) and (2,2,2)) will add another 100 to block (1,2,1) (through the first line of code) and then update cell (2,2,2) through the second. Continuing the processing will finally give a values of GB1 = 400 for block (1,2,1), 200 for blocks (1,1,2), (1,2,2) and (2,2,2), and 100 for blocks (1,1,1) and (2,2,1). Blocks (2,1,1) and (2,1,2) are not associated with any faulted connections, and therefore the values of GB1 will not be modified from the original value of 0.0.

If the same code were inserted in the PERM or THICK plugins, the final values of GB1 would not be correct, because GB1 would be modified for every vertex of every x y z (1,1,1) (2,1,1) (1,1,2) (1,2,1) (1,2,2) (2,2,1) (2,2,2) x y z (1,1,1) (2,1,1) (1,1,2) (1,2,1) (1,2,2) (2,2,1) (2,2,2) rather than once for every connection. Since there are 4 vertices for every connection in this model, the final value of GB1 for block (1,2,1) would therefore be 1600 rather than 400.

This example serves to illustrate some of the pitfalls associated with calculating cell properties in plugins.