MULgraph geometry file format#

Introduction#

This section gives a format specification of the MULgraph geometry file. These files can be used to give a geometrical description of a TOUGH2 model grid, useful for creating grids and visualizing simulation results.

MULgraph geometry files were originally developed for use with MULgraph, a graphical interface for TOUGH2 and AUTOUGH2 developed at the University of Auckland in the 1990s, and subsequently adopted by the TIM graphical interface. However, MULgraph geometry files can be used independently of MULgraph or TIM. PyTOUGH is able to represent the contents of a MULgraph geometry file in a Python script via the mulgrid class.

Grid structure#

Layers and columns#

MULgraph geometry files implicitly assume a layered structure, with blocks arranged in layers and columns, and the same arrangement of columns in each layer. The only exception to this is at the top surface of the model, where layers are allowed to be incomplete (i.e. not contain all columns) in order to represent topography.

The layers are always of constant vertical thickness. However, the blocks in the top layer are allowed to vary in height, again to represent variations in ground surface elevation.

Atmosphere blocks#

The blocks in the top layer may optionally be connected to the atmosphere- either a single atmosphere block connected to all columns, or a separate atmosphere block over each column (see Naming conventions and atmosphere types).

Tilted geometries#

It is possible to tilt the geometry coordinate axes with respect to the vertical, to represent non-horizontal geometries. When a TOUGH2 grid is created from such a tilted geometry, only the gravity cosines of the grid connections are affected.

Rotating permeability directions#

It is also possible to rotate the permeability principal directions with respect to the coordinate axes- for example, to align permeabilities with a dominant fault direction. When a TOUGH2 grid is created, this can change the permeability index associated with each connection.

Geometry types#

The original MULgraph file specification allowed for three types of geometry: ‘general’, ‘rectangular’ and ‘radial’. Only the ‘general’ geometry type is supported by PyTOUGH. It is intended for representing general grids with arbitrary, possibly unstructured horizontal column arrangements.

The ‘rectangular’ type was a special type for grids with rectangular horizontal column structures. These can also be represented using the ‘general’ geometry type. Since PyTOUGH contains methods for constructing rectangular grids within the ‘general’ geometry type, there is usually no longer any significant benefit from using the ‘rectangular’ type.

The ‘radial’ type was intended for grids with radial horizontal column structure. PyTOUGH also contains methods for creating radial TOUGH2 grids. Simulation results from radial models can also be visualized using a simple one- or two-dimensional rectangular ‘general’ geometry to represent the grid structure in the radial direction.

Naming conventions and atmosphere types#

The grid block naming convention and atmosphere type used in a MULgraph geometry file are both integers and can be given values in the range 0 – 3 and 0 – 2 respectively. The meanings of these values are shown in the tables below.

Note that the grid nodes (vertices) are also named according to the column part of the block naming convention. If naming nodes, columns or layers manually, while the names can in principle be arbitrary (within the naming convention), it is safest to right-justify them.

The MULgraph block naming conventions all use part of the block name to indicate the layer, and part of it to indicate the column. In PyTOUGH, it is also possible to use MULgraph geometry files in conjunction with TOUGH2 grids that follow other naming conventions, by means of a block mapping dictionary.

Block naming convention 3 was not supported by the original MULgraph geometry file format, and produces block names which do not conform to the TOUGH2 block naming requirements (having numbers in the last two characters). It can be used to produce grids for other simulators such as Waiwera which do not have these requirements. An alternative tool for creating such grids is the Layermesh library.

MULgraph geometry file naming conventions#

Convention

Meaning

0

3 characters for column followed by 2 digits for layer

1

3 characters for layer followed by 2 digits for column

2

2 characters for layer followed by 3 digits for column

3

3 characters for column followed by 2 characters for layer
MULgraph geometry file atmosphere types#

Type

Meaning

0

A single atmosphere block

1

One atmosphere block over each column

2

No atmosphere blocks

File format#

MUlgraph geometry files are simple formatted ASCII text files with a header line at the top, followed by a number of sections. Each section begins with a keyword and ends with a blank line. Each line has fixed format, so the different values have to be specified in the right text columns.

If you use PyTOUGH scripts to create and manipulate your grid geometries, you don’t need to know anything about the format of a MULgraph geometry file, because PyTOUGH will handle reading and writing them for you. If, however, for some reason you do need to know how these files are structured, the format specification for a ‘general’ type geometry file is given below.

Vertices#

This section defines the horizontal locations of the grid vertices (nodes), at the corners of the columns. The first line just contains the keyword ‘VERTI’. Each subsequent line defines the position of a vertex, and has the format given in the table below. The vertices section is terminated by a blank line.

MULgraph geometry file vertices format#

Name

Type

Length

Columns

Description

Vertex name

character

3

1–3

Name of the vertex (honouring the column naming convention

x

float

10

4–13

x-coordinate of the vertex

y

float

10

14–23

y-coordinate of the vertex

Grid#

This section specifies the vertices making up each column. The first line just contains the keyword ‘GRID’.

For each grid column, there is then a sub-header line with information about the column, followed by a line for each vertex making up the column. The lines for the sub-header and each vertex have the formats given in the tables below. There are no blank lines between the definitions of the grid columns, but there is a blank line at the end of the section.

MULgraph geometry file column header format#

Name

Type

Length

Columns

Description

Column name

character

3

1–3

Name of the column (honouring the column naming convention)

Centre specified

integer

1

4–5

Set non-zero to specify the column centre location, or zero (default) to calculate it as the centroid of the column

Number of vertices

integer

2

6–7

Number of vertices in the column

Column centre x

float

10

8–17

x-coordinate of column centre

Column centre y

float

10

18–27

y-coordinate of column centre
MULgraph geometry file column vertex format#

Name

Type

Length

Columns

Description

Vertex name

character

3

1–3

Name of the vertex, as specified in the vertices section

Connections#

This section defines the horizontal connections between columns. The first line just contains the keyword ‘CONNE’.

Each subsequent line defines a connection between two columns, and has the format given in the table below. There is a blank line at the end of the section.

MULgraph geometry file connection format#

Name

Type

Length

Columns

Description

First column name

character

3

1–3

Name of the first column

Second column name

character

3

4–6

Name of the second column

Layers#

This section defines the grid layers. The first line just contains the keyword ‘LAYER’.

Each subsequent line defines a layer, with format given in the table below. There are no blank lines between layers, but there is a blank line at the end of the section.

MULgraph geometry file layer format#

Name

Type

Length

Columns

Description

Layer name

character

3

1–3

Name of the layer (honouring the layer naming convention)

Bottom elevation

float

10

4–13

Elevation of the bottom of the layer

Centre elevation

float

10

14–23

Elevation of the centre of the layer

Surface elevation#

This section is optional, and can be used to define the surface elevation at any or all columns in the grid, to represent topography. The first line just contains the keyword ‘SURFA’.

Each subsequent line defines the surface elevation at a column, with format given in the table below. There is a blank line at the end of the section.

MULgraph geometry file surface elevation format#

Name

Type

Length

Columns

Description

Column name

character

3

1–3

Name of the column

Surface elevation

float

10

4–13

Surface elevation of the column

Wells#

This section is optional, and can be used to define the positions of wells (including their tracks) within the geometry. Deviated wells are supported. The first line of the section just contains the keyword ‘WELLS’.

Each subsequent line defines the location of one point on a well track, with format given in the table below. At least two points are required to define each well (one for the wellhead and one for the bottom), with more than two points needed to define a deviated well. There is a blank line at the end of the section.

MULgraph geometry file well format#

Name

Type

Length

Columns

Description

Well name

character

5

1–5

Name of the well

x

float

10

6–15

x-coordinate of the well location

y

float

10

16–25

y-coordinate of the well location

z

float

10

26–35

z-coordinate of the well location