hgs simulations is a product of aquanty inc. · 2.hgs is run to solve the problem and generate...

HGS Simulations is a product of Aquanty Inc.564 Weber Street North, Unit 2Waterloo, Ontario N2L 5C6

This manual documents HydroGeoSphere (HGS) version 2166.

Copyright © 2015, Aquanty Inc. All rights reserved.

This publication is a product of Aquanty Inc. and may not be reproduced either commer-cially or non-commercially by any means including but not limited to electronic replication,photocopy, or mechanical replication without direct written permission from Aquanty Inc.

Permissions may be sought directly from Aquanty Inc:Phone: 1-855-aquantyFax: (519) 279-1081Email: [email protected]

Contents

1 Quick Start Guide 1

1.1 HGS Installation Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Key Executable Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.1 Grok (grok.exe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.2 HGS (phgs.exe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.3 HSPLOT (hsplot.exe) . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3 Running a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Input/Output Instructions 5

2.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.1.1 File Process Control Options . . . . . . . . . . . . . . . . . . . . . . 9

2.1.2 Units and Physical Constants . . . . . . . . . . . . . . . . . . . . . . 10

2.1.3 Pre-Processor Considerations . . . . . . . . . . . . . . . . . . . . . . 12

2.1.3.1 Array Dimensioning . . . . . . . . . . . . . . . . . . . . . . 12

2.2 Problem Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.3 Grid Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3.1 Simple Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3.2 Interactive Block Grids . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.3.3 3-D Random Fracture Generator for Block Grids . . . . . . . . . . . 18

2.3.4 2-D Random Fracture Generator . . . . . . . . . . . . . . . . . . . . 21

2.3.5 Interactive 3-D Mesh Generator . . . . . . . . . . . . . . . . . . . . 29

2.3.5.1 Defining a 2-D Mesh . . . . . . . . . . . . . . . . . . . . . . 29

i

CONTENTS ii

2.3.5.2 3-D Mesh Generation . . . . . . . . . . . . . . . . . . . . . 32

2.3.5.3 Adding a New Layer . . . . . . . . . . . . . . . . . . . . . . 33

2.3.5.4 Elevation Instructions . . . . . . . . . . . . . . . . . . . . . 36

2.3.6 Tetrahedral Element Grids . . . . . . . . . . . . . . . . . . . . . . . 38

2.3.7 Axisymmetric Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

2.3.8 Reading an Existing 3-D Grid . . . . . . . . . . . . . . . . . . . . . . 39

2.3.9 Manipulating the 3-D Grid . . . . . . . . . . . . . . . . . . . . . . . 41

2.3.10 Grid Projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

2.3.11 Ending Grid Generation . . . . . . . . . . . . . . . . . . . . . . . . . 43

2.4 Selecting Mesh Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

2.4.1 Selecting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

2.4.2 Selecting Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

2.4.3 Selecting Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

2.4.4 Selecting Inclined Faces . . . . . . . . . . . . . . . . . . . . . . . . . 63

2.4.5 Selecting Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

2.5 Simulation Control Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

2.5.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

2.5.1.1 Finite-Difference Options . . . . . . . . . . . . . . . . . . . 72

2.5.1.2 Matrix Solver . . . . . . . . . . . . . . . . . . . . . . . . . 72

2.5.2 Timestep Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

2.5.2.1 Adaptive Timesteps . . . . . . . . . . . . . . . . . . . . . . 76

2.5.3 Saturated Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

2.5.4 Variably-Saturated Flow . . . . . . . . . . . . . . . . . . . . . . . . . 80

2.5.4.1 Newton Iteration Parameters . . . . . . . . . . . . . . . . . 81

2.5.5 Discrete Fracture Flow . . . . . . . . . . . . . . . . . . . . . . . . . 86

2.5.6 Surface Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

2.5.7 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

2.5.8 Density-Dependent Flow Solution . . . . . . . . . . . . . . . . . . . 90

2.5.9 Heat Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

CONTENTS iii

2.5.10 Inactive Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

2.6 Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

2.6.1 Subsurface Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

2.6.2 Surface Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

2.6.3 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

2.6.3.1 Solute Definition . . . . . . . . . . . . . . . . . . . . . . . . 108

2.6.3.2 Travel Time Probability . . . . . . . . . . . . . . . . . . . 120

2.6.3.3 Heat Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 120

2.6.3.4 Auxiliary Features . . . . . . . . . . . . . . . . . . . . . . . 123

2.7 Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

2.7.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

2.7.2 Set Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

2.7.3 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

2.7.3.1 Specified Head . . . . . . . . . . . . . . . . . . . . . . . . . 126

2.7.3.2 Specified Flux . . . . . . . . . . . . . . . . . . . . . . . . . 128

2.7.3.3 Fluid Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 132

2.7.3.4 Free Drainage . . . . . . . . . . . . . . . . . . . . . . . . . 133

2.7.3.5 Potential Evapotranspiration . . . . . . . . . . . . . . . . . 134

2.7.3.6 River Flux . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

2.7.3.7 Drain Flux . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

2.7.3.8 Makeup Water . . . . . . . . . . . . . . . . . . . . . . . . . 137

2.7.3.9 Surface Loading . . . . . . . . . . . . . . . . . . . . . . . . 138

2.7.3.10 Hydromechanical Stress . . . . . . . . . . . . . . . . . . . . 139

2.7.3.11 Surface Flow . . . . . . . . . . . . . . . . . . . . . . . . . 140

2.7.3.12 Snowmelt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

2.7.4 Node and Face Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

2.7.5 Time-Varying Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

2.7.5.1 Interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . 147

2.7.5.2 Scaling Factor . . . . . . . . . . . . . . . . . . . . . . . . . 147

CONTENTS iv

2.7.5.3 Intermittent Conditions . . . . . . . . . . . . . . . . . . . . 148

2.7.6 Tecplot Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

2.7.7 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

2.7.7.1 Specified Concentration . . . . . . . . . . . . . . . . . . . . 150

2.7.7.2 Specified Mass Flux . . . . . . . . . . . . . . . . . . . . . . 151

2.7.7.3 Specified Third-Type Concentration . . . . . . . . . . . . . 152

2.7.7.4 Thermal Energy . . . . . . . . . . . . . . . . . . . . . . . . 156

2.7.7.5 Immiscible Phase Dissolution Source . . . . . . . . . . . . . 160

2.7.7.6 Zero-Order Source . . . . . . . . . . . . . . . . . . . . . . . 161

2.8 Materials and Material Properties . . . . . . . . . . . . . . . . . . . . . . . 162

2.8.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

2.8.1.1 Defining a New Zone . . . . . . . . . . . . . . . . . . . . . 163

2.8.1.2 Saving and Retrieving Element Zone Numbers . . . . . . . 164

2.8.1.3 Defining New Zones Using ArcView Files . . . . . . . . . . 166

2.8.1.4 Selecting Zones . . . . . . . . . . . . . . . . . . . . . . . . . 168

2.8.1.5 Modifying Zoned Properties . . . . . . . . . . . . . . . . . . 168

2.8.2 Saturated Subsurface Flow . . . . . . . . . . . . . . . . . . . . . . . 172

2.8.2.1 Porous Medium . . . . . . . . . . . . . . . . . . . . . . . . 172

2.8.2.2 Discrete Fractures . . . . . . . . . . . . . . . . . . . . . . . 185

2.8.2.3 Dual Continuum . . . . . . . . . . . . . . . . . . . . . . . . 191

2.8.2.4 Wells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

2.8.2.5 Tile Drains . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

2.8.2.6 Channel Flow . . . . . . . . . . . . . . . . . . . . . . . . . 201

2.8.2.7 Cutoff Walls . . . . . . . . . . . . . . . . . . . . . . . . . . 207

2.8.2.8 Imported from FRACTRAN . . . . . . . . . . . . . . . . . 207

2.8.3 Variably-Saturated Subsurface Flow . . . . . . . . . . . . . . . . . . 208

2.8.3.1 Porous Medium . . . . . . . . . . . . . . . . . . . . . . . . 208


2.8.3.3 Dual Continuum . . . . . . . . . . . . . . . . . . . . . . . . 211

CONTENTS v

2.8.3.4 Functional Constitutive Relationships . . . . . . . . . . . . 213

2.8.3.5 Tabular Constitutive Relationships . . . . . . . . . . . . . 219

2.8.4 Surface Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

2.8.5 Evapotranspiration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

2.8.6 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

2.8.6.1 Porous Medium . . . . . . . . . . . . . . . . . . . . . . . . 233


2.8.6.3 Dual Continuum . . . . . . . . . . . . . . . . . . . . . . . . 238

2.8.6.4 Surface Runoff . . . . . . . . . . . . . . . . . . . . . . . . . 240

2.9 Winter Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

2.9.1 Groundwater Flow with Freezing and Thawing of Pore Water . . . 242

2.10 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

2.10.1 Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

2.10.1.1 GMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

2.10.1.2 Tecplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

2.10.2 Flow Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

2.10.2.1 Observation Wells and Points . . . . . . . . . . . . . . . . 252

2.10.2.2 Fluid Mass Balance . . . . . . . . . . . . . . . . . . . . . . 254

2.10.3 Surface Flow Hydrographs . . . . . . . . . . . . . . . . . . . . . . . . 257

2.10.4 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

2.10.4.1 Observation Wells and Points . . . . . . . . . . . . . . . . 260

2.10.4.2 Solute Mass Balance . . . . . . . . . . . . . . . . . . . . . . 261

2.10.4.3 Travel Time Probability . . . . . . . . . . . . . . . . . . . 263

References 265

A Output Files 266

B Run-Time Debug Utility 272

C Run-Time Timestep Output 278

CONTENTS vi

C.1 Simulation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

C.2 Summary of the Nonlinear Iteration . . . . . . . . . . . . . . . . . . . . . . 279

C.3 Adaptive Timestep Update . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

D HSBATCH: Batch Run Utility 282

E HSPLOT: Visualization Post-Processor 286

E.1 Output Format Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

E.2 Porous Media Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

E.3 Dual Continuum Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

E.4 Discrete Fracture Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

E.5 Surface Flow Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

F Raster File Formats 294

Index 296

List of Figures

2.1 Element types and local node numbering conventions. . . . . . . . . . . . . 15

2.2 Example grid that was created using Generate blocks interactive instructions. 18

2.3 Default random fracture distribution. . . . . . . . . . . . . . . . . . . . . . . 28

2.4 Example of an irregular fracture network. . . . . . . . . . . . . . . . . . . . 28

2.5 Mesh in geographic coordinates (lat/long). The map of Canada is shown as areference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

2.6 Mesh using Albers equal-area projection. The map of Canada now showsmuch less distortion but the elements are deformed. . . . . . . . . . . . . . 44

2.7 Definition of a parent solute with zoned properties. . . . . . . . . . . . . . . 119

2.8 Definition of a daughter solute with zoned properties. . . . . . . . . . . . . 120

2.9 Example of a porous media domain property file prefix.mprops. . . . . . . 170

2.10 Example output for a porous media material. . . . . . . . . . . . . . . . . . 171

2.11 Example of fracture generation showing 3-D porous medium domain (greycube), Tecplot triangles (yellow triangles), and the resulting fracture elements(blue triangles). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

2.12 Example of a well domain property file prefix.wprops. . . . . . . . . . . . . 195

2.13 Example of a tile drain domain property file prefix.tprops. . . . . . . . . . 199

2.14 Example of a channel domain property file prefix.cprops. . . . . . . . . . . 204

2.15 Example of using functional parameters to generate tabular constitutiverelationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

2.16 Normalized root depth functions. . . . . . . . . . . . . . . . . . . . . . . . . 228

2.17 Example of fluid balance information written to file prefixo.lst. . . . . . . 255

2.18 Example of solute mass balance information written to file prefixo.lst. . . 262

vii

LIST OF FIGURES viii

B.1 Sample contents of debug.control file. . . . . . . . . . . . . . . . . . . . . 273

B.2 Modified debug.control file. . . . . . . . . . . . . . . . . . . . . . . . . . . 273

C.1 Run-time timestep output for the Abdul verification problem. . . . . . . . . 279

E.1 Example output of instruction Write fracture elements to 3d domain file. . . 293

List of Tables

2.1 Default values for 2-D random fracture orientation. . . . . . . . . . . . . . . 23

2.2 Default values for 2-D random fracture aperture. . . . . . . . . . . . . . . . 24

2.3 Default values for 2-D random fracture length, log-normal distribution. . . 24

2.4 Default values for 2-D random fracture length, exponential distribution. . . 25

2.5 Default values for porous media saturated flow properties. . . . . . . . . . . 173

2.6 Default values for fractured media saturated flow properties. . . . . . . . . 185

2.7 Default values for dual-continuum saturated flow properties. . . . . . . . . 191

2.8 Default values for well properties. . . . . . . . . . . . . . . . . . . . . . . . . 194

2.9 Default values for tile drain properties. . . . . . . . . . . . . . . . . . . . . . 198

2.10 Default values for channel properties. . . . . . . . . . . . . . . . . . . . . . 201

2.11 Default values for functions defining the porous media constitutive relation-ships, for the Van Genuchten and Brooks–Corey models. . . . . . . . . . . . 209

2.12 Default pressure-saturation and saturation-relative permeability tables forvariably-saturated porous media. . . . . . . . . . . . . . . . . . . . . . . . . 209

2.13 Default values for functions defining the discrete fracture constitutive rela-tionships, for the Van Genuchten and Brooks–Corey models. . . . . . . . . 210

2.14 Default pressure-saturation and saturation-relative permeability tables forvariably-saturated discrete fractures. . . . . . . . . . . . . . . . . . . . . . . 210

2.15 Default pressure-effective area table for variably-saturated discrete fracturedmedia. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

2.16 Default values for functions defining the dual continua constitutive relation-ships, for the Van Genuchten and Brooks–Corey models. . . . . . . . . . . . 212

2.17 Default pressure-saturation and saturation-relative permeability tables forvariably-saturated dual continua. . . . . . . . . . . . . . . . . . . . . . . . . 212

ix

LIST OF TABLES x

2.18 Default properties for surface flow. . . . . . . . . . . . . . . . . . . . . . . . 221

2.19 Default properties for evapotranspiration. . . . . . . . . . . . . . . . . . . . 224

2.20 Observed values of leaf area index [Scurlock et al., 2001] and maximumrooting depth [Canadell et al., 1996] for various terrestrial biomes. . . . . . 227

2.21 Default values for porous media transport properties. . . . . . . . . . . . . . 233

2.22 Default values for discrete fracture transport properties. . . . . . . . . . . . 238

2.23 Default values for dual-continua transport properties. . . . . . . . . . . . . 239

2.24 Default values for surface flow transport properties. . . . . . . . . . . . . . 240

Chapter 1

Quick Start Guide

The goal of this guide is to get you up to speed quickly on the basic operation of Hydro-GeoSphere (HGS). The topics covered include:

• The HGS installation folder.

• A brief overview of the key executable files (grok.exe, phgs.exe, hsplot.exe).

• Running a model.

1.1 HGS Installation Folder

By default HGS is installed in the directory:

C:\Program_Files\HydroGeoSphere

The installation folder contains the key executable files (grok.exe, phgs.exe, hsplot.exe)required for simulation and results post-processing. Folders within the installation directoryinclude:

• docs: This folder contains the Theory and Reference Manuals which are importantreferences for model setup.

• illustration and verification: These folders contain example problems, some of whichare discussed in the Theory Manual.

Note that in order to run the HGS executable phgs.exe, a valid HGS license file hgs.licmust be present in the installation directory.

1

CHAPTER 1. QUICK START GUIDE 2

1.2 Key Executable Overview

There are three steps required to setup, simulate, and view the results of a simulation.

1. A data file is prepared for the pre-processor (called grok) which is then run to generatethe input data files for HGS.

2. HGS is run to solve the problem and generate output data files.

3. Depending on the problem, post-processing of the data is completed using HSPLOT,to convert the data into a Tecplot compatible format for visualization and analysis.

1.2.1 Grok (grok.exe)

The grok input file contains all of the information and instruction required for the HGSsimulation. This file name consists of a meaningful prefix (up to 40 characters) to which theextension .grok is appended. For example, if the problem prefix created by the user is test,then the general input file created by the user will be test.grok. Information containedwithin the grok file includes mesh definition, model parameterization, initial conditions,boundary conditions, convergence criteria, and simulation output criteria. The pre-processor,grok, performs its task in the following order:

1. Read and allocated default array sizes.

2. Read the problem identification information.

3. Read instructions for generating the grid.

4. Perform grid modifications if necessary.

5. Generate default properties for all parameters.

6. Read optional instructions for modifying the default parameters.

7. Write the HGS-compatible data types.

Once the *.grok file has been built by the user it is compiled by running grok.exe. A moredetailed description of grok and its associated commands are contained in Chapter 2 ofthis document. We note that *.grok files in the illustration and verification folders are anexcellent resource for reviewing grok structure and the use of grok commands.

1.2.2 HGS (phgs.exe)

After the execution of grok.exe, which writes all the HGS-compatible data files, phgs.exe isexecuted to perform the model simulation. There is little user involvement at this stageother than the configuration of the parallel execution details in the file parallelindx.dat.


The file parallelindx.dat does not exist, phgs.exe will create it when it is launched. Thisfile tells phgs.exe how many processors to use the simulation. By default parallelindx.datis created assuming the simulation is being performed in serial mode, i.e., 1 processor.

__Number_of_CPU1

__Num_Domain_Partitiong1

__Solver_Type1

__Coloring_InputF

__Wrting_Output_Time-1.00000000000000

__Simulation_Restart1

To increase the level of parallelization, change the values of ‘‘ Number of CPU’’ and‘‘ Num Domain Partitiong’’ (these values should be the same). When setting these valuesit is important to make sure you don’t exceed the number of processors available on yourmachine. In general we recommend that at most you use up to two fewer than the totalnumber available. For example, if your machine has 8 processors, we recommend that youuse up to 6 if you plan on using the machine for other tasks. Note that when the number ofCPUs requested is greater than 1, the solver type must be changed to 2.

The following example shows how the parallelindx.dat file would be set up to use 6processors for a simulation.

__Number_of_CPU6

__Num_Domain_Partitiong6

__Solver_Type2

__Coloring_InputF

__Wrting_Output_Time-1.00000000000000

__Simulation_Restart1

You do not have to wait for phgs.exe to generate the parallelindx.dat file each timeyou run a simulation. You can copy the file from a previous simulation to your currentmodel folder. Changing parallelindx.dat while the simulation is running will not affect


the number of processors being used. To change the level of parallelization it is necessary tostop and restart the simulation.

1.2.3 HSPLOT (hsplot.exe)

The executable hsplot.exe is used the post-process the simulation results for viewing inTecplot. HSPLOT can be executed during an HGS run or following its completion. Theresulting surface (*o.olf.dat) and subsurface output files (*o.pm.dat) can be opened inTecplot to view the simulation results in three dimensions.

1.3 Running a Model

We conclude this chapter by describing the steps to run the Abdul model problem, themodel files for which can be found in

C:\Program_Files\HydroGeoSphere\verification\abdul

For additional details on this problem the user is referred to the Verification Exampleschapter of the Theory Manual. The steps to run this model problem are as follows.

1. Copy grok.exe, phgs.exe, and hsplot.exe to C:\Program_Files\HydroGeoSphere\verification\abdul.

2. Run grok.exe.

3. Run phgs.exe.

4. Run hsplot.exe.

5. Open abdulo.olf.dat and abdulo.pm.dat with Tecplot to view the simulation re-sults.

Note that Windows 10 users (or, users that receive a dll error when running phgs.exe) shouldcopy the dll files from the installation folder to the current simulation folder. Alternatively,Windows users can add the directory C:\Program_Files\HydroGeoSphere to their systempath. Note that appending to the system path makes it possible to run a model from anyfolder without copying any HGS executable files or dll files to that folder.

Chapter 2

Input/Output Instructions

2.1 General

Before presenting in detail the input data needed for the numerical simulations, some generalinformation about the format and nature of the input data is first given.

There are two steps involved in solving a given problem. First, a data file is preparedfor the pre-processor (called grok1) which is then run to generate the input data files forHydroGeoSphere. Second, HydroGeoSphere is run to solve the problem and generateoutput data files.

The grok input file name consists of a meaningful prefix of up to 40 characters to whichthe extension .grok is appended. This prefix will determine the input and output filenames.The grok listing file name will be the problem prefix to which the letter o and the fileextension .eco are appended. For example, if the problem prefix specified by the user istest, the general input file to be created by the user will be test.grok and the outputlisting, or echo, file generated by the pre-processor will be testo.eco. Some simulationswill require more than one input file (e.g. initial heads read from file) and will result in thegeneration of more than one output file. As a rule, all input files needed during a specificsimulation will have the problem prefix plus a given extension as filename while all generatedoutput files will have the problem prefix, the letter o, plus a given extension as filename.

Throughout the manual, we will adopt the convention of using italics to indicate problem-dependent, user-defined portions of filenames (e.g. prefix, species name etc.) and typewriterfont to indicate invariant portions generated by HydroGeoSphere. For example, in thefilename prefixo.conc.species.0001 the prefix and species portions would be the user-

1grok /grok/, var. /grohk/ vt. [from the novel ‘‘Stranger in a Strange Land’’, by Robert A. Heinlein,where it is a Martian word meaning literally ‘to drink’ and metaphorically ‘to be one with’] The emphaticform is ‘grok in fullness’. 1. To understand, usually in a global sense. Connotes intimate and exhaustiveknowledge. Contrast zen, which is similar supernal understanding experienced as a single brief flash. Seealso glark. 2. Used of programs, may connote merely sufficient understanding. ‘‘Almost all C compilers grokthe void type these days.’’

5

CHAPTER 2. INPUT/OUTPUT INSTRUCTIONS 6

defined prefix and name of a solute, or species, while the o.conc. and .0001 portions wouldbe generated by HydroGeoSphere automatically.

After the pre-processor starts executing, it prompts the user to enter the prefix for theproblem interactively from the keyboard. For cases in which the same input file is beingused repeatedly, you can create a file called batch.pfx which consists of a single line whichcontains the problem prefix. If the file is present, the prefix will automatically be read fromthe file and you will not be prompted to enter it from the keyboard. This file should beplaced in the same directory as the prefix.grok file.

Briefly, the pre-processor performs its tasks in the following order:

1. Read and allocate default array sizes

2. Read problem identification information

3. Read instructions for generating grid

4. Perform grid modifications if necessary

5. Generate default properties for all parameters

6. Read optional instructions for modifying the default parameters

7. Write the HydroGeoSphere-compatible data files

Tasks 3 and 6 are guided by instructions issued by the user in the prefix.grok file. Thegeneration of a complete set of default data by Task 5 tends to minimize the amount ofdata which must be supplied by the user.

Here is an example instruction and some input data which illustrates some common conven-tions that will be used throughout the manual:

Example instruction text1. xl, nbx Domain length and number of blocks in the x-direction.

2. xi(i), i=1,nx x-coordinates of the nx nodes.

3. inode(i)...end Node numbers.

• • •

The pre-processor instruction is separated from the preceding text by a horizontal line, andis written using the sans serif font. It must be typed in the prefix.grok file exactly as shown,with the exception that it is not case-sensitive, and blanks before and after the instructionare optional. Note that only one blank is allowed between any two words in an instruction.


If the instruction requires input data, there will follow a series of numbered lines, eachcontaining boldfaced variable names and a description of what is to be read. Eachnumbered line will correspond to one or more Fortran read statements.

Usually, the number of items required in the data file are indicated by how many boldfacedvariable names are present on the line. The default Fortran variable naming conventionsare in effect. This means variables starting with the letters I–N inclusive require integervalues, while all the rest require real values, unless stated otherwise in the case of string orlogical variables. Numerical values are read in free-format so integers and reals do not needto be lined up in columns and they can be separated by blanks or commas. A descriptivecomment can be included inline after the last data value has been read from the line, butshould be avoided when reading character strings (e.g. file names).

In this example, three items of input are required. The first item xl, nbx requires that theuser enter a real value (i.e. domain length) followed by an integer value (i.e. number ofblocks) on the first non-blank or uncommented line following the instruction.

The second item xi(i), i=1,nx reads nx real values into the array xi. The size of nx isproblem dependent (e.g. number of nodes in x, number of species, etc.) and it is up to theuser to supply enough values to satisfy the read statement. The values may be entered onone line or spread out over multiple lines as desired. If they are entered on one line, theyshould be separated by spaces or commas.

Finally, the third item inode(i)...end indicates a list, in this case of node numbers, that isto be read until an end instruction is encountered. The list values must be entered one perline.

The end of the documentation that pertains to a specific instruction is designated by threedots: • • •.

So for this example instruction, assuming that nx is equal to 5, the following statements inthe prefix.grok file would satisfy the input requirements:

Example instruction text10.0 1000.0 2.0 4.0 6.0 8.0 10.012356end

Some instructions are controlled by input routines that have their own subset of inputinstructions, some or all of which may be optional. For example, the instruction Solute isused to define a new solute and in its simplest form appears as:

Solute


end

In this case, the End instruction immediately follows the Solute instruction, and no optionalinstructions have been issued. The End statement is required so that grok knows when toexit the solute definition routine. Such instructions will be indicated using the followingconvention:

Example instruction text...End

• • •

where the text ...End indicates that the instruction (e.g. Solute) will be followed by optionalinstructions or input and terminated by an End instruction.

Before grok processes instructions contained in a prefix.grok or a material properties file(see Section 2.8.1.5) it first makes a working copy of the file in which any line which iscompletely blank or which begins with an exclamation point (!) is removed and in whichthe contents of any included file are copied. This allows you to include blank lines andcomments when and where required to improve the readability and clarity of the input.

Included files can be used to avoid having to cut and paste or comment and uncommentlarge sections of input instructions. Long lists (e.g. of node numbers or boundary conditiondata) and cases where various different grid generation approaches are being tried aregood candidates for application of the include feature. For example, if we wanted to useinclude to supply data to the example given above, we could use the following instruction inprefix.grok:

Example instruction text10.0 1000.0 2.0 4.0 6.0 8.0 10.0include my.node_list

and where the file my.node list could contain, for example:

12356end

If you now wanted to substitute another node list you could, for example, supply differentnode numbers in the file my other.node list and then just change the file name given inthe include instruction.


Included files can contain groups of instructions and input, or just bits of input for a singleinstruction. Only one level of include instruction is allowed, and so included files can notthemselves contain include instructions.

As grok reads and processes the copy of the prefix.grok file it also creates the prefixo.ecofile. Results of the HydroGeoSphere data generation procedures are written to this fileso if there are any problems reported by the pre-processor you should check this file first todetermine their nature and how you might fix them. If an error occurs while reading theinput data, then grok will halt execution and issue an error message (to the screen and theprefixo.eco file) of the form:

INSTRUCTION: 500

***************************************** INPUT ERROR, HALTING EXECUTION *****************************************

GRID GENERATION: Unrecognized instruction

Press any key to continue

In this case the last instruction (i.e. 500) has, for some reason, caused an error. You shouldnow check the input files to further investigate the cause of the problem, starting with theprefix.grok and material properties files.

2.1.1 File Process Control Options

The following instructions control how the pre-processor treats instructions in the prefix.grokfile and can be inserted at any point in the file and as often as required, except of coursewhen input for a specific instruction is expected.

Echo offBy default, as instructions are read by grok they are echoed to the screen. This commandturns off this feature.

• • •

Echo onThis commands turns on the echoing of instructions to the screen.

• • •

Skip on


With skip mode turned on, grok will read but not act on any subsequent instructions.• • •

Skip offTurns skip mode off, so grok will resume acting on instructions.

• • •

Skip restgrok exits the loop for reading instructions from the prefix.grok file and proceeds togenerate the HydroGeoSphere data files.

• • •

PauseThis instruction causes grok to pause at the current location in the prefix.grok file untilthe user presses a key.

• • •

We will now describe in detail the various actions of the pre-processor, giving instructionsfor setting up the prefix.grok file where necessary.

2.1.2 Units and Physical Constants

The units used in the program are not preset, although a default of kilogram-metre-secondunits is assumed and used to define the values of certain physical constants as discussedbelow. The user should decide which units will be used for mass (M), length (L), andtime (T) for the various input variables, issue the appropriate units instruction (or assignappropriate values for the physical constants) and then consistently use those chosen unitsfor all other input data. For example, if you want to specify the dimensions of your domainin metres and the time at which you want a solution is in seconds, then all measures of lengthand time will have to be in metres and seconds, respectively. The hydraulic conductivityshould therefore be specified in m s−1, a pumping rate in m3 s−1, etc. The program doesnot perform any checks to ensure unit consistency.

Default values are assigned for the gravitational acceleration and fluid properties whichcorrespond to standard values in the kilogram-metre-second system. These parameters areused when defining the properties of fractures, open wells and tile drains.

The following default values will be used for the physical constants and correspond to typicalvalues in the kilogram-metre-second system:


• Gravitational acceleration g = 9.80665 m s−2, Equation 2.3.

• Fluid density ρ = 1000.0 kg m−3, Equation 2.13.

• Fluid viscosity µ = 1.124× 10−3 kg m−1 s−1, Equation 2.13.

• Fluid compressibility αw = 4.4× 10−10 kg−1 m s2, Equation 2.15.

• Fluid surface tension χ = 0.07183 kg s−2, Equation 4.5.

If you are using different units or you want to change the default values you can do so usingthe following instructions.

Units: kilogram-metre-minuteConverts the default values given above into the kilogram-metre-minute system. Thisinstruction also converts the porous media, dual continuum, fractured media, and surfaceflow default properties that are defined in the code. Note, however, that it does not convertproperties specified in any prefix.grok, .mprops, etc. files. Similar instructions exist forconverting to the following systems:

• Kilogram-metre-hour.

• Kilogram-metre-day.

• Kilogram-metre-year.

• Kilogram-centimetre-second.

• Kilogram-centimetre-minute.

• Kilogram-centimetre-hour.

• Kilogram-centimetre-day.

• Kilogram-centimetre-year.

You can change the default values of the physical constants using the following instructions.If you change the default units from the kilogram-metre-second system make sure the valuesgiven here are in the new system.

• • •

Gravitational acceleration1. grav Gravitational acceleration constant [L T−2], g in Equation 2.3.

• • •

Reference fluid density


1. rho Fluid density [M L−3], ρ in Equation 2.13.

• • •

Reference fluid viscosity1. visc Fluid viscosity [M L−1 T−1], µ in Equation 2.13.

• • •

Fluid compressibility1. wcomp Fluid compressibility [M−1 L T2], αw in Equation 2.15.

• • •

Zero fluid compressibilityAssigns a value of zero for fluid compressibility (i.e. incompressible).

• • •

Fluid surface tension1. tensn Fluid surface tension [M T−2], χ in Equation 4.5.

• • •

2.1.3 Pre-Processor Considerations

2.1.3.1 Array Dimensioning

When performing Task 1, grok first checks for the existence of a file array sizes.default inthe directory where the prefix.grok file is located. If it is not found, the file is automaticallycreated and default array sizes are written which are then used by the pre-processor.Associated with each default are a descriptor and a default value. A portion of the file isshown here:

dual: material zones20

dual flow bc: flux nodes10000


...etc...

tiles: flux function panels20

wells: injection concentration function panels100

end

So, for example, the default maximum number of dual continuum material zones is 20. Ifthe problem is defined such that an array exceeds the default maximum (e.g. the number ofnode sheets in the z-direction for layered grids exceeds 50) then grok will halt executionand issue an error message (to the screen and the prefixo.eco file) of the form:

************************************************ DIMENSIONING ERROR, HALTING EXECUTION ************************************************

Pre-processor request exceeds default array size

mesh: node sheets in z for layered gridsDefault value: 50Requested value: 100

Increase the default value in file ARRAY_SIZES.DEFAULT

Given the descriptor in the error message, you can now edit the array sizes.default fileand increase the appropriate value. Note that the file is sorted alphabetically by descriptor.When you run grok again, it will read the new default value from the file. Re-compilationof the code is not necessary, since it uses Fortran ALLOCATE statements to define arraysizes at run-time.

HydroGeoSphere does not utilize the file array sizes.default, but instead uses exactarray sizes determined and passed by grok.

Remember, this process is problem dependent, and each time you run grok in a differentdirectory, a fresh array sizes.default file will be generated with default values.

2.2 Problem Identification

The first section of the prefix.grok file should consist of a description of the problem beingdefined. As for the rest of the file, blank lines and lines beginning with an exclamation point(!) are ignored.

The description can contain from zero up to as many lines as the user requires to describe


the problem. Each line can contain up to 60 characters. The description is printed at thebeginning of the listing files for grok (prefixo.eco) and HydroGeoSphere (prefix.lst).

The user must signal the end of the description using the End instruction.

EndThis instruction signals the end of the description at which point control is passed back tothe pre-processor.

• • •

2.3 Grid Generation

The next section of the prefix.grok file should consist of instructions for grid generationfollowed by an End instruction.

Currently, grok is capable of generating grids which are composed of either hexahedralblocks or triangular prisms. Figure 2.1 shows the local node numbering conventions for eachof these elements and also the positive directions of the x-, y-, and z-axes.

There is also an option for subdividing hexahedral block elements into 4-node tetrahedralelements (see Section 2.3.6). We will first discuss options for generating simple grids, followedby irregular grids.

2.3.1 Simple Grids

Simple grids can be generated for rectangular domains which are adequate for many problems.They can have uniform or variable element sizes and can be made of hexahedral block ortriangular prismatic elements. Each element in the grid is given a default zone number of 1.

Generate uniform blocks1. xl, nbx, (x0) Domain length and number of blocks in the x-direction, the optional

origin in the x-direction (zero by default).

2. yl, nby, (y0) Domain length and number of blocks in the y-direction, the optionalorigin in the y-direction (zero by default).

3. zl, nbz, (z0) Domain length and number of blocks in the z-direction, the optionalorigin in the z-direction (zero by default).

Generates a grid for a rectangular domain made up of uniform blocks. In this case, thegrid is formed by subdividing the domain in the x-direction into nbx blocks, each of lengthxl/nbx. The domain is subdivided in a similar fashion in the y- and z-directions, using the


Figure 2.1: Element types and local node numbering conventions.

other input parameters.• • •

Generate uniform prismsGenerates a grid for a rectangular domain made up of uniform prisms. Requires identicalinput to the routine Generate uniform blocks described above. In this case though, instead ofgenerating block elements, this instruction generates prism elements by subdividing eachblock into two prism elements.

• • •

Generate variable blocks1. nx Number of nodes in the x-direction.

2. x(i), i=1,nx x-coordinates of the nx nodes.

3. ny Number of nodes in the y-direction.

4. y(i), i=1,ny y-coordinates of the ny nodes.

5. nz Number of nodes in the z-direction.


6. z(i), i=1,nz z-coordinates of the nz nodes.

Generates a grid for a rectangular domain made up of variably-sized blocks. It is almostidentical to the Generate uniform blocks instruction except that instead of entering a domainlength in each direction we enter a list of coordinates, which are each used to define theposition of a plane of nodes along that axis. The structure x(i), i=1,nx is called an implieddo and means that you must supply nx values for the array xi. One or more values can beentered per line until the read statement is satisfied, then a new line should be started forthe next read statement. Note that the line length is limited by 3000 characters in any inputinstructions and thus, use additional lines for x(i), y(i), z(i) should your input exceed thislimit.

• • •

Generate variable prismsGenerates a grid for a rectangular domain made up of variably-sized prisms. Requires identi-cal input to the routine Generate variable blocks described above. In this case though, insteadof generating block elements, this instruction generates prism elements by subdividing eachblock into two prism elements.

• • •

2.3.2 Interactive Block Grids

Interactive block instructions can be used to generate a grid made up of variably-sizedblocks. The user can grade the mesh as desired in each of the three principal directions.This is particularly useful for regions in which fine meshes are required, for example, near adiscrete fracture or well.

Note that these instructions cannot be used in conjunction with the other grid generationinstructions such as Generate uniform block, Generate uniform prisms, Generate variable blocks,or Generate variable prisms.

Generate blocks interactive...EndCauses grok to begin reading a group of interactive block instructions until it encountersan End instruction. The group should contain of at least one instruction for each of theprincipal directions.

• • •

The available instructions are:

Grade x


1. x1, x2, dxstart, xfac, dxmax Starting x-coordinate, ending x-coordinate, startingelement size, element size multiplication factor, and maximum element size.

Grid lines (i.e. elements) are generated along the x-axis from x1 to x2 which grade up insize from dxstart to dxmax. Element sizes are increased steadily by a factor of xfac.

• • •

Grade yAs above but for the y-axis.

• • •

Grade zAs above but for the z-axis.

• • •

The instructions used to generate the mesh shown in Figure 2.2 are:

generate blocks interactivegrade x75.0 0.0 0.01 1.5 5.0

grade x75.0 100.0 0.01 1.5 5.0

grade x125.0 100.0 0.01 1.5 5.0grade x125.0 200.0 0.01 1.5 5.0grade y100.0 0.0 0.01 1.5 5.0grade y100.0 200.0 0.01 1.5 5.0grade z

1.0 0.0 0.25 1.0 0.25grade z

3.0 1.0 0.01 1.3 0.25grade z

3.0 11.0 0.01 1.3 0.25grade z11.0 12.0 0.25 1.0 0.25

end generate blocks interactive


Figure 2.2: Example grid that was created using Generate blocks interactiveinstructions.

2.3.3 3-D Random Fracture Generator for Block Grids

The following command can be used to generate a 3-D random fracture network in anorthogonal domain (i.e. composed of 8-node block elements). Fractures with randomlocations, lengths, and apertures can be generated.

Rfgen driver1. rfgfile Name of the file that contains the random fracture grid and fracture generation

information.

The structure of the input file is described below.• • •

Grid information1. x1, x2 x-range of the domain.

2. y1, y2 y-range of the domain.

3. z1, z2 z-range of the domain.


4. botfracbnd Elevation of lowest extent of a fracture. No fractures will be generatedbelow this elevation.

5. nwell Number of wells.

6. xwell(i), ywell(i), i=1,nwell xy-coordinates of the well. Generates x- and y-gridlines through each point.

7. xsource1, xsource2 x-coordinates of the source. Generates x-grid lines at thesepoints.

8. ysource1, ysource2 y-coordinates of the source. Generates y-grid lines at thesepoints.

9. zsource1, zsource2 z-coordinates of the source. Generates z-grid lines at thesepoints.

10. mingrspacx, mingrspacy, mingrspacz Minimum grid spacing in the x-, y-, andz-directions, respectively. For example, a mingrspacx value of 1.0 would ensure thatno gridlines are more than 1.0 length units apart along the x-axis.

11. fixed grid Logical variable that controls whether grid lines are generated randomlyor according to fixed spacing input parameters. If true, read the following:

(a) fixed space Logical variable that controls whether uniform or variable grid linespacing is applied. If true, read the following:

i. fixgrspacx, fixgrspacy, fixgrspacz Fixed spacing values in the x-, y-, andz-directions respectively.

Otherwise, if false, read the following:i. nx Number of nodes in the x-direction.

ii. x(i), i=1,nx x-coordinates of the nx nodes.iii. ny Number of nodes in the y-direction.iv. y(i), i=1,ny y-coordinates of the ny nodes.v. nz Number of nodes in the z-direction.vi. z(i), i=1,nz z-coordinates of the nz nodes.

This instruction should be placed at the top of the file and should not appear more thanonce.

• • •

Fracture information1. seed Seed for the random number generator. If this number is changed, a new random

number sequence is produced, which in turn causes new realizations of fracture location,length and aperture to be generated.


2. xmeanfreq Mean fracture frequency in the x-direction.

3. ymeanfreq Mean fracture frequency in the y-direction.

4. zmeanfreq Mean fracture frequency in the z-direction.

5. decay Aperture decay constant. Aperture size can be made to decrease with increasingdepth. Set to zero for no decay.

6. lnsbetween Minimum number of grid lines between fractures.

7. cap Maximum number of times to attempt generating a fracture.

This instruction should follow the Grid information instruction and should not appear morethan once.

• • •

Fracture location distribution x-axis1. type An integer value indicating the type of function to use to generate the variable

fracture locations in the x-direction. Acceptable values are:

1 Uniform.2 Normal.3 Exponential.

2. var1, var2 Distribution parameters which control the function.

For a uniform distribution var1 is the minimum and var2 is the maximum.

For a normal distribution var1 is the mean and var2 is the variance.

For an exponential distribution var1 is the mean and var2 is the standard deviation.

The following instructions use the same input data structure except they are applied to they- and z-directions:

Fracture location distribution y-axisFracture location distribution z-axis

The following instructions use the same input data structure to generate fracture lengths inthe three principal directions:

Fracture length distribution x-axisFracture length distribution y-axisFracture length distribution z-axis

The following instructions use the same input data structure to generate fracture aperturesin the three principal orientations:


XY fracture aperture distributionXZ fracture aperture distributionYZ fracture aperture distribution

• • •

The remaining commands are optional but should not be used more than once:

Vertical fracture from top1. vertical frac top This is a logical variable which, if true, ensures that all vertical

fractures start from the top of the domain.

• • •

Zone fractures how1. zone rfgen fracs Controls how fracture zone numbers are assigned. Acceptable

values are:

1 Assign zone numbers by fracture.2 Assign zone numbers by orientation.

If zoned by orientation, horizontal fractures are in zone 1, vertical fractures parallel to thexy-axis are in zone 2, and vertical fractures parallel to the xz-axis are in zone 3.

• • •

EndThis instruction signals the end of the 3-D random fracture generator input at which pointcontrol is passed back to the pre-processor.

• • •

Once the 3-D grid is generated, it is possible to change the random fracture apertures tozoned fracture apertures by following the procedures outlined in Section 2.8.1.5.

2.3.4 2-D Random Fracture Generator

The 2-D Random Fracture Generator can be used to generate random fracture networks intwo dimensions, currently only in the xz-plane. Nevertheless, in the y-direction, more thanone block can be used.

Begin 2D random fractures...End


Causes grok to begin reading instructions that describe the generation of 2-D randomfractures until it encounters an End instruction.

• • •

The following optional instructions can be used to modify the default behaviour of thefracture generator:

Number of random fractures1. n rfractures Number of random fractures to generate.

By default, the 2-D random fracture network will consist of 80 fractures.• • •

Use constant seed1. the seed Seed for the 2-D Random Fracture Generator.

Causes the 2-D Random Fracture Generator to use a constant seed the seed to producethe same random fracture network each time grok is run.

By default, the 2-D Random Fracture Generator is seeded with a time-dependent value,based on the current system time. In that case, it produces a different fracture networkeach time grok is run.

In either case, the seed value is written to the prefixo.eco file and can be used to generatethe same random fracture network many times.

• • •

Generate orientation distribution1. or n classes Number of orientation classes.

2. or first class middle Middle of the smallest orientation class.

3. or last class middle Middle of the largest orientation class.

4. or sigma Standard deviation σ of both Gaussian distributions.

5. or mu1 Mean µ1 of the first Gaussian distribution.

6. or mu2 Mean µ2 of the second Gaussian distribution.

Causes grok to read the parameters that are used to define the distribution of fractureorientation, which follows a mixed Gaussian distribution according to:

P (x) = 12P1(x) + 1

2P2(x) (2.1)


where the ith Gaussian distribution with mean µi and variance σ2 has probability densityfunction

Pi(x) = 1σ√

2πe−

(x−µi)2

2σ2 (2.2)

defined for all x ∈ (−∞,∞).

By default, the values given in Table 2.1 are used to define these relationships.

Table 2.1: Default values for 2-D random fracture orientation.

Parameter Value UnitNumber of orientation classes 13Middle of the smallest orientation class 30 degreesMiddle of the largest orientation class 150 degreesStandard deviation of both classes σ 15 degreesMean of the first Gaussian distribution µ1 60 degreesMean of the second Gaussian distribution µ2 120 degrees

• • •

Generate aperture distribution1. ap n classes Number of aperture classes.

2. ap first class middle Middle of the smallest aperture class.

3. ap last class middle Middle of the largest aperture class.

4. ap lambda λ of the exponential aperture distribution.

Causes grok to read the parameters that are used to define the distribution of fractureaperture, which follows an exponential distribution, according to:

P (x) = Po · e−λ x (2.3)

Note that for a high value of λ, the exponential distribution becomes steeper and smallapertures are more numerous, whereas a small value of λ favours larger apertures.

By default, the values given in Table 2.2 are used to define these relationships.• • •

Generate log-normal length distribution1. le n classes Number of length classes.


Table 2.2: Default values for 2-D random fracture aperture.

Parameter Value UnitNumber of aperture classes 10Middle of the smallest aperture class 50 micronsMiddle of the largest aperture class 300 micronsλ of the exponential aperture distribution 9000

2. le first class middle Middle of the smallest length class.

3. le last class middle Middle of the largest length class.

4. lognormal m µ of the log-normal distribution.

5. lognormal s σ of the log-normal length distribution.

Causes grok to read the parameters that are used to define the distribution of fracturelength, which follows a log-normal distribution according to:

P (x) = 1σx√

2πe−

(ln x−µ)2

2σ2 (2.4)


Table 2.3: Default values for 2-D random fracture length, log-normaldistribution.

Parameter Value UnitNumber of length classes 10Middle of the smallest length class 0.1 ·min(Lx, Lz)† m‡Middle of the largest length class min(Lx, Lz) mµ of the log-normal distribution 2.9σ of the log-normal length distribution 0.45† The symbols Lx and Lz denote the length of the simulation

domain the x and z directions respectively.‡ Although metre units of length are shown in this table they may

be defined differently by the user as outlined in Section 2.1.2.

It should be noted that the log-normal distribution Λ(µ, σ2) is obtains from the distributionΛ(0, σ2) via:

• Stretching by eµ in the x-direction.

• Stretching by e−µ in the z-direction.


Thus, larger values for µ will move the peak to the right. Altering the standard deviationσ will have an impact on the scattering of the distribution where a small σ leads to lessscattering and a sharper peak.

• • •

Exponential length distributionCauses grok to use an exponential distribution of the fracture trace, as opposed to thedefault log-normal distribution.

• • •

Generate exponential length distribution1. le n classes Number of length classes.

2. le first class middle Middle of the smallest length class.

3. le last class middle Middle of the largest length class.

4. le lambda λ of the exponential length distribution.

Used in conjunction with the Exponential length distribution instruction, this causes grokto read the parameters that are used to define the distribution of fracture length, whichfollows an exponential distribution according to:

P (x) = Po · e−λ x (2.5)

Note that for a high value for λ, the exponential distribution becomes steeper and shortfractures are more numerous whereas a small λ favors longer fractures.


Table 2.4: Default values for 2-D random fracture length, exponentialdistribution.

Parameter Value UnitNumber of length classes 10Middle of the smallest length class 0.1 ·min(Lx, Lz)† m‡Middle of the largest length class min(Lx, Lz) mλ of the exponential length distribution 0.05† The symbols Lx and Lz denote the length of the simulation domain

in the x and z directions respectively.‡ Although metre units of length are shown in this table they may

be defined differently by the user as outlined in Section 2.1.2.


• • •

Output random aperturesWrites the generated aperture distribution data and individual fracture apertures to theoutput file prefixo.rfrac.apertures.

• • •

Output random lengthsWrites the generated length distribution data and individual fracture lengths to the outputfile prefixo.rfrac.lengths.

• • •

Output random orientationsWrites the generated orientation distribution data and individual fracture orientations tothe output file prefixo.rfrac.orientations.

• • •

Output random fracturesWrites fracture zone aperture, conductivity and location data to the output fileprefixo.rfrac.fractures.

• • •

Figure 2.3 gives an overview of the default distributions which the 2-D Random FractureGenerator employs. The orientation distribution (Figure 2.3a) is based on the assumptionthat tectonic stress results in the creation of two fracture families as depicted in Figure 2.3b.However, upon assigning identical values for µ1 and µ2, the distribution collapses to aone-peak distribution. The default distribution for the aperture (Figure 2.3c) is exponentialand can be modified by the user. By default, the fracture traces are distributed log-normally(Figure 2.3d), which can be changed to exponential. Note that the fracture trace distributiondepends on the domain dimensions. Here, a block has been used with Lx = 100 m, Ly = 1m, and Lz = 50 m.

The following instructions were used to generate the irregular fracture network shown inFigure 2.4. Note the dominance of the two orientations 80 and 135.

!_______________________ grid definition

generate uniform blocks


100.0 2001.0 150.0 100

adapt grid to fractures3end

...etc...

!_______________________ fracture media properties

use domain typefracture

properties fileeval.fprops

begin random fractures

use constant seed0.5

number of random fractures70

exponential length distribution

generate orientation distribution1060.150.10.80.135.

output random aperturesoutput random lengthsoutput random orientationsoutput random fractures

end

read propertiesfracture


0

5

10

15

0 30 60 90 120 150 180

orientation [1°]

nu

mb

er

of

fractu

res

0

5

10

15

20

50 100 150 200 250 300

aperture [µm]

nu

mb

er

of

fra

ctu

res

0

5

10

15

20

25

0 10 20 30 40 50

length [m]

nu

mb

er

of

fra

ctu

res

a)b)

c) d)

Figure 2.3: Default random fracture distribution.

Figure 2.4: Example of an irregular fracture network.


2.3.5 Interactive 3-D Mesh Generator

Irregular grids can be generated by supplying nodal coordinates, element incidences andelement zones for a 2-D slice which is composed of triangular or quadrilateral elements.Currently, triangles and quadrilaterals can not be mixed in the same slice. These slices canthen be replicated to form a 3-D mesh composed of 6-node prisms (from triangles) or 8-nodehexahedra (from quadrilaterals).

2.3.5.1 Defining a 2-D Mesh

The following instructions can be used to obtain 2-D slice data.

Generate uniform rectangles1. xl, nbx, (x0) Length and number of rectangles in the x-direction, the optional origin

in the x-direction (zero by default).

2. yl, nby, (y0) Length and number of rectangles in the y-direction, the optional originin the y-direction (zero by default).

Generates a 2-D grid for a rectangular domain made up of uniform rectangles. Each rectan-gular element will be assigned a default zone number of 1. It is identical to the Generateuniform blocks instruction except that we drop the z-axis parameters.

• • •

Generate variable rectangles1. nx Number of nodes in the x-direction.

2. x(i), i=1,nx x-coordinates of the nx nodes.

3. ny Number of nodes in the y-direction.

4. y(i), i=1,ny y-coordinates of the ny nodes.

Generates a 2-D grid for a rectangular domain made up of variably-sized rectangles. Eachrectangular element will be assigned a zone number of 1. It is almost identical to theGenerate variable blocks instruction except that we drop the z-axis parameters. Note that theline length is limited by 3000 characters in any input instructions and thus, use additionallines for x(i), y(i) should your input exceed this limit.

• • •

Generate rectangles interactive


This instruction works in exactly the same way as the Generate blocks interactive instructiondescribed in Section 2.3.2, except that input is limited to the x- and y-directions and a 2-Dmesh of 4-node rectangular elements is generated.

• • •

Generate uniform trianglesScope: .grok

1. xl, nbx, (x0) Length and number of rectangles in the x-direction, the optional originin the x-direction (zero by default).

2. yl, nby, (y0) Length and number of rectangles in the y-direction, the optional originin the y-direction (zero by default).

Generates a 2-D grid for a rectangular domain made up of uniform triangles. Each triangularelement is assigned a default zone number of one. This command is identical to the commandGenerate uniform prisms except that we drop the z-dependence.

• • •

Read algomesh 2d grid1. ah2 mesh Filename (including extension) of the 2-D *.ah2 mesh exported from

AlgoMesh.

• • •

Refine 2d gridCauses grok to refine 2-D irregular triangular grid (one triangle to four triangles). Thiscommand can be repeated multiple times after the 2-D grid has been imported. Note thatthe number of nodes increases by about four times with this command.

• • •

Reduce 2d grid, boundary file1. polygon file Filename (including extension) of a text file where a polygon is defined

with x- and y-coordinates in each line (the number of lines in this file is the same asthe number of points to define the polygon). Note that first and last points need to beidentical. The reduced 2-D grid system includes only those triangular elements whenall the vertices are located within the polygon.

• • •


Read fractran 2d grid1. prefix Prefix of the FRACTRAN files which contain the node coordinates, element

incidences and element zone numbers for the 2-D rectangular element mesh. This is astring variable.

Reads the files which contain data defining a 2-D slice composed of 4-node rectangularelements. These files are compatible with output generated by the FRACTRAN program.

• • •

For a 2-D slice made of 4-node rectangular elements, the following instructions can be usedto remove elements:

Remove rectangles with shapefile1. arcview prefix Prefix of the ArcView shapefile.

2. unproject file If true, this logical switch causes grok to read grid unprojection dataas described in Section 2.3.10 and to apply it to the data read from the ArcViewshapefile.

3. project file If true, this logical switch causes grok to read grid projection data asdescribed in Section 2.3.10 and to apply it to the data read from the ArcView shapefile.

4. outside If true, elements located outside the area defined in the ArcView shapefileare removed. If false, elements located inside the area are removed.

• • •

Remove rectangles with blanking fileAs above except a blanking file in surfer format is used instead of an ArcView shapefile.

• • •

Raster to scl1. arcview file name Name of the ArcView ASCII file.

2. bandwidth Cell bandwidth used for averaging.

Reads an ArcView ASCII file and interpolates a value for each 2-D mesh node. The resultsare written to a GMS formatted scalar file called output.scl.

• • •

Raster to nprop


1. arcview file name Name of the ArcView ASCII file.

2. bandwidth Cell bandwidth used for averaging.

Reads an ArcView ASCII file and interpolates a value for each 2-D mesh node. The resultsare written to a binary file called raster2nprop.output.nprop.

• • •

Raster to element1. arcview file name Name of the ArcView ASCII file.

2. Statistic Statistic to be used to interpolate values. Acceptable values for the variablestatistic are:

max countnearest

If variable statistic is set to max count read the following:

(a) bandwidth Cell bandwidth used for averaging.

Reads an ArcView ASCII file and interpolates a value for each 2-D mesh element. Theresults are written as a list of element number and value to a file called output.el.

• • •

2.3.5.2 3-D Mesh Generation

Once you have a 2-D slice, you have the option of exiting the grid definition procedure,which will cause grok to automatically generate a unit thickness 3-D grid. It does this byduplicating the 2-D slice and constructing the appropriate 6-node prism or 8-node hexahedralelement incidences and assigning a unit element length perpendicular to the slice. Theelement zone numbers for the slice are used to assign default zone numbers for each element.Such a grid could be used to simulate 2-D cross-sectional problems.

More often, you will want to generate a 3-D layered grid, perhaps with topography definedby a DEM (Digital Elevation Model) and/or uneven layer contacts based on the observedhydrostratigraphy.

To do so you should start by issuing the following instruction:

Generate layers interactive...EndCauses grok to begin reading a group of 3-D grid generation instructions until it encountersan End instruction.


• • •

The basic procedure is to build up the 3-D mesh by defining the base, then adding layersone at a time from the base to ground surface.

By default, the domain will contain a single layer, one element high with a base elevation ofzero and a top elevation of 1, and the element zone numbering scheme from the 2-D slicewill be used to assign the 3-D mesh element zone numbers. Instructions that change thedefault behaviour are described below:

These commands are optional but should not be used more than once:

Zone by layerCauses grok to assign the 3-D mesh layer number to the element zone number. By default,the element zone numbering scheme from the 2-D slice is used to assign the 3-D meshelement zone number.

• • •

Base elevation...EndCauses grok to begin reading a group of base elevation instructions until it encounters anEnd instruction. Available instructions are described in Section 2.3.5.4. By default, the baseelevation of the domain will be set to zero.

• • •

2.3.5.3 Adding a New Layer

For each layer in the domain, you should include a single instance of the following instruction:

New layer...EndCauses grok to begin reading a group of new layer instructions until it encounters an Endinstruction.

By default, the top elevation of the layer will be set to zero by assigning all nodes in thelowermost 2-D slice to have a z-coordinate value of zero. You can change the layer topelevation using the instructions described in Section 2.3.5.4.

• • •

The following instructions are optional:

Layer name1. layer name Layer name.


Changes the layer name, which defaults to ‘‘Layer n’’, where n is the current layer number.• • •

Minimum layer thickness1. min thick Minimum thickness [L].

This instruction causes grok to enforce a minimum thickness constraint for the currentlayer. At nodes where the computed layer top elevation is less than or equal to the currentbase elevation, min thick is added to the current base elevation to get the top elevation.

If this constraint is not enforced, grok will stop and issue a warning message if the computedtop elevation is less than or equal to the current base elevation.

• • •

Minimum layer thickness with fixed top elevation1. min thick Minimum thickness [L].

This instruction causes grok to enforce a minimum thickness constraint for all layers. Atnodes where the computed layer top elevation is less than or equal to the current baseelevation, min thick is subtracted from the top elevation to get the base elevation.

In contrast to the command Minimum layer thickness, this command applies to all layers andadjusts layers from the top down, maintaining the original surface layer elevations.

If this constraint is not enforced, then grok will stop and issue a warning message if thecomputed top elevation is less than or equal to the current base elevation.

• • •

By default, a new layer will not be subdivided vertically unless one of the following twoinstructions is issued:

Uniform sublayering1. nsublayer Number of sublayers.

This instruction divides the layer vertically into nsublayer elements, which will each havethe same height, equal to the top elevation minus the current base elevation divided bynsublayer.

• • •

Proportional sublayering


1. nsublayer Number of proportional sublayers.

2. sub thick(i), i=1,nsublayer Proportional thicknesses in order from top to bottom.

This instruction can be used if you want to refine the mesh vertically, for example in thesubsurface near the surface flow domain or a fracture.

It is important to understand that the variable sub thick is not a true thickness, but isinstead a relative thickness, which is used along with the layer thickness to determine theelement heights in the current column.

For example, these instructions would subdivide the current layer vertically into threeelements, between the current base and top elevation, with element height proportions of0.1, 1, and 10 from top to bottom:

Proportional sublayering30.11.010.0

• • •

Offset top1. value Thickness [L] by which to offset the layer top elevation.

This instruction causes the elevation of the top layer to be offset vertically by the givenvalue. This can be used to create a surface at a given distance below another surface.

• • •

Offset base1. value Thickness value [L] by which to offset the base elevation.

This instruction causes the base elevation to be offset vertically by the given value.

For example, these instructions create two layers with the elevations 2 and 1 metres belowthe elevation defined in the raster gs.asc and the raster elevation:

base elevationelevation from raster filegs.asc


offset base-2.0

end

new layerUniform sublayering10

elevation from raster filegs.asc

offset top-1.0

end

new layerUniform sublayering3

elevation from raster filegs.asc

end

• • •

2.3.5.4 Elevation Instructions

These instructions are used to define 3-D mesh base elevations and new layer top elevations.

Elevation constant1. elev Elevation value [L].

• • •

Elevation from raster file1. rasterfile Name of the raster file containing the base elevation values. This is a string

variable. The file should be formatted as outlined in Section F.

• • •


Elevation from tsurf fileScope: .grok

1. filename Filename of GoCAD tsurf file, up to 120 characters.

This command assigns elevations by interpolating to a surface consisting of triangularelements. The surface is stored as a GoCAD tsurf file. Note that this command applies onlyto triangular prism or hexahedral block meshes.

• • •

Elevation from bilinear function in xy1. xfrom, xto, yfrom, yto x- and y-range.

2. a1, a2, a3, a4, a5 Constants for bilinear function.

For nodes falling within the given x- and y-range, the z-coordinate is computed accordingto the following function:

z = a1 + a2(x− xfrom) + a3(x− xfrom)2 + a4(y − yfrom) + a5(y − yfrom)2

• • •

Elevation from sine function in xy1. xfrom, xto, yfrom, yto x- and y-range.

2. zz0 Elevation at xfrom, yfrom.

3. num sw x, amplitude x, slope x Number of sine wave cycles, sine wave amplitudeand surface slope in the x-direction.

4. num sw y, amplitude y, slope y Number of sine wave cycles, sine wave amplitudeand surface slope in the y-direction.

For nodes falling within the given x- and y-range, the z-coordinate is computed accordingto the following function:

z = zz0 + amplitude x(1 + sin(f(x))) + slope x(x− xfrom)+amplitude y(1 + sin(f(y))) + slope y(y − yfrom)

where:f(x) = 2π · num sw x · (x− xfrom)/(xto− xfrom)


f(y) = 2π · num sw y · (y − yfrom)/(yto− yfrom)

• • •

The number of cycles of the sine wave can be a fraction and the sine function rises froma value of zz0 at (xfrom, yfrom) as x- and y-values increase. Where the peaks coincide,the maximum elevation is the sum of zz0 + amplitude x + amplitude y.

Elevation from cosine function in xyAs above but uses the cosine function instead of the sine function.

• • •

Elevation from xz pairs1. xval(i), zval(i)...end List of xz-pairs.

Listed xz-coordinate pairs are read until an End instruction is encountered. They shouldbe given in order from the smallest to largest x-value. For each node in the 2-D grid, thex-coordinate of the node is used to determine its position in the list, and a z-coordinate isthen interpolated from the neighbouring xz-pairs.

• • •

Elevation from file1. ascii elevation filename Name of the ASCII text file containing the elevation values.

The file should contain one elevation value per line for each node in the surface mesh.

• • •

2.3.6 Tetrahedral Element Grids

TetrahedraSubdivides block elements into tetrahedra (4-node) elements. If the grid does not containblock elements the pre-processor will stop and you will be issued a warning.

• • •

Block elements must be orthogonal or nearly so in order to avoid introducing numerical error,while tetrahedral elements can handle irregular geometries. The subdivision into tetrahedrais carried out by HydroGeoSphere during problem solution and is transparent to the


user. Faces which can be designated as fracture elements are restricted to the original blockelements. This is merely a matter of convenience and future versions may allow tetrahedralelement faces to be designated as fractures.

2.3.7 Axisymmetric Flow

Axisymmetric coordinatesThis instruction is used for simulating radial flow to a well. It should only be applied to avertical cross-section, of unit thickness in the y-direction. The x-coordinate is taken as theradial distance.

One should define a vertical cross-section of unit thickness in the y-direction (with twonodes in that direction), and locate a pumping/injection well at the origin (x = 0).

• • •

2.3.8 Reading an Existing 3-D Grid

In some cases, the grid generation step can be very time consuming. If this is so, then thefollowing instruction can be used to read a grid which was generated in a previous run:

Read 3D gridThe grid whose prefix matches that of the prefix.grok file will be read in.

These instructions show how to set up the grid generation section of the prefix.grok file touse the Read 3d grid instruction:

! Generate the grid for the first runread algomesh 2d gridlaurel

generate layers interactivenew layerelevation from raster file

Layer 1.ascendnew layerelevation from raster file

Layer 2.ascend

end

skip on


! Read previously defined grid for subsequent runsread 3D gridskip offend

In the first run, one can read the slice and generate the layered grid. It is important thatthe instruction Write faces and segments be included if you are using any of the Choose faceor Choose segment instructions later in the prefix.grok file.

On subsequent runs, one can skip over the grid generation commands and use the Read 3Dgrid instruction instead.

• • •

Read 3D grid, asciiForce grok to read prefix.coordinates and prefix.elements to create a 3-D mesh. Formatsare as follows:

prefix.coordinates

• Line 1: nn (1 integer), total number of nodes

• Lines 2 to nn+1: x(i), y(i), z(i) (3 floats), nodal coordinates for node 1 to node nn

• Line nn+2: nx, ny, nz, nsptot (4 integer), number of grid lines in x, y, and z coordinates+ number of species for transport (for unstructured grid, nx and ny are neglected;nsptot = 0 always)

• Line nn+3: ne2d (1 integer), number of triangles or rectangles in the 2-D node sheet

• Line nn+4: tetramesh (1 logical), logical switch (true if it is a tetrahedral mesh)

• Line nn+5: gal mode (1 logical), logical switch (true if the Galerkin method is usedfor tetramesh)

• Line nn+6: do write face seg (1 logical), should always be false

• Line nn+7: nb2d (1 integer), maximum number of nodes connected to a node for the2-D triangular mesh

prefix.elements

• Line 1: nln (1 integer), number of nodes in a single element (4: tetrahedron; 6:triangular prism; 8: hexahedron)

• Line 2: ne (1 integer), total number of elements

• Lines 3 to ne+2: n(1,i), n(2,i),. . . , n(nln,i) (nln integers), node numbers for elementincidences for elements 1 to ne


• Lines ne+3 to 2ne+2: id(i) (1 integer), element ID (zone number) for elements 1 to ne

• • •

2.3.9 Manipulating the 3-D Grid

Tilt grid xTilts a grid by 90° around the x-axis. This is especially suitable in conjunction with theinstruction Read slice which reads a two-dimensional grid (parallel to the xy-plane) in GMSformat.

• • •

Tilt grid ySame as the command Tilt grid x but for the y-axis.

• • •

Adapt grid to fractures1. adapt g2f mode An integer value indicating how the grid is adapted to inclined

fractures.

If block elements are used, two inclined fractures may intersect in the middle of an elementinstead of on a grid node, so the fractures will not be connected unless additional nodes arespecified.

Acceptable values for the variable adapt g2f mode and the actions taken in each case are:

0 No action is taken.1 New grid lines are added.2 The block element is substituted by four prisms.3 Inclined faces are not selected in the block element where the problem occurs.

The default value is 1.• • •

2.3.10 Grid Projection

Figure 2.5 illustrates the degree of distortion that can occur (which is especially severe atthe poles) when a spherical geographic coordinate system, such as longitude and latitude, is


mapped directly into a planar 2-D coordinate system. The following command can be usedto correct the distortion which occurs when modelling large continental scale problems.

Project grid1. project The projection type to be applied. Currently, the only valid input for project

are ‘‘albers equal-area’’ or ‘‘lambert azimuthal equal-area’’, which apply the Albersconical or Lambert azimuthal equal-area projections, respectively. For the Albersprojection, the following additional data are required:

(a) lon0, lat0 The longitude and latitude for the origin of the projection.(b) lat1, lat2 The latitude of the standard parallels.(c) datum The datum used for the projection. Acceptable values for the variable

datum are:

1 Sphere.2 Ellipsoid (Clarke 1866).

For the Lambert projection, the following additional data are required:

(a) lon0, lat0 The longitude and latitude for the origin of the projection.(b) datum The datum used for the projection. Acceptable values for the variable

datum are:

1 Sphere.

Transforms the current mesh from a spherical system into a planar 2-D coordinate system.It must be inserted just before the End grid generation command.

The following example uses the Project Grid instruction:

generate blocks interactivegrade x-150 -50 5 1 5grade y40 85 5 1 5grade z0 10 10 1 10end

project gridalbers equal-area-100 60 ! projection origin55 70 ! standard parallels1 ! 1=sphere, 2=ellipsoid

end


The grid produced by the Generate blocks interactive instruction is shown on Figure 2.5 andonce projected, the grid looks like the one on Figure 2.6.

• • •

Project 2d gridThe input data for this instruction is identical to the input data required by the commandProject grid described above.

Transforms the current 2-D mesh from a spherical coordinate system (lat/long) into a planar2-D coordinate system. It must be inserted just before the End grid generation command.

• • •

Unproject 2d gridThe input data for this instruction is identical to the input data required by the commandProject grid described above.

Transforms the current 2-D mesh from a planar 2-D coordinate system into a spherical coor-dinate system (lat/long). It must be inserted just before the End grid generation command.

• • •

2.3.11 Ending Grid Generation

EndSignals the end of the user-controlled portion of the grid definition section of the inputdata file. At this stage, the pre-processor will automatically perform grid modifications ifappropriate. For example, if you read in 2-D slice data but did not specify layer informationusing for example, the Generate layers interactive instruction, the pre-processor would generatea default 3-D system by duplicating the 2-D slice to form a single layer of unit-thicknesselements.

• • •


Figure 2.5: Mesh in geographic coordinates (lat/long). The map of Canadais shown as a reference.

Figure 2.6: Mesh using Albers equal-area projection. The map of Canadanow shows much less distortion but the elements are deformed.


2.4 Selecting Mesh Components

In order to assign boundary conditions, material properties etc. we need to be able to choosesubsets of the grid. The method of choice must be flexible and easy to use as well as beingable to handle complex input requirements.

The following is a list of grid components, ranked in order of increasing complexity:

1. Nodes: used to assign initial heads and first-type boundary conditions.

2. Segments: used to represent wells, tile drains, or observation wells.

3. Faces (triangles or rectangles): used to represent fractures or high-conductivity planes(as 2-D triangular or rectangular elements) and to assign second- and third-typeboundary conditions to these as well as 3-D prism or block elements.

4. Elements (blocks, prisms, or tetrahedra): sometimes used to assign hydraulic conduc-tivities or distribution coefficients.

5. Zones: generally used to assign material properties such as hydraulic conductivity.Elements are grouped into zones by assigning them the same ID number.

We will assign to all members of a grid component an attribute called ‘chosen’ that can betoggled on or off by the user. If an attribute is chosen for certain members of a component,then subsequent instructions issued by the user will affect those members only. For example,the following section of a hypothetical prefix.grok file would initially turn off all chosennodes (i.e. instruction Clear chosen nodes which requires no further input), then turn on onlythose nodes satisfying the requirement that they are within 10−5 distance units of the planedefined by the equation x = 0 (i.e. instruction Choose nodes x plane followed by two lines ofinput).

clear chosen nodeschoose nodes x plane0.0 ! x-coordinate of plane1.e-5 ! distance criteria

Once these nodes were chosen, we could set the property of interest by issuing another setof instructions, for example:

create node setmy_node_set

boundary conditiontypehead


node setmy_node_set

time value table0.0 10.0end

end

In this case we are assigning a constant head of 10.0 to all chosen nodes at time zero, whichwill apply for the duration of the simulation. We note that the head boundary conditioninstruction is acting on nodes via the Node set instruction. In general, it is up to the user tobe aware of which components each group of instructions acts upon.

The effect of issuing two such instructions in succession is cumulative. For example, thefollowing input would choose nodes that are within 10−5 distance units of the planes x = 0and x = 10.

clear chosen nodes

choose nodes x plane0.0 ! x-coordinate of plane1.e-5 ! distance criteria

choose nodes x plane10.0 ! x-coordinate of plane1.e-5 ! distance criteria

The following sections introduce all instructions that are available for choosing subsets ofthe various grid components.

2.4.1 Selecting Nodes

We can use the following instructions to alter the set of chosen nodes.

Clear chosen nodesAll nodes in the domain will be flagged as not chosen. This is recommended if you areunsure of which nodes are chosen due to previously issued instructions.

• • •

Choose nodes allAll nodes in the domain will be chosen. This is useful if you wish to assign a property to allnodes in the grid. For example, you could issue this instruction and then assign a uniform


initial head for the problem.• • •

Choose node1. x1, y1, z1 xyz-coordinate.

The node closest to the given coordinate will be chosen.• • •

Choose node number1. node number Node number.

The node with this number will be chosen. You should use this instruction with cautionsince node numbering will change if the grid structure changes.

• • •

Choose nodes x plane1. x1 x-coordinate of the plane.

2. ptol Distance from the plane.

Nodes within distance ptol of the plane defined by the equation x = x1 will be chosen.This command is particularly useful when assigning boundary conditions to a specific sideof a rectangular domain.

• • •

Choose nodes y planeAs above but for the y-plane.

• • •

Choose nodes z planeAs above but for the z-plane.

• • •

Choose nodes 3pt plane


1. x1, y1, z1 xyz-coordinate of the first point.

2. x2, y2, z2 xyz-coordinate of the second point.

3. x3, y3, z3 xyz-coordinate of the third point.


Nodes within distance ptol of the plane defined by the three points will be chosen. Thisallows you to choose planes of nodes with an arbitrary orientation.

• • •

Choose nodes 3pt plane bounded1. x1, y1, z1 xyz-coordinate of the first point.




5. x4, x5 x-range of the block.

6. y4, y5 y-range of the block.

7. z4, z5 z-range of the block.

Nodes within distance ptol of the plane defined by the three points and within the rectan-gular block defined by the three ranges will be chosen.

• • •

Choose nodes block1. x1, x2 x-range of the block.



Nodes within the rectangular block defined by the three ranges are chosen. Note that thevalues given for one, two or all of the ranges can be identical and in that case, the block willcollapse to a plane, line or point respectively.

• • •


Choose nodes topAll nodes in the top sheet of the domain are chosen.

• • •

Choose nodes top block1. x1, x2 x-range of the block.



Nodes in the top sheet whose centroids are within the rectangular block defined by thethree ranges are chosen. Note that the values given for one, two or all of the ranges can beidentical and in that case, the block will collapse to a plane, line or point respectively.

• • •

Choose nodes bottomAll nodes in the bottom sheet of the domain are chosen.

• • •

Choose nodes sheet1. nsheet Sheet number.

All nodes in this sheet are chosen.• • •

Choose nodes top am1. fname Name of the AlgoMesh chosen nodes file am prefix.nchos.description.

Nodes flagged as true in the file and that are in the top sheet are chosen.• • •

Choose nodes am1. fname Name of the AlgoMesh chosen nodes file am prefix.nchos.description.


2. nsheet bot, nsheet top Bottom and top sheet numbers.

Nodes flagged as true in the file and that are between the bottom and top sheet (inclusive)are chosen.

• • •

Choose nodes list1. fname Name of the file which contains the list of node numbers.

The file consists of a list of node numbers, one entry per line. The procedure exits automati-cally when end-of-file is reached. The nodes in the list are chosen.

• • •

Choose nodes xyz list1. fname Name of the file which contains the list of xyz-coordinates.

The file consists of a list of xyz-coordinates, one entry per line. The node nearest the givencoordinate will be chosen. The procedure exits automatically when end-of-file is reached.

• • •

Choose surface flow nodesNodes currently flagged as surface flow nodes are chosen.

• • •

Choose nodes top boundaryNodes around the top edge of the surface flow domain are chosen.

• • •

Choose nodes lateral boundariesSelects all nodes belonging to the lateral boundaries of the porous media domain. It isequivalent to choosing all nodes belonging to the boundary edges within each sheet of themesh.

• • •

Choose nodes tecplot geometry


1. geofile Name of the Tecplot geometry file which contains polyline data.

The node nearest to each point on the polyline is chosen.• • •

Choose nodes horizontal circle1. x mid, y mid, z mid xy-coordinates of the centre of the circle and elevation of the

circle.

2. radius Radius of the circle.

3. ptol Vertical tolerance.

4. rtol Horizontal tolerance.

Nodes within a vertical distance ptol of elevation z mid, and within a horizontal distancertol of the circle with centre x mid, y mid and radius radius are chosen. This allows youto choose nodes in a domain that has a circular ground-plan.

• • •

Choose nodes active/inactive boundaryNodes which lie on the boundary between active and inactive elements will be chosen.

This instruction was intended to be used to select the surface of nodes on top of the setof active elements so that flow boundary conditions (e.g. head equals elevation) could beassigned.

• • •

Choose nodes 2d-list sheet1. nsheet Sheet number.

2. fname Name of the file which contains the list of 2-D node numbers.

The file consists of a list of 2-D node numbers, one entry per line. The procedure exitsautomatically when end-of-file is reached. The 3-D nodes in the sheet are chosen based onthe 2-D node number and the sheet number. If the 2-D node number in the list is larger thanthe number of nodes in a single mesh sheet but less than or equal to the total number ofnodes in the mesh, then it is automatically converted to a corresponding 2-D node number.

• • •

Choose nodes top 2d-list


1. fname Name of the file which contains the list of 2-D node numbers.

The file consists of a list of 2-D node numbers, one entry per line. The procedure exitsautomatically when end-of-file is reached. The 3-D nodes in the top sheet are chosen basedon the 2-D node number. If the 2-D node number in the list is larger than the number ofnodes in a single mesh sheet but less than or equal to the total number of nodes in the mesh,then it is converted to a corresponding 2-D node number.

• • •

Choose nodes polyline by sheetScope: .grok

1. isheet1, isheet2 Bottom and top sheet numbers (inclusive), respectively.

2. npts The number of points defining the polyline.

3. x(i), y(i), i=1,npts The xy-coordinates of points on the polyline within a singlesheet. The points should be ordered from one end of the polyline to the other.

Within each sheet between isheet1 and isheet2, nodes that fall on or close to the polylineare chosen.

• • •

Choose nodes polyline top sheetScope: .grok

1. npts The number of points defining the polyline.

2. x(i), y(i), i=1,npts The xy-coordinates of points on the polyline in the top sheet.The points should be ordered from one end of the polyline to the other.

Within the top sheet, nodes that fall on or close to the polyline are chosen.• • •

Choose nodes by zone1. zone number Zone number.

This instruction is intended to choose all the nodes within a zone of the given zone number.• • •

Choose nodes between zones


1. zone number1, zone number2 Two zone numbers interface of which will be chosen.

This instruction is intended to choose the interface nodes between two zones.• • •

Write chosen nodes1. fname Name of the file to which the chosen node numbers will be written.

• • •

Write chosen nodes xyz1. fname Name of the file to which the chosen node information will be written.

Writes the xyz-coordinates of chosen nodes to file.• • •

2.4.2 Selecting Segments

We can use the following instructions to alter the set of chosen segments.

Clear chosen segmentsAll segments in the domain are flagged as not chosen. This is recommended if you are unsureof which segments are chosen due to previously issued instructions.

• • •

Choose segments allAll segments in the domain will be chosen. This is useful if you wish to assign a property toall segments in the grid.

• • •

Choose segments line1. x1, y1, z1 xyz-coordinates of the first end point of the line.

2. x2, y2, z2 xyz-coordinates of the second end point of the line.


Segments which fall on or close to the line are chosen. The routine finds the two nodesclosest to the end points of the line and then finds the group of connected line segmentswhich form the shortest path between the two nodes.

• • •

Choose segments polyline1. npts The number of points defining the polyline, which should be entered in order

from one end of the polyline to the other.

2. x(i), y(i), z(i), i=1,npts List of polyline point xyz-coordinates.

Segments that fall on or close to the polyline are chosen. The routine proceeds along thepolyline, considering two points at a time. For each set of points it finds the two nearestnodes and then finds the group of connected line segments that form the shortest pathbetween the two nodes.

• • •

Choose segments polyline by sheet1. nsheet The sheet number.

2. npts The number of points defining the polyline, which should be entered in orderfrom one end of the polyline to the other.

3. x(i), y(i), z(i), i=1,npts List of polyline point xyz-coordinates.

Segments that fall on or close to the polyline are chosen. The routine proceeds along thepolyline, considering two points at a time. For each set of points it finds the two nearestnodes in the specified sheet and then finds the group of connected line segments that formthe shortest path between the two nodes.

• • •

Choose segments am node list1. npts The number of points defining the polyline, which should be entered in order

from one end of the polyline to the other.

2. node(i), sheet(i), i=1,npts List of polyline point node and sheet numbers.

Segments which fall on or close to the polyline are chosen. This instruction is intended tohelp to build horizontal wells/drains.


• • •

Choose segments xy between sheets1. x1, y1 xy-coordinates to define a vertical segment.

2. isheet1, isheet2 Bottom and top sheet numbers to define the segment.

This instruction is intended to help to build vertical wells/drains.• • •

2.4.3 Selecting Faces

Allow internal facesCauses grok to define internal faces, which cut through elements.

By default, only the external faces (six orthogonal faces for 8-node blocks and five faces for6-node prisms) are defined for the mesh.

• • •

The following instructions are used to alter the set of chosen faces:

Clear chosen facesAll faces in the domain are flagged as not chosen. This is recommended if you are unsure ofwhich faces are chosen due to previously issued instructions.

• • •

Choose faces allAll faces in the domain will be chosen. This is useful if you wish to assign a property to allfaces in the grid. Rarely used.

• • •

Choose faces x plane1. x1 x-coordinate of the plane.


Faces within distance ptol of the plane defined by the equation x = x1 will be chosen. Thiscommand is particularly useful when assigning boundary conditions to a specific face of a


rectangular domain.• • •

Choose faces y planeAs above but for the y-plane.

• • •

Choose faces z planeAs above but for the z-plane.

• • •

Choose faces 3pt diskScope: .grok

1. x1, y1, z1 xyz-coordinates of a point on the disk.

2. x2, y2, z2 xyz-coordinates of a point on the disk.

3. x3, y3, z3 xyz-coordinates of disk center.

4. radius The radius of the disk (> 0).

5. tol Distance above and below the disk (> 0).

Faces whose centroids are within the cylindrical region bisected by the disk with height tolabove and below the disk are chosen. Note that all three points on the disk must be distinct.

• • •

Choose faces 3pt plane1. x1, y1, z1 xyz-coordinate of the first point.




Faces within distance ptol of the plane defined by the three points will be chosen. Thisallows you to choose planes of faces with an arbitrary orientation, and is particularly usefulfor setting up a set of sloping fractures.


• • •

Choose faces 3pt plane bounded1. x1, y1, z1 xyz-coordinate of the first point.




5. x4, x5 x-range of the block.



Faces within distance ptol of the plane defined by the three points and within the rectangularblock defined by the three ranges will be chosen.

• • •

Choose faces block1. x1, x2 x-range of the block.



Faces whose centroids are within the rectangular block defined by the 3 ranges are chosen.Note that the values given for one, two or all of the ranges can be identical and in that case,the block will collapse to a plane, line or point respectively.

• • •

Choose faces block by layer1. x1, x2 x-range of the block.



4. nlaybot, nlaytop Bottom and top element layer numbers.


Faces whose centroids are within the rectangular block which is defined by the threecoordinate ranges, and which lie within the element layers defined by nlaybot and nlaytopare chosen. These layer numbers do not correspond to those given during grid generationbut are simply defined by numbering each sheet of elements from 1 (bottom) to n− 1 (top)where n is the number of node sheets (2-D meshes) making up the grid.

This instruction is intended for grids that are regular in the x- and y-directions, but whichhave variable z-values for a given element layer. It can be used if the top and bottomelevations of a 3-D element layer vary spatially.

Note that the values given for one, two or all of the ranges can be identical and in that case,the block will collapse to a plane, line or point respectively.

• • •

Choose faces sheet1. nsheet bot,nsheet top Bottom and top sheet numbers.

Faces which are between the two specified sheets (inclusive) and are not oriented perpendic-ular to the sheet will be chosen.

• • •

Choose faces topAll faces in the top sheet of the domain will be chosen.

• • •

Choose faces top block1. x1, x2 x-range of the block.



Faces in the top layer whose centroids are within the rectangular block defined by thethree ranges are chosen. Note that the values given for one, two or all of the ranges can beidentical and in that case, the block will collapse to a plane, line or point respectively.

• • •

Choose faces top from raster1. fname File path to raster file.


2. n1, n2 Range of raster values.

Faces in the top layer whose centroids lie within the given raster class range are chosen.Selects all raster values that fall within the interval [n1,n2].

• • •

Choose faces bottomAll faces in the bottom sheet of the domain will be chosen.

• • •

Choose faces frontFaces on the front of the domain will be chosen. This instruction can only be applied tomeshes composed of block elements. Front faces are parallel to the xz-coordinate plane andhave small y-coordinates.

• • •

Choose faces backFaces on the back of the domain will be chosen. This instruction can only be applied tomeshes composed of block elements. Back faces are parallel to the xz-coordinate plane andhave large y-coordinates.

• • •

Choose faces leftFaces on the left side of the domain will be chosen. This instruction can only be applied tomeshes composed of block elements. Left side faces are parallel to the yz-coordinate planeand have small x-coordinates.

• • •

Choose faces rightFaces on the right side of the domain will be chosen. This instruction can only be appliedto meshes composed of block elements. Right side faces are parallel to the yz-coordinateplane and have large x-coordinates.

• • •

Choose faces top am1. fname Name of the AlgoMesh chosen elements file am prefix.echos.description.


Faces flagged as true in the file, are in the top sheet and are not oriented perpendicular tothe sheet are chosen.

• • •

Choose faces top am common1. fname1 Name of the AlgoMesh chosen elements file am prefix.echos.description1.

2. fname2 Name of the AlgoMesh chosen elements file am prefix.echos.description2.

Faces flagged as true in the both files, are in the top sheet and are not oriented perpendicularto the sheet are chosen.

• • •

Choose faces top am exclude1. fname1 Name of the AlgoMesh chosen elements file am prefix.echos.description1.

2. fname2 Name of the AlgoMesh chosen elements file am prefix.echos.description2.

Faces flagged as true in the first file and flagged as false in the second file, are in the topsheet and are not oriented perpendicular to the sheet are chosen.

• • •

Choose faces top for chosen elementsFaces are chosen if they are in the top sheet and the 3-D element they belong to is chosen.

• • •

Choose faces am1. fname Name of the AlgoMesh chosen elements file am prefix.echos.description.

2. nsheet bot,nsheet top Bottom and top sheet numbers.

Faces flagged as true in the file, that are between the bottom and top sheets (inclusive),and that are not oriented perpendicular to the sheet are chosen.

• • •

Choose faces vertical from am nodes1. fname Name of the AlgoMesh chosen nodes file am prefix.nchos.description.


2. nsheet bot,nsheet top Bottom and top sheet numbers.

This instruction is intended for use with meshes that are generated from AlgoMesh 2-Dmeshes, and is used to choose faces that are oriented perpendicular to the mesh.

If a node is chosen in the 2-D mesh, then the nodes in the 3-D mesh that have the samexy-coordinate (i.e. that fall in the same column of nodes as the 2-D node) and betweenthe top and bottom sheets will be chosen. A face is then chosen if all of its four nodes arechosen.

• • •

Choose horizontal faces on layer1. nlayer Element layer number.

2. x1, x2 The x-range of the block.

3. y1, y2 The y-range of the block.

Horizontal faces which are in the layer of elements numbered nlayer and within the rect-angular block which is defined by the x- and y-range are chosen. This instruction can beused to select horizontal faces (e.g. to make fractures) when the elevation of a given layer ofnodes is irregular.

• • •

Choose faces stairway1. x1, y1, z1 xyz-coordinates of the first point.

2. x2, y2, z2 xyz-coordinates of the second point.

3. x3, y3, z3 xyz-coordinates of the third point.

Horizontal and vertical faces of an inclined plane that is defined by three points are chosen.This instruction is mainly designed for verification purpose of modelling results using inclinedfractures. Note that if using this instruction, fracture velocities are multiplied by a correctionfactor that accounts for the longer path that contaminants have to travel from node to node.

• • •

Choose fracture faces block1. x1, x2 x-range of the block.




Faces which are fracture elements and whose centroids are within the rectangular blockdefined by the 3 ranges are chosen. Note that the values given for one, two or all of theranges can be identical and in that case, the block will collapse to a plane, line or pointrespectively.

• • •

Choose face by nodes1. n1, n2, n3, n4 Node numbers of the face to be chosen.

The rectangular face which is made up of the four given nodes will be chosen.• • •

Clear chosen faces by nodesAs above except the face will be cleared (i.e. not chosen).

• • •

Choose faces horizontal circle1. x mid, y mid, z mid xy-coordinates of the centre of the circle and elevation of the

circle.



Faces within a vertical distance ptol of elevation z mid, and within the circle with centrex mid, y mid and radius radius are chosen. This allows you to choose faces in a domainthat has a circular ground-plan.

• • •

Write chosen faces1. fname Name of the file to which the chosen face information will be written.

Setting up complex fracture networks with combinations of Choose face instructions can bevery time consuming in grok and this step does not need to be repeated as long as the grid


structure remains the same. This instruction is intended to be used in conjunction with thefollowing instruction.

• • •

Write chosen faces and host element numbers1. fname Name of the file to which the chosen face and host element information will be

written.

For each currently chosen face, this instruction writes the face number and associated 3-Delement numbers. If the second element number is zero, the face is on the outside of the3-D domain.

• • •

Read chosen faces1. fname Name of the file from which the chosen face information will be read.

If you want only those faces read from the file to be chosen then make sure to issue theinstruction Clear chosen faces before you use Read chosen faces. If not, the results will bemerged with the currently chosen set of faces. This could be useful if you want to apply acertain set of fracture material properties to more than one group of faces at a time.

• • •

Echo chosen facesCauses the current set of chosen face numbers to be written to the prefixo.eco file.

• • •

2.4.4 Selecting Inclined Faces

These instructions only work for rectangular meshes with the standard element numberingscheme.

For each block element, there are 6 potential inclined faces which may be selected. Theseare given ID numbers according to the following convention:

PLANE ID LOCAL NODES1 1-2-7-82 4-3-6-53 2-3-8-5


4 1-4-7-65 1-3-7-56 2-4-8-6

Clear chosen inclined facesAll faces in the domain are flagged as not chosen. This is recommended if you are unsure ofwhich inclined faces are chosen due to previously issued instructions.

Note that this instruction also clears chosen regular (horizontal and vertical) faces. Thisis necessary because a previously defined inclined plane may also consist of horizontal orvertical faces which have to be unselected as well.

• • •

Choose faces 3pt inclined plane1. nplane Plane ID number, as defined above.

2. x1, y1, z1 xyz-coordinates of the first point on the plane.

3. x2, y2, z2 xyz-coordinates of the second point on the plane.

4. x3, y3, z3 xyz-coordinates of the third point on the plane.


6. xmin, xmax x-range of the block.

7. ymin, ymax y-range of the block.

8. zmin, zmax z-range of the block.

Faces which have the appropriate plane ID, whose centroids lie within the distance ptol ofthe plane which is defined by the three points, and whose centroids are within the rectangularblock defined by the three ranges are chosen.

Note that if the plane defined by the three points is parallel to one coordinate axis, thepre-processor will automatically use the ID of the plane parallel to that axis, and theuser-defined plane ID will be ignored.

• • •

2.4.5 Selecting Elements

We can use the following instructions to alter the set of chosen elements.


Clear chosen elementsAll elements in the domain will be flagged as not chosen. This is recommended if you areunsure of which elements are chosen due to previously issued instructions.

• • •

Choose elements allAll elements in the domain will be chosen. This is useful if you wish to assign a property toall elements in the grid.

• • •

Choose elements by zone1. nval Zone number.

Elements which have zone numbers equal to the given value are chosen.• • •

Choose elements x plane1. x1 The x-coordinate of the plane.


Elements within distance ptol of the plane defined by the equation x = x1 will be chosen.• • •

Choose elements y planeAs above but for the y-plane.

• • •

Choose elements z planeAs above but for the z-plane.

• • •

Choose elements 3pt plane1. x1, y1, z1 xyz-coordinate of the first point.





Elements whose centroids are within distance ptol of the plane defined by the three pointswill be chosen. This allows you to choose planes of elements with an arbitrary orientation.

• • •

Choose elements block1. x1, x2 x-range of the block.



Elements whose centroids are within the rectangular block defined by the three ranges arechosen. Note that the values given for one, two or all of the ranges can be identical and inthat case, the block will collapse to a plane, line or point respectively.

• • •

Choose elements block by layer1. x1, x2 x-range of the block.



4. nlaybot, nlaytop Bottom and top element layer numbers.

Elements whose centroids are within the rectangular block which is defined by the threecoordinate ranges, and which lie within the element layers defined by nlaybot and nlaytopare chosen. These layer numbers do not correspond to those given during grid generationbut are simply defined by numbering each sheet of elements from 1 (bottom) to n− 1 (top)where n is the number of node sheets (2-D meshes) making up the grid.

This instruction is intended for grids that are regular in the x- and y-directions, but whichhave variable z-values for a given element layer. It can be used if the top and bottomelevations of a 3-D element layer vary spatially.

Note that the values given for one, two or all of the ranges can be identical and in that case,the block will collapse to a plane, line or point respectively.


• • •

Choose elements by layer1. nlaybot, nlaytop Bottom and top element layer numbers.

Elements which are between the bottom and top layers are chosen.• • •

Choose elements topAll elements which are in the top layer are chosen.

• • •

Choose elements list1. fname Name of the file which contains the list of element numbers.

The file consists of a list of element numbers, one entry per line. The procedure exitsautomatically when end-of-file is reached. The elements in the list are chosen.

• • •

Choose elements xyz list1. fname Name of the file which contains the list of xyz-coordinates.

One set of coordinates should be entered per line. If a coordinate falls within an element,then that element is chosen. Note that this instruction only works for rectangular structuredmeshes with the standard element numbering scheme, where the number of nodes in each ofthe x-, y-, z-directions (nx, ny, nz) is defined. It does not work for irregular grids.

• • •

Choose elements am1. fname Name of the AlgoMesh chosen elements file am prefix.echos.description.

2. nsheet bot, nsheet top Bottom and top sheet numbers.

Elements flagged as true in the file and that are between the bottom and top sheet arechosen.


• • •

The following instructions allow you to choose elements based on raster surfaces, as describedin Section F. Since rasters are independent of the 3-D mesh, they do not have to be re-generated if the mesh changes, as is the case with GMS formatted surfaces that have valuescorresponding to each node in the 2-D mesh.

Choose elements between raster surfaces1. rasterfile Name of the raster file for the bottom surface.

2. rasterfile Name of the raster file for the top surface.

The xy-coordinates of the element centroid are used to determine if it falls in a valid cell(i.e. a cell that has no missing values) in both raster files. If it does, the coordinates areused to interpolate a raster value from the cell’s four corner values. If the z-coordinate ofthe element centroid is greater than the raster value of the bottom surface, and less thanthe raster value of the top surface, then the element is chosen.

• • •

The following instructions use the same input data structure except that a single raster fileis read and used for comparison:

Choose elements above raster surfaceChoose elements below raster surface

The following instructions use the same input data structure except that there is an additionalconstraint that the element is chosen only if its current zone number is zero. They areintended to be used in conjunction with the instruction Assign zone zero:

Choose elements between raster surfaces, iprop zeroChoose elements above raster surface, iprop zeroChoose elements below raster surface, iprop zero

The following instructions use the same input data structure except that GMS scalar filesare read instead of raster files. The element is chosen based on the z-coordinate of the firstnode in it’s node list:

Choose elements between gms surfacesChoose elements above gms surfaceChoose elements below gms surface

Choose elements from arcview ascii thickness map1. arcfile Name of the ArcView ASCII file.

Reads an ArcView ASCII file containing thickness values (e.g. overburden thickness). For


each 3-D element, it’s position (row and column) in the raster is determined and it’s centroidis calculated. It is chosen if its centroid is greater than the surface elevation minus thethickness at that location.

• • •

Choose elements horizontal circle1. x mid, y mid, z mid xy-coordinates of the centre of the circle and elevation of the

circle.



4. rtol Horizontal tolerance.

Elements whose centroids are within a vertical distance ptol of elevation z mid, and withina horizontal distance rtol of the circle with centre x mid, y mid and radius radius arechosen. This allows you to choose elements in a domain that has a circular ground-plan.

• • •

2.5 Simulation Control Options

2.5.1 General

Once the grid generation step is completed, the pre-processor generates a set of data for adefault problem by assuming saturated, steady-state flow in a non-fractured, homogeneousporous medium. The porous medium properties for the default problem, which are hardwiredin the code, are listed in Table 2.5. By default, the finite-element approach is used anda transport simulation is not done. If the default problem setup and material propertiesare acceptable, it is likely that the only additional data required to complete the definitionof the problem are some flow boundary conditions, which can be assigned as described inSection 2.7.

Transient flowCauses HydroGeoSphere to perform a time-stepping, transient flow solution.

• • •

UnsaturatedCauses HydroGeoSphere to perform a variably-saturated flow solution.


• • •

Do transportCauses HydroGeoSphere to perform a transport solution.

• • •

If surface loading with hydromechanical coupling is required, you must issue the followinginstruction:

Surface loadingCauses HydroGeoSphere to consider surface loading with hydromechanical coupling.

• • •

The following instructions are used to define the behaviour of the Travel Time ProbabilityPackage described in Section 2.10.

Travel time PDFDefines if a travel time PDF computation is to be performed.

• • •

Travel time CDFDefines if a travel time CDF computation is to be performed.

• • •

Travel time PDF from CDFDefines if the travel time PDF must be deduced from the CDF at observation points.

• • •

Mean ageDefines if a mean age/mean life expectancy computation is to be performed.

• • •

Snapshot mean ageCauses HydroGeoSphere to compute the mean age under transient flow conditions at eachsimulation output time. Note that each simulation output is assumed to be a steady-state


flow condition.• • •

Snapshot mean life expectancyCauses HydroGeoSphere to compute the mean life expectancy under transient flow con-ditions at each simulation output time. Note that each simulation output is assumed to bea steady-state flow condition.

• • •

Backward-in-timeDefines if flow is to be reversed (backward transport solution). This command only worksfor a single conservative species.

• • •

Evaluate capture zoneDefines if an outlet capture zone is to be evaluated. This command only works for a singleconservative species.

• • •

Species attributionDefines the species number (absolutely necessary in the case of multi-species transport).

• • •

These instructions are of general interest:

Y verticalCauses HydroGeoSphere to assume that the y-coordinate points in the vertical direction(i.e. instead of the z-coordinate).

This instruction does not switch coordinates, but merely cause HydroGeoSphere to usethe y-coordinate of a node to calculate the total hydraulic head (pressure + elevation) forvariably-saturated simulations. It is intended to be used for variably-saturated flow problemswhen using triangular prism elements, when one wants to have the triangular mesh (whichis defined in the xy-plane) to be oriented along the vertical direction.

• • •

Data check only


Causes HydroGeoSphere to halt execution after reading all data files, initializing arrays,etc., but prior to the start of the solution procedure

This command can be useful for very large problems, where it is desirable to make sure thatall the input is correct before actually doing the simulation.

• • •

Defined flowThis command defines the flow conditions for the simulation based on the initial conditionsand boundary conditions defined in the prefix.grok file and applies the predefined flowconditions for the entire solute transport simulation.

• • •

2.5.1.1 Finite-Difference Options

Finite difference modeCauses HydroGeoSphere to use the finite difference approach instead of the default finiteelement method.

• • •The following instructions affect the transport simulation in a general way when finite dif-ference method is being used.

Compute fd cross termsCauses HydroGeoSphere to compute cross terms explicitly when a finite difference repre-sentation is chosen, which, by default, are ignored.

• • •

Control volumeCauses the control-volume finite difference approach to be used instead of the defaultstandard finite difference approach. This instruction has no effect when the finite elementapproach is being used because the control volume approach is always used in that case.

• • •

2.5.1.2 Matrix Solver

The matrix solution procedure consists of three phases: initialization, preconditioning andsolution. The instructions presented here can be used to control the preconditioning and


solution phases in order to increase the efficiency of the model.

The default preconditioning scheme is level-based factorization without red/black systemreduction. Improving model performance requires a good understanding of these options,and so if you are unsure you should just use the default settings. However, if you decide toexperiment with the solver preconditioning parameters, here are a few suggestions for doingso:

1. For transient, simple (i.e. small number of nodes) problems, level-based preconditioningworks better, because the static data structure analysis does not need to be done foreach time step.

2. For steady state or complex problems, drop tolerance preconditioning works better,because WATSIT spends most of its time in the solution phase, not the preconditioningphase.

3. For a very smoothly varying solution (e.g. a weakly stressed, homogeneous propertyfield) red/black reduction will speed convergence.

Level of fill1. level Level of fill.

Assigns the level of fill to be preserved in level-based factorization, which defaults to 0. Ifdrop tolerance preconditioning is used, this value is not used.

• • •

Red black reductionTells the solver to use red black reduction. This can be used either using level-based or droptolerance preconditioning.

• • •

Drop tolerance preconditioningTells the solver to use drop tolerance preconditioning. This will remove elements based onhow small they are. The default threshold is 0.1.

• • •

Drop tolerance threshold1. thres Drop tolerance threshold.


Assign a new drop tolerance threshold.• • •

Once the preconditioning phase is complete, the matrix can be solved using several accelera-tion techniques. The following command can be used to change the solver procedure:

Solver acceleration technique1. iaccel Type of acceleration to use.

Assigns a new value for the acceleration technique for the linear solver, which defaults to 3(CGSTAB-P). Appropriate values are 0 (CG, for symmetric matrices only), 1 (OrthoMin), 2(CGS), 3 (CGSTAB-P) or 4 (GMRES). If unsure, don’t use this command.

• • •

No matrix scalingTells the solver not to use matrix scaling preconditioning.

• • •

2.5.2 Timestep Control

Before discussing the available instructions for controlling the behaviour of a transientsolution, some background information is required. The pre-processor grok generates anarray of target times, which are derived from the following sources:

• Times specified by the user to meet timestep constraints.

• Times specified by the user to meet output requirements.

• Times at which transient boundary condition values change.

This target time array is passed to HydroGeoSphere, which uses it to produce timestepvalues. In addition, as discussed in Section 2.5.2.1, adaptive timestepping can be used toadjust the timestep values based on changes in head, saturation and/or concentration asthe solution progresses.

The following instructions can be used to modify the time-stepping behaviour of a transientsolution:

Initial time1. tinit Initial time [T].


Assigns a new value for the initial time, which defaults to zero. This is useful if you arerestarting the simulation and want to index the times used to an earlier run.

• • •

Initial timestep1. val Initial timestep size [T].

Assigns a new value for the initial timestep, which defaults to 0.01 time units.• • •

Maximum timestep1. val Maximum timestep size [T].

Assigns a new value for the maximum timestep size, which defaults to 1025 time units.• • •

Time varying maximum timestep1. time(i), max timestep(i)...end Simulation time [T] and maximum timestep [T]

list.

This command assigns a maximum timestep to each simulation time in the specified list.• • •

Minimum timestep1. val Minimum timestep size [T].

Assigns a new value for the minimum timestep size, which defaults to 10−10 time units.If the timestep becomes smaller than this value as a result of the adaptive timesteppingprocedure, HydroGeoSphere will stop and issue a diagnostic message.

• • •

Target times1. target time(i)...end Target times [T] list.


Listed times are added to the current set of target times.• • •

Generate target times1. tstart Start time [T].

2. delta Initial time step size [T].

3. tinc Time step multiplier [-].

4. dtmax Maximum time step size allowed [T].

5. tend End time [T].

New target times are generated from the start time tstart to end time tend by repeatedlyadding the time step delta, which is increased each time by the multiplier tinc until itreaches a maximum size of dtmax.

• • •

Output times1. output time(i)...end Output time [T] list.

Listed times are added to the current set of output times (i.e. times for which you wantdetailed output). Note that these values will automatically become part of the target timelist.

• • •

Auto save on1. asv interval Time interval in seconds for auto-saving restart files.

This command reads a wall clock time interval in seconds with which restart files forhead and concentration will be automatically recorded/updated in prefixo head.asv andprefixo conc.asv. The last time saved can be found in the prefixo.lst file.

• • •

2.5.2.1 Adaptive Timesteps

If required, HydroGeoSphere can modify timestep values as the solution proceeds, basedon the transient behaviour of the system (see Equation 3.102). The following instructions can


be used to activate this feature and to set targets for specific variables (e.g. pressure head,saturation etc.). These targets are used to modify timestep size as the solution proceeds.

Head control1. dhead allowed Maximum allowed absolute change in nodal head during any time

step [L].

• • •

Water depth control1. ddepth allowed Maximum allowed absolute change in nodal surface water depth

during any time step [L].

• • •

Saturation control1. dsat allowed Maximum allowed absolute change in nodal saturation during any time

step [L].

• • •

Newton iteration control1. nnri allowed Maximum allowed number of Newton–Raphson iterations during any

time step.

• • •

DDF Picard iteration control1. npicard allowed Maximum allowed number of density-flow Picard iterations during

any time step.

• • •

Concentration control1. dconc allowed Maximum allowed absolute change in nodal concentration during any

time step.


• • •

Concentration control, multi-species1. dconc allowed(i) Maximum allowed absolute change in nodal concentration for theith species during any time step. This command needs to be repeated, once per species,each on a separate line.

• • •

Mass change control1. dmass change allowed Maximum allowed absolute change in mass during any time

step [L].• • •

Mass error control1. dmass error allowed Maximum allowed absolute mass error during any time step

[L].• • •

The following instructions are used to generate a timestep multiplier according to Equa-tion 3.102. The multiplier is constrained to lie between a lower and upper bound (inclusive),which by default is the interval [0.5, 2]. If you would like to modify these limits, you maydo so via the following instructions:

Maximum timestep multiplier1. val Maximum timestep multiplier value.

Assigns a new value for the maximum timestep multiplier, which defaults to 2.• • •

Minimum timestep multiplier1. val Minimum timestep multiplier value.

Assigns a new value for the minimum timestep multiplier, which defaults to 0.5.• • •


2.5.3 Saturated Flow

Pressure head inputCauses all heads which are input to be treated as pressure heads instead of hydraulic heads.

• • •

Freshwater pressure headCauses all heads which are input and output to be treated as freshwater pressure headsinstead of hydraulic heads.

• • •

Fluid pressureCauses all heads which are input and output to be treated as fluid pressures instead ofhydraulic heads.

• • •

No fluid mass balanceThis instruction suppresses the calculation of fluid mass balance information which is, bydefault, computed at each time step.

• • •

Flow time weighting1. tw Time-weighting factor for the flow solution.

Assigns a new value for the time-weighting factor for the flow solution, which defaults to1.0. Values must be greater than 0.0 and less than or equal to 1.0.

• • •

Flow solver maximum iterations1. maxfit Maximum number of flow solver iterations.

Assigns a new value for the maximum number of flow solver iterations, which defaults to2000.

• • •


Flow solver convergence criteria1. restol Flow solver convergence criteria.

Assigns a new value for the flow solver convergence criteria, which defaults to 10−10.Convergence is obtained when this criteria is less than the absolute maximum value of theresidual (error) of the latest flow solution. For the matrix equation

[A]x = b

where [A] is the coefficient matrix, x the vector of unknowns, and b is a vector of knownvalues, the residual vector r for a given vector x is

r = b− [A]x

• • •

Flow solver detail1. isolv info Flow solver detail level.

Assigns a new value for the flow solver detail level, which defaults to 0. This value controlsthe level of detail of solver performance information printed to the screen and listing file,and can have values of 0 (no information) or 1 (full information).

• • •

2.5.4 Variably-Saturated Flow

By default, HydroGeoSphere uses the upstream weighting scheme (weighted harmonicmean) for relative permeability, with an upstream weighting factor value of 1.0. The defaultbehaviour can be changed with the following commands:

Upstream weighting factor1. upwfactor Upstream weighting factor.

Assigns a new value for the upstream weighting factor, which defaults to 1.0. This valueshould be in the range of 0.5 (central weighting) to 1.0 (upstream weighting).

• • •


Central weightingCauses HydroGeoSphere to use central weighting (weighted arithmetic mean) instead ofupstream weighting.

• • •

Primary variable switchingCauses HydroGeoSphere to use the primary variable substitution technique outlined inSection 3.13.3.

• • •

If desired, the default values of tolf and tolb, the upper and lower limits for variablesubstitution (see Equation 3.99) can be changed with the following commands:

Upper limit1. switch t Upper limit of the variable substitution approach, tolf in Equation 3.99.

The default value is 0.99.

• • •

Lower limit1. switch f Lower limit of the variable substitution approach, tolb in Equation 3.99.

The default value is 0.89.

• • •

2.5.4.1 Newton Iteration Parameters

The following parameters can be used to control the Newton-Raphson iteration scheme forsolution of the variably-saturated flow problem as described in Section 3.13.2.

Newton maximum iterations1. maxnewt Maximum number of Newton iterations.

Assigns a new value for the maximum number of Newton iterations, which defaults to 15. Ifthis number is exceeded during a time step, the current time step value is reduced by halfand a new solution is attempted.


• • •

Newton minimum iterations1. minnewt Minimum number of Newton iterations.

Assigns a new value for the minimum number of Newton iterations, which defaults to 0.• • •

Jacobian epsilon1. epsilon Jacobian epsilon.

Assigns a new value for the Jacobian epsilon, which defaults to 10−4. The Jacobian epsilonis the shift in pressure head used to numerically compute the derivatives in the Jacobianmatrix. As a rule of thumb, a value equal to 10−5 times the average pressure head in thedomain is recommended.

• • •

Newton absolute convergence criteria1. delnewt Newton absolute convergence criteria.

Assigns a new value for the Newton absolute convergence criteria, which defaults to 10−5.Convergence of the solution occurs when the maximum absolute nodal change in pressurehead over the domain for one Newton iteration is less than this value.

• • •

Newton residual convergence criteria1. resnewt Newton residual convergence criteria.

Assigns a new value for the Newton residual convergence criteria, which defaults to 10−8.Convergence of the solution occurs when the maximum absolute nodal residual (see Sec-tion 2.5.3) in the domain for one Newton iteration exceeds this value.

• • •

Minimum relaxation factor for convergence1. minrelfac convergence Minimum relaxation factor to declare the convergence.


Assigns a new value for the minimum relaxation factor for convergence, which defaults to0.95. Convergence of the solution occurs only when the relaxation factor is larger than theminimum.

• • •

Newton maximum update for head1. NR dhtol Newton maximum update for head.

Assigns a new value for the Newton maximum update for head, which defaults to 1.0. Thisvalue is used to calculate the underrelaxation factor ωr according to

ωr = NR dhtolmax(dhr)

hr = hr−1 + ωr · dhr

where max(dhr) is the computed maximum update for head in rth Newton iteration andhr is the head flow solution after r iterations. As NR dhtol becomes smaller, the Newtonsolution becomes more stable but with possibly more iterations. For highly nonlinearproblems for which Newton linearization easily fails to converge, it is recommended to setthis value smaller.

• • •

Newton maximum update for depth1. NR ddtol Newton maximum update for depth.

Assigns a new value for the Newton maximum update for water depth, which defaults to10−2. The same as NR dhtol above but applies only to water depth.

• • •

Newton absolute maximum residual1. NR max resnorm Newton absolute maximum residual value (must be strictly posi-

tive). By default this tolerance is set to zero, which is treated the same as ∞.

If after any iteration the Euclidean norm of the Newton residual exceeds NR max resnorm,then the Newton iteration is restarted with a smaller time step.

• • •

Newton maximum residual increase


1. NR resnorm fac Newton maximum residual increase.

Assigns a new value for the Newton maximum residual increase, which defaults to 1030. Ifafter any iteration the Newton residual increases by more than NR resnorm fac, then theNewton loop is restarted with a smaller time step.

• • •

Remove negative coefficientsForces negative inter-nodal conductances to zero. Negative inter-nodal conductances resultin inter-nodal flow from lower to higher heads and can cause oscillatory behavior duringNewton iterations [Letniowski and Forsyth, 1991].

• • •

Nodal flow check tolerance1. n flow check tol Assigns a new value for the nodal flow check tolerance, which

defaults to 10−2.

The nodal flow check ensures that the relative local (nodal) fluid mass balance is acceptableat all nodes:

Qin −Qout + dM

Qin< n flow check tol

We note that absolute fluid mass balance can always be satisfied against a global convergencecriteria if local inflows, outflows, and mass accumulation are significantly small, that is,

(Qin −Qout + dM) < global tolerance

where Qin, Qout, and dM (mass accumulation) are significantly small. This type of con-vergence test can lead to a deterioration in the transport solution, as the concentration isdefined as solute mass per unit fluid mass.

• • •

No nodal flow checkTurns off the nodal flow check feature. In cases where a transport solution is not required,the nodal flow check is not necessary.

• • •

Underrelaxation factor1. under rel Underrelaxation factor.


Assigns a new value for the underrelaxation factor for the Newton iteration, which defaultsto 1. This value can range from 0 (full underrelaxation) to 1 (no underrelaxation).

• • •

Compute underrelaxation factorCauses the underrelaxation factor ω to be computed according to the following methoddescribed by Cooley [1983]:

ωr+1 =

3+s

3+|s| if s ≥ −11

2|s| if s < −1

where

s = er+1

erωrif r > 1

1 if r = 1In the equations above, r and r + 1 represent the previous and current iteration level, ωrand ωr+1 represent the underrelaxation factor for the previous and current iteration levels,and e represents the maximum value of the largest difference between head values for twosuccessive iterations, er = maxi |ψri − ψr−1

i |.• • •

Compute underrelaxation factor limit1. dellim Upper limit on the computed underrelaxation factor.

Assigns a new value for the upper limit on the computed underrelaxation factor, whichdefaults to 1000. A suggested value is 10 times the system domain thickness.

• • •

Minimum relaxation factor allowed1. min relfac allowed Minimum value allowed for computed underrelaxation factor.

Assigns a new value for the lower limit of the computed underrelaxation factor, whichdefaults to 10−3. If not at the first timestep and the computed underrelaxation factor is lessthan this value, then the current timestep is cut in half and the Newton–Raphson iterationloop is restarted.

• • •

Newton information


Causes HydroGeoSphere to write more detailed information to the listing file about theperformance of the Newton iteration process.

• • •

2.5.5 Discrete Fracture Flow

By default, HydroGeoSphere does not simulate discrete fracture flow unless a discretefracture flow zone is created using the methods and instructions outlined in Section 2.8.2.

Also by default, HydroGeoSphere uses the common node approach to define the discretefracture flow domain. If the dual-node approach is required, you must issue the followinginstruction:

Dual nodes for fracture flow

2.5.6 Surface Flow

By default, HydroGeoSphere does not simulate surface flow unless a surface flow zone iscreated using the methods and instructions outlined in Section 2.8.2.

Dual nodes for surface flowCauses HydroGeoSphere to use the dual-node approach to define the discrete surfaceflow domain. By default, the common node approach is used.

• • •

2.5.7 Transport

Transport time weighting1. twc Time-weighting factor for the transport solution.

Assigns a new value for the time-weighting factor for the transport solution, which defaultsto 0.5. Values can range from 0.0 (explicit) to 0.5 (central or Crank–Nicholson) or 1.0 (fullyimplicit). Fully implicit time-weighting is less prone to exhibit oscillations but more proneto numerical smearing than central time-weighting.

• • •

Peclet number1. pectol Peclet number.


Assigns a new value for the Peclet number, which defaults to 1020. The Peclet number doesnot influence the solution in any way, but is merely used to generate warning messages.The Peclet number can be computed as

Pe = v∆xD

where v is a flow velocity, ∆x is an element length, in this case in the x-direction, andD is a dispersion coefficient. It is a measure of the adequacy of mesh fineness, with largenumbers indicating poor spatial discretization. The large default value serves to suppressthe generation of warning messages.

• • •

Output peclet numberThis instruction causes HydroGeoSphere to write the Peclet number for each element tothe file prefixo.peclet number, at the first timestep only.

• • •

Courant number1. courtol Courant number.

Assigns a new value for the Courant number, which defaults to 1020. The Courant numberdoes not influence the solution in any way, but is merely used to generate warning messages.The Courant number can be computed as:

Ce = v ∆t∆x

where v is a flow velocity, ∆x is an element length, in this case in the x-direction, and∆t is the timestep length. It is a measure of the adequacy of timestep size, with largenumbers indicating poor temporal discretization. The large default value serves to suppressthe generation of warning messages.

• • •

Transport solver convergence criteria1. restolc Transport solver convergence criteria.

Assigns a new value for the transport solver convergence criteria, which defaults to 10−10.Convergence is obtained when this criteria is less than the absolute maximum value of theresidual (error) of the latest transport solution.

• • •


Transport solver detail1. isolv infoc Transport solver detail level.

Assigns a new value for the transport solver detail level, which defaults to 0. This valuecontrols the level of detail of solver performance information printed to the screen and listingfile, and can have values of 0 (no information) or 1 (full information).

• • •

Transport solver maximum iterations1. maxtit Maximum number of transport solver iterations.

Assigns a new value for the maximum number of transport solver iterations, which defaultsto 2000.

• • •

Upstream weighting of velocities1. almax, btmax, gammax Upstream weighting factors in the x-, y-, and z-directions,

respectively.

Causes upstream-weighting of velocities, which by default is disabled. Values can range from0.0 (no upstream-weighting) to 1.0 (full upstream weighting). Note that these variablesdo not apply for the control volume case, where full upstream weighting is always applied.

• • •

Flux limiter for transportThis instruction causes HydroGeoSphere to use the van Leer flux limiter as described inSection 3.9.1.

• • •

Iteration parameters flux limiter1. maxiter flim, resmax flim, delmax flim Maximum number of iterations, residual

and absolute convergence criteria respectively for the non-linear flux limiter iterationprocedure.

Assigns new values to the parameters that affect the behaviour of the van Leer flux limiter,and which default to 15, 10−5, and 10−8, respectively.


• • •

Overland advective solute exchange onlyThis instruction only affects transport in coupled surface/subsurface systems, and causesHydroGeoSphere to neglect dispersive/diffusive exchange between the two domains. Itis intended to be used to gauge the relative importance of advective versus dispersive ex-change or when comparing HydroGeoSphere to codes that neglect dispersive exchange.

• • •

Fracture advective solute exchange onlyThis instruction only affects transport in coupled fracture/subsurface systems, and causesHydroGeoSphere to neglect dispersive/diffusive exchange between the two domains. Itis intended to be used to gauge the relative importance of advective versus dispersive ex-change or when comparing HydroGeoSphere to codes that neglect dispersive exchange.

• • •

The following three instructions can be used to define a threshold concentration for flaggingoutput and optionally stopping a run.

Detection threshold concentration1. detection threshold conc Detection threshold concentration [M L−3]. This instruc-

tion sets the value that is used to control the behaviour of the next two instructions.

• • •

Flag observation nodes if exceed detection threshold concentrationCauses HydroGeoSphere to tag observation well output with the string > detectionthreshold if the concentration at the node exceeds detection threshold conc, definedabove.

• • •

Stop run if flux output nodes exceed detection threshold concentrationCauses HydroGeoSphere to halt execution if the concentration at any observation wellnode exceeds detection threshold conc, as defined above.

• • •


2.5.8 Density-Dependent Flow Solution

The following command can be used to control the Picard iteration for the solution of theweakly nonlinear density-dependent flow problem.

Picard convergence criteriaScope: .grok

1. head tol The maximum absolute difference in head for convergence of the Picardloop (10−5 by default).

2. conc tol The maximum absolute difference in concentration for convergence of thePicard loop (10−5 by default).

3. maxits The maximum number of iterations for the Picard loop (100 by default). Ifthe maximum number of iterations is reached without obtaining convergence, the timestep is cut in half and the loop is started over.

Assigns new values to the Picard convergence criteria.• • •

2.5.9 Heat Transfer

To enable heat transfer, you must define the temperature species in the solute definitionblock as described in Chapter 2.6.3.1. Note that the unit for temperature must be °C andthat all heat transfer properties must be given in the SI-units kilogram-meter-second-Celsius.The thermal properties of the solids are specified in the material property file. The followinginstructions can be used to control the heat transfer solution:

Do heat transfer...EndCauses grok to begin reading a group of heat transfer instructions until it encounters anEnd instruction.

• • •


Thermal conductivity of air1. k air [W L−1 K−1] Thermal conductivity of the air phase.

Assigns a uniform value to the thermal conductivity of air.• • •


Specific heat capacity of air1. c air [J kg−1 K−1] Specific heat capacity of the air phase.

Assigns a uniform value to the specific heat capacity of air.• • •

Density of air1. c air [kg m−3] Density of the air phase.

Assigns a uniform value to the density of air.• • •

Thermal conductivity of water1. k l [W L−1 K−1] Thermal conductivity of the liquid phase.

Assigns a uniform value to the thermal conductivity of water. If this instructions is used,the thermal conductivity of water is assumed constant and equal to kl. It is therefore notcalculated from the water temperature, which is the default setting.

• • •

Specific heat capacity of water1. c l [J kg−1 K−1] Specific heat capacity of the liquid phase.

Assigns a uniform value to the specific heat capacity of water. If this instructions is used,the specific heat capacity of water is assumed constant and equal to cl. It is therefore notcalculated from the water temperature, which is the default setting.

• • •

Mechanical heat dispersionCauses mechanical heat dispersion to be simulated. The default is no mechanical heatdispersion.

• • •

The following instruction can be used to define initial temperatures for the problem:

Initial temperature profile


1. temp top [°C] The temperature at the top of the domain.

2. temp grad [m−1 K] The prevailing geothermal gradient.

Calculates a depth profile of temperature and assigns the values to the initial temperature.• • •

The following instructions can be used to define the heat source boundary condition:

Zero order source1. npanel Number of panels in the time-variable, zero-order source function.

2. ton val(i), toff val(i), (bc val(j), j=1,nspeciesmob), i=1,npanel Time on [T],time off [T], and mass of solute produced per unit volume of porous medium solids perunit time [M L−3].

Nodes in the chosen zones area assigned zero-order source boundary conditions.

A panel is a point in time at which the source term is set to a new value. The first panelwould normally start at time zero. The source term given for the last panel will be maintaineduntil the end of the simulation. You can assign a static source term for the duration of thesimulation by setting npanel to 1, ton val to 0.0 and toff val to a large number.

Note that if nspeciesmob is greater than 1, additional values of bc val should be included.

• • •

Exponential zero order source1. heat q zero Heat production [M L−1 T−3] at time t = 0.

2. heat constant Constant [T−1] in the exponential function.

Nodes in the chosen zones area assigned an exponentially decreasing zero-order heat sourceboundary conditions.

• • •

2.5.10 Inactive Elements

These instructions can be used to discretize irregular boundaries with block elements bydeactivating portions of the grid, where all elements become inactive for both the flow andtransport simulation. Elemental assembly is skipped and all nodes that only belong to


the inactive element, and are not at all connected to active elements, are assigned defaultvalues of head and concentration equal to −9999. This option is similar to what is done inMODFLOW to specify inactive cells.

Make element inactiveAll chosen elements will become inactive.

• • •

Make zone inactiveAll elements in the current set of chosen zones will become inactive.

• • •

For a 2-D slice made of 4-node rectangular elements, the following instruction can be usedto make elements inactive:

Make element inactive using shapefile1. arcview prefix Prefix of the ArcView shapefile.

2. unproject file If true, this logical switch causes grok to read grid unprojection dataas described in Section 2.3.10 and to apply it to the data read from the ArcViewshapefile.

3. project file If true, this logical switch causes grok to read grid projection data asdescribed in Section 2.3.10 and to apply it to the data read from the ArcView shapefile.

4. outside If true, elements located outside the area defined in the ArcView shapefilewill become inactive. If false, elements located inside the area will become inactive.

• • •

Write inactive elements to file1. inactive file Name of the file to which the inactive element information will be

written.

Setting up inactive elements with the Make element inactive using shapefile instruction canbe time consuming in grok and this step does not need to be repeated as long as the gridstructure remains the same. This instruction is intended to be used in conjunction with thefollowing instruction.

• • •

Read inactive elements from file


1. inactive file Name of the file from which the inactive element information will beread.

The results of successive calls to this instruction are cumulative, if different sets of inactiveelements are read.

• • •

2.6 Initial Conditions

2.6.1 Subsurface Flow

Initial heads should be given for both steady-state and transient problems since the iterativesolver uses them as a starting point in achieving a solution. These heads can be assigned orread from a file.

Initial head1. hval Initial head [L].

Chosen nodes in the currently active domain (see Section 2.8.1) are assigned an initial headvalue.

• • •

Initial head surface elevationAll nodes in the currently active domain (see Section 2.8.1) are assigned an initial headvalue equal to the surface elevation at the same xy-location.

• • •

Initial head from depth-saturation tableScope: .grok

1. depth(i), saturation(i)...end Depth [L] and saturation [-] list.

Paired values of depth z and saturation S should be entered from smallest to largest depth.The last line of the table must be an end instruction.

Chosen nodes in the currently active domain (see Section 2.8.1) are first assigned a saturationthat is interpolated from the depth-saturation table. The nodes depth is calculated relativeto the node on ground surface at the same xy-location. The computed saturation is then


converted to an initial head value using the constitutive relationships (see Section 2.8.3)for the zone number of the element containing the chosen node. In cases where a node isshared by two elements with different zone numbers, then the zone number of the lowestnumbered element is used.

• • •

Initial head from file1. file name Name of the file that contains the initial head data.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial headvalue that is read from a free-format ASCII file. The heads must be listed in the file inorder from node 1 to node N , where N is the number of nodes in the active domain. Eachline may contain one or more values.

• • •

Initial head from output file1. file name Name of the file that contains the initial head data.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial headvalue which is read from a previously generated output file with a name of the style pre-fixo.head.suffix, where suffix is a 4-digit number identifying the output file. Since it isapplied to the current domain type you can use, for example, prefixo.head.0003 for theporous media and prefixo.head overland.0003 for the surface domain. This can be useful,for example, when a run crashes (since you don’t have to start simulation from scratch) orif you want to use separate solutions of groundwater and surface flow to start a coupledsurface-subsurface simulation.

• • •

Initial head subsurface from surface output file1. file name Name of the file that contains the initial surface domain head data.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial head valueequal to the surface domain head at the same xy-location. The surface heads are read froma previously generated output file with a name of the style prefixo.head overland.suffix,where suffix is a 4-digit number identifying the output file.

• • •

Function x initial head


1. x1, h1 The x-coordinate and initial head [L] value for the first point.

2. x2, h2 The x-coordinate and initial head [L] value for the second point.

Using linear interpolation, chosen nodes in the currently active domain (see Section 2.8.1)are assigned initial head values, based on their x-coordinate and given heads at two points.

• • •

Function z initial headThe same as command Function x initial head but as a function of z.

• • •

Initial head raster1. rasterfile Name of the raster file that contains the initial head data. The file should

be formatted as outlined in Section F.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial headvalue equal to the raster value at the same xy-location.

• • •

Map initial head from rasterScope: .grok

1. rasterfile Name of the raster file that contains the initial head values. The file shouldbe formatted as outlined in Section F.

For each node in each element in the set of currently chosen zones, a value for the initialhead will be interpolated from the raster file data. This instruction currently only generatesinitial head values for the porous medium domain.

• • •

Initial head depth to water table1. depth2wtable Depth of water table below ground surface for initial condition.

For each node in each element in the set of currently chosen zones, a value for the initialhead will be calculated based on the assigned depth to water table.

• • •

Function surface elevation initial head


1. z0, zscale Reference elevation [L] and scaling factor [-].

Initial head h is assigned as a function of the ground surface elevation (zsurf ) according to

h = z0 + zscale · (zsurf − z0)

• • •

Restart file for heads1. flow restart file name Name of the file that contains the results of the previous

flow solution.

All nodes are assigned an initial head value which is read from the file. This allows headsfrom a previous run to be used as initial conditions for a subsequent simulation, for example,if one wants to carry on the simulation further in time without restarting from time zero.

Since, by default, head values for the last time step are output in BINARY format to afile with the suffix prefixo.hen, these are always available for restarting a flow run. It isrecommended that this file be renamed in order to avoid accidentally overwriting it andchanging the restart conditions for a later run.

• • •

Initial head from xyh file1. maximum distance Maximum distance [L] threshold for determining nearest points.

2. ascii text file name Name of the file that contains the xy-coordinates and headvalues.

For each chosen node, an initial head value is assigned from the nearest point in the givenfile only if the distance between the node and the closest point given is smaller than thegiven maximum distance. The ASCII text file contains the number of data points on thefirst line. Subsequent lines contain three floating point values for the xy-coordinates andhead value, i.e., x y h(x, y).

• • •

Initial head from porous mediumThe initial head for any medium is set to be the same as the initial head specified in theporous medium domain.

• • •


Initial head from regional output fileScope: .grok

1. file name Name of the output file from the regional simulation. Typically pre-fix regionalo.head pm.000x for the porous medium domain or prefix regionalo.head olf.000x for the surface domain.

This command needs to come after a regional model is defined using the Regional modelcommand.

• • •

Initial head from regional output file with depth scalingScope: .grok

1. file name Name of the output file from the regional simulation. Typically pre-fix regionalo.head olf.000x for the surface domain.

2. dscale Depth scale factor [-] applied to the surface domain (must be strictly positive).This scaling factor does not affect porous medium heads.

This command needs to come after a regional model is defined using the Regional modelcommand.

• • •

Regional modelScope: .grok

1. prefix regional prefix for the regional simulation model.

This command reads the prefix regionalo.coordinates pm and prefix regionalo.elements pmfiles. If the regional model includes the overland flow domain, then it will also read thecorresponding overland coordinates and elements files.

• • •

Map zone numbers from regional modelScope: .grokThis command can be used to map porous medium, overland, or ET domain zone numbersfrom a regional model. It must come after a regional model is defined using the Regionalmodel command.

• • •


Map zone numbers from regional model by layerScope: .grok

1. i, regional model layer(i), i=1,nlayers local The local model layer number andthe mapped from regional model layer number for each layer in the local model.

This command can be used to map porous medium domain zone numbers on a per layer basisfrom a regional model. It must come after a regional model is defined using the Regionalmodel command. The command may be issued as follows:

Map zone numbers from regional model by layer1 12 13 24 35 4

In this example the local model has five layers. Each row specifies a mapping for a singlelayer in local model. For example, the second row indicates that values in layer 2 of thelocal model are mapped from values in layer 1 of the regional model. Note that a mappingmust be provided for each layer in the local model, but not all layers in the regional modelmay be mapped from (e.g., the regional model in the above example could have more thanfour layers).

• • •

Map K from regional model list fileScope: .grok

1. input k file name Name of the file that contains the variable K data supplied by theuser. The format of the input file is the same as that for the command Read elementalk from file; see Section 2.8.2.1.

This command can be used to map variable K from the regional model which is definedby the Regional model command. It must come after a regional model is defined using theRegional model command.

• • •

Map K from regional model list file by layerScope: .grok

1. input k file name Name of the file that contains the variable K data supplied by theuser. The format of the input file is the same as that for the command Read elementalk from file; see Section 2.8.2.1.


2. i, regional model layer(i), i=1,nlayers local The local model layer number andthe mapped from regional model layer number for each layer in the local model.

This command can be used to map variable K on a per layer basis from the regional modelwhich is defined by the Regional model command. It must come after a regional model isdefined using the Regional model command. The command may be issued as follows:

Map K from regional model list file by layerinput k file name1 12 13 24 35 4

In this example the local model has five layers. Each row specifies a mapping for a singlelayer in local model. For example, the second row indicates that values in layer 2 of thelocal model are mapped from values in layer 1 of the regional model. Note that a mappingmust be provided for each layer in the local model, but not all layers in the regional modelmay be mapped from (e.g., the regional model in the above example could have more thanfour layers).

• • •

Elevation from regional model gb file1. regional gb file Name of a grid builder .nprops file for the regional model. The

elevation data for the regional model will be mapped for the local model for each layer.

• • •

Compute velocity field from head1. v head file Name of the file that contains the results of the previous flow solution.

A flow solution is not performed. Instead, the velocity field is computed from the previousflow solution, a steady-state flow field is assumed, and the transport solution proceeds.

The heads are read from a previously generated output file with a name of the style prefix-o.head.suffix, where suffix is a 4-digit number identifying the output file.

• • •

Compute velocity field from head and conc


1. v head file Name of the file which contains the results of the previous flow solution.

2. v conc file Name of the file which contains the results of the previous transportsolution.

3. vrhomax, vcmax Assumed maximum density [M L−3] and concentration [M L−3].

A flow solution is not performed. Instead, the velocity field is computed from the previousflow solution and transport solution, a steady-state flow field is assumed, and the density-dependent transport solution proceeds.

The heads are read from a previously generated output file with a name of the styleprefixo.head.suffix, where suffix is a 4-digit number identifying the output file.

The concentrations are read from a previously generated output file with a name of thestyle prefixo.concentration.species.suffix, where suffix is a 4-digit number identifyingthe output file.

• • •

2.6.2 Surface Flow

Initial water depth1. val Initial water depth.

Chosen surface flow nodes are assigned an initial depth value.• • •

Initial water depth from file1. file name Name of the ASCII-formatted nodal properties file prefix.ascii nprop.-

description that contains the initial water depth data.

This command assumes that the surface flow domain covers the entire top of the 3-D domain,and contains N nodes, where N is the number of nodes in the 2-D slice. All surface flowdomain nodes (see Section 2.8.1) are assigned an initial water depth value that is read fromfile file name. This file is ASCII formatted, with the water depth values listed in orderfrom node 1 to N .

• • •


2.6.3 Transport

It should be noted that the instructions given here affect the behaviour of one or moresolutes, which should already have been defined according to the instructions given inSection 2.6.3.1.

Currently the initial condition (for both mobile and immobile zones if dual porosity) defaultsto zero unless one of the following instructions are included.

Initial concentration1. bc val(i), i=1,nspeciesmob Initial concentration [M L−3] for each solute.

Chosen nodes in the currently active domain (see Section 2.8.1) are assigned an initialconcentration value.

• • •

Initial concentration from output file1. filename Name of the file that contains the xy-coordinates and concentration [M L−3]

values.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial concentra-tion value which is read from a previously generated output file with a name of the style prefix-o.concentration.suffix, where suffix is a 4-digit number identifying the output file. Since itis applied to the current domain type you can use, for example, prefixo.concentration.0003for the porous media and prefixo.concentration overland.0003 for the surface domain.This can be useful, for example, when a run crashes (since you don’t have to start thesimulation from scratch).

• • •

Initial concentration from xyc file1. filename Name of the file that contains the initial concentration [M L−3] data.

For each of chosen nodes, an initial concentration value is assigned from the closest pointfrom the given file when the distance between the node and the closest point given is smallerthan the given maximum distance. The ASCII text file contains the number of data pointson the first line. Each subsequent line contains three floating point values separated byspaces for the xy-coordinates and concentration value, i.e., x y C(x, y).

• • •

Z function initial concentration


1. z1, conc1 First elevation and concentration [M L−3].

2. z2, conc2 Second elevation and concentration [M L−3].

For all the chosen nodes, initial concentration is assigned as a linear function of the elevationwhich satisfies the two pairs of specified elevation and concentration data.

• • •

Specified concentration from initial concentrationFor all the chosen nodes, a specified concentration boundary condition is applied with theconcentration values from the initial concentration values.

• • •

Initial immobile concentration from output file1. filename Name of the file that contains the initial immobile zone concentration

[M L−3] data.

As above for the command Initial concentration from output file except that immobile zoneinitial concentrations are assigned. This command insures that the mobile and immobilezones will be in equilibrium at the start of a simulation if the same file concentration outputfile is used to define the initial conditions.

• • •

Initial concentration from file1. filename Name of the file that contains the initial concentration [M L−3] data.

All nodes in the currently active domain (see Section 2.8.1) are assigned an initial concen-tration value which is read from a free-format ASCII file. The concentrations must be listedin the file in order from node 1 to node N , where N is the number of nodes in the activedomain. Each line may contain one or more values.

• • •

Initial concentration for zones1. izone(i), czone(i)...end Zone number and initial concentration [M L−3].

This instruction takes as input a list of zone numbers and initial concentrations. Nodes thatare in the currently active domain (see Section 2.8.1), and that are also in elements whose


zone number is in the list will be assigned the listed initial concentration value. All othernodes will be assigned an initial concentration of zero. If a node straddles the boundarybetween one or more zones, an average initial concentration value is assigned.

• • •

Initial immobile zone concentration1. val Initial concentration [M L−3].

All nodes are assigned an initial concentration value for the first solute only.• • •

Initial immobile zone concentration from file1. filename Name of the file that contains the initial immobile zone concentration

[M L−3] data.

All nodes are assigned an initial concentration value, for the first solute only, which is readfrom a free-format ASCII file. The concentrations must be listed in the file in order fromnode 1 to node N , where N is the total number of nodes. Each line may contain one ormore values.

• • •

Restart file for concentrations1. filename Name of the file that contains the concentration [M L−3] results computed

in a previous transport solution.

All nodes are assigned an initial concentration value which is read from the file. Thisallows concentrations from a previous run to be used as initial conditions for a subsequentsimulation, for example, if one wants to carry on the simulation further in time withoutrestarting from time zero.

Since, by default, concentration values for the last time step are output in BINARY formatto a file with the suffix prefixo.cen, these are always available for restarting a transportrun. It is recommended that this file be renamed in order to avoid accidentally overwritingit and changing the restart conditions for a later run.

• • •

Use Pitzer model


With this instructions, fluid density is calculated from species concentrations using Pitzer’sion interaction model. Note that this method can be very time-consuming because fluiddensity is calculated by iterating between density and molality. The default is a faster andnon-iterative empirical approach.

• • •

The following commands define time and depth dependent 1-D temperature profiles for thebulk porous medium and bulk dual continuum domains (Equation 2.97). They are intendedto be used in conjunction with the commands Nonlinear decay with temperature and Dualnonlinear decay with temperature that form part of the solute definition.

Solute 1d temperature profileDefines a depth-dependent 1-D temperature profile for the bulk porous medium. Commandsare read until an End command is encountered. Note that all temperatures must be specifiedin degrees Celsius. For example:

solute 1d temperature profilesurface temperature

0 -7.02592000 -6.15184000 -0.97776000 6.210368000 12.912960000 18.015552000 20.218144000 19.320736000 14.823328000 8.625920000 2.428512000 -4.031104000 -7.0

end

thermal diffusivity2.0e-7

background temperature6.0

maximum depth2.0

integration convergence tolerance0.01


integration maximum iterations20

number of points500

integration memory length15552000.0

end

• • •

Solute dual 1d temperature profileDefines a depth-dependent 1-D temperature profile for the bulk dual continuum. Commandsare read until an End command is encountered. Note that all temperatures must be specifiedin degrees Celsius. See the description of the command Solute 1d temperature profile for anexample of its usage.

• • •

The commands Solute 1d temperature profile and Solute dual 1d temperature profile arecomposed of the following subcommands:

Surface temperature1. time(i), temp(i)...end The time [T] and surface temperature [°C] value list.

At time time(i) the value temp(i) is applied and maintained until time time(i + 1). Thelast value entered in the list will be applied until the end of the simulation.

• • •

Thermal diffusivity1. thermal diff Thermal diffusivity [L2 T−1]. Default value of 2× 10−7 [m2 s−1].

• • •

Background temperature1. background temp Background temperature [°C].

• • •


Maximum depth1. max depth Maximum depth for which the temperature profile is defined [L].

Note that the temperature beyond the maximum depth is constant and is equal to thetemperature at the maximum depth.

• • •

Integration convergence tolerance1. tol Convergence tolerance [T−1/2 °C]. Default value of 0.01 [s−1/2 °C].

Controls the approximation quality of the integral that defines the porous medium tempera-ture. If In is the approximation of the integral on n points and I2n is the approximation ofthe integral on 2n points, then convergence of this approximation is defined by

|I2n − In| ≤ tol,

where n = 2kn0 for k = 0, 1, 2, . . ..• • •

Integration maximum iterations1. maxits Maximum number of iterations for integration convergence. Default value of

20.

Terminates the approximation of the integral that defines the porous medium temperatureafter maxits iterations and issues a warning message to the screen and the .lst file.

• • •

Integration memory length1. memory length Memory length for convolution integral [T]. Default value of

15,552,000.0 [s] (6 months).

The memory length of the convolution integral can be set to control the amount of thermalmemory in the system. After a certain amount of time relative to the past, there shouldbe no influence on the present value of the porous medium temperature. In practice, thememory length of the convolution integral should be set to half the surface temperaturecycle length. For example, if seasonally varying ground surface temperature is cyclic over aperiod of a year, then an appropriate memory length is 6 months (in consistent time units).


If a diurnal temperature cycle was being simulated, then an appropriate memory lengthwould be 12 hours.

• • •

Number of points1. num Number of values in depth-dependent temperature profile. Default value of 500.

At a given time t, a depth-dependent temperature profile is defined as a lookup table over arange of num uniformly spaced depth values between zero and the maximum depth definedby the command Maximum depth. For a given depth value z in this range, the temperatureis interpolated, via linear interpolation, from the endpoints of the bin that contains z. Forany value of z that falls outside this range, the temperature is treated as constant and equalto the temperature of the endpoint nearest to z.

• • •

2.6.3.1 Solute Definition

These instructions can be used to add a new solute (i.e. species) to the system. HydroGeo-Sphere is able to handle more than one solute per simulation, and straight and branchingdecay chains are also supported. An example of a straight decay chain is the followingsystem:

Uranium234 → Thorium230 → Radium226

which indicates that the decay of the radioactive isotope Uranium234 produces the daughterproduct Thorium230, which in turn decays to form Radium226. For an example of a straightdecay chain see Section 4.5.1. Branching decay chains can have a single isotope which decaysinto one or more daughter products, or daughter products which have one or more parents.

Note that a solute can have different values for the decay constant and distribution coefficient(retardation factor for fractured media) in porous, dual or fractured media or from zone tozone in a single medium.

SoluteCauses grok to begin reading a group of solute definition instructions until it encounters anEnd instruction.

• • •


Name1. spname Solute name.


Changes the solute name, which defaults to Species n, where n is the current solute number.

• • •

Free-solution diffusion coefficient1. diffrac Free-solution diffusion coefficient [L2 T−1].

Assigns a new value for the free-solution diffusion coefficient, Dfree (Equation 2.104). Thedefault value is 0.0.

• • •

Parents1. npa Number of parent species for the current species.

2. kparen(i), aparen(i), i=1,npa Parent species number and the mass fraction.

Assigns a value for the number of parent species, which defaults to 0. The mass fraction isa number between 0 and 1 which defines how much of the parent species transforms intothe daughter species (i.e. the current species).

• • •

The following parameters affect porous media solute properties:

Decay constant1. clambda First-order decay constant [T−1].

Assigns a uniform value for the solute first-order decay constant, λ (Equation 2.102), for allporous media zones in the domain. The default value is 0.0 (no decay).

• • •

Zoned decay constant1. clambda(j), j=1,nzones First-order decay constant [T−1] for each porous media

zone j.

Assigns a unique value for the solute first-order decay constant, λ (Equation 2.102), to eachporous media zone in the domain. The default value is 0.0 (no decay).

• • •


Nonlinear decay with saturation1. coeff Nonlinear decay coefficient α [T−1].

2. shape Nonlinear decay shape parameter β [-].

Causes the first-order decay constant, λ (Equation 2.102), across all porous medium zonesin the domain to be computed according to the nonlinear decay equation

λ = α ·min(1, Sβw

),

where Sw is the water saturation. Note that this command overrides the commands Decayconstant and Zoned decay constant for the same species.

• • •

Zoned nonlinear decay with saturation1. coeff(j), shape(j), j=1,nzones Nonlinear decay coefficient α [T−1] and shape pa-

rameter β [-], respectively, for each porous medium zone j.

Causes the first-order decay constant, λ (Equation 2.102), for each porous medium zone inthe domain to be computed according to the nonlinear decay equation

λ = αj ·min(1, Sβjw

),

where Sw is the water saturation and j indexes the jth porous medium zone. Note that thiscommand overrides the commands Decay constant and Zoned decay constant for the samespecies.

• • •

Nonlinear decay with temperature1. ref coeff Decay coefficient at reference temperature α [T−1].

2. ref temp Reference temperature Tr [°C].

3. act energy Activation energy of the reaction Ea [J mol−1].

Computes a temperature dependent first-order decay coefficient, λ (Equation 2.102), accord-ing to the modified Arrhenius equation

λ = α · exp[Ea(T − (Tr + 273.15))R · T (Tr + 273.15)

],


where T is the temperature of the bulk porous medium [K] and R is the universal gasconstant [J K−1 mol−1]. In order to use this command, the user must issue the commandSolute 1d temperature profile once outside of the solute definition to define a depth-dependent1-D temperature profile of the bulk porous medium. This command can be combined withthe commands Nonlinear decay with saturation or Zoned nonlinear decay with saturation, for thesame species, in which case the decay coefficients have a multiplicative effect. Note, however,that this command overrides the commands Decay constant and Zoned decay constant forthe same species.

• • •

Distribution coefficient1. dkd Distribution coefficient [M−1 L3].

Assigns a uniform value for the solute distribution coefficient, K ′ (Equation 2.103), for allporous media zones in the domain. The default value is 0.0 (no attenuation).

• • •

Zoned distribution coefficient1. dkd(j), j=1,nzones Distribution coefficient [M−1 L3] for each porous media zone j.

Assigns a unique value for the distribution coefficient, K ′ (Equation 2.103), to each porousmedia zone in the domain. The default value is 0.0 (no attenuation).

• • •

Freundlich isotherm1. coeff Freundlich adsorption capacity KF [M−1 L3].

2. rconc Freundlich reference concentration C0 [M L−3].

3. expon Freundlich exponent of non-linearity n [-].

The nonlinear Freundlich isotherm relates the amount of adsorbate in equilibrium, X, tosolute concentration, C, via the empirical relationship

X = KF · C0

(C

C0

)nNote that for n = 1, we recover the linear Freundlich isotherm. The solution distributioncoefficient, K ′ (Equation 2.103), across all porous medium zones in the domain is defined asthe slope of the nonlinear Freundlich isotherm

K ′ = dX

dC= n ·KF

(C

C0

)n−1


Note that this command overrides the commands Distribution coefficient and Zoned distribu-tion coefficient for the same species.

• • •

Zoned freundlich isotherm1. coeff(j), rconc(j), expon(j), j=1,nzones Freundlich adsorption capacity KF,j

[M−1 L3], reference concentration C0,j [M L−3], and exponent of non-linearity nj[-], respectively, for each porous medium zone j.


X = KF,j · C0,j

(C

C0,j

)njNote that for nj = 1, we recover the linear Freundlich isotherm. The solution distributioncoefficient, K ′ (Equation 2.103), for each porous medium zone in the domain is defined asthe slope of the nonlinear Freundlich isotherm

K ′ = dX

dC= nj ·KF,j

(C

C0,j

)nj−1

where j indexes the jth porous medium zone. Note that this command overrides thecommands Distribution coefficient and Zoned distribution coefficient for the same species.

• • •

Solute uptake by plant roots1. partition constant The fraction of solute in the transpiration stream relative to the

full stream (value between 0 and 1) in the porous medium domain [-]. Note that avalue of 1 means full transpiration-stream solute uptake across the plant root depth.

Causes the uptake of solute by plant roots. By default there is no solute uptake.• • •

The following parameters affect the dual media solute properties:

Dual decay constant1. clambda First-order decay constant [T−1].


Assigns a uniform value for the solute first-order decay constant, λd (Equation 2.110), forall dual continua zones in the domain. The default value is 0.0 (no decay).

• • •

Zoned dual decay constant1. clambda(j), j=1,nzones First-order decay constant [T−1] for each dual continua

zone j.

Assigns a unique value for the solute first-order decay constant, λd (Equation 2.110), toeach zone in the domain. The default value is 0.0 (no decay).

• • •

Dual nonlinear decay with saturation1. coeff Nonlinear decay coefficient α [T−1].

2. shape Nonlinear decay shape parameter β [-].

Causes the first-order decay constant, λd (Equation 2.110), across all dual continua zones inthe domain to be computed according to the nonlinear decay equation

λd = α ·min(1, Sβw

),

where Sw is the water saturation. Note that this command overrides the commands Dualdecay constant and Zoned dual decay constant for the same species.

• • •

Zoned dual nonlinear decay with saturation1. coeff(j), shape(j), j=1,nzones Nonlinear decay coefficient α [T−1] and shape pa-

rameter β [-], respectively, for each dual continua zone j.

Causes the first-order decay constant, λd (Equation 2.110), for each dual continua zone inthe domain to be computed according to the nonlinear decay equation

λd = αj ·min(1, Sβjw

),

where Sw is the water saturation and j indexes the jth dual continua zone. Note that thiscommand overrides the commands Dual decay constant and Zoned dual decay constant forthe same species.

• • •

Dual nonlinear decay with temperature


1. ref coeff Decay coefficient at reference temperature α [T−1].

2. ref temp Reference temperature Tr [°C].

3. act energy Activation energy of the reaction Ea [J mol−1].

Computes a temperature dependent first-order decay coefficient, λd (Equation 2.110),according to the modified Arrhenius equation

λd = α · exp[Ea(T − (Tr + 273.15))R · T (Tr + 273.15)

],

where T is the temperature of the bulk dual continuum [K] and R is the universal gas constant[J K−1 mol−1]. In order to use this command, the user must issue the command Solute dual1d temperature profile once outside of the solute definition to define a depth-dependent 1-Dtemperature profile of the bulk dual continuum. This command can be combined with thecommands Dual nonlinear decay with saturation or Zoned dual nonlinear decay with saturation,for the same species, in which case the decay coefficients have a multiplicative effect. Note,however, that this command overrides the commands Dual decay constant and Zoned dualdecay constant for the same species.

• • •

Dual distribution coefficient1. dkd Distribution coefficient [M−1 L3].

Assigns a uniform value for the solute distribution coefficient, K ′d (Equation 2.111), for alldual continua zones in the domain. The default value is 0.0 (no attenuation).

• • •

Zoned dual distribution coefficient1. dkd(j), j=1,nzones Distribution coefficient [M−1 L3] for each dual continua zone j.

Assigns a unique value for the distribution coefficient, K ′d (Equation 2.111), to each dualcontinua zone in the domain. The default value is 0.0 (no attenuation).

• • •

Dual freundlich isotherm1. coeff Freundlich adsorption capacity KF [M−1 L3].

2. rconc Freundlich reference concentration C0 [M L−3].


3. expon Freundlich exponent of non-linearity n [-].


X = KF · C0

(C

C0

)nNote that for n = 1, we recover the linear Freundlich isotherm. The solution distributioncoefficient, K ′d (Equation 2.111), across all dual continua zones in the domain is defined asthe slope of the nonlinear Freundlich isotherm

K ′d = dX

dC= n ·KF

(C

C0

)n−1

Note that this command overrides the commands Dual distribution coefficient and Zoned dualdistribution coefficient for the same species.

• • •

Zoned dual freundlich isotherm1. coeff(j), rconc(j), expon(j), j=1,nzones Freundlich adsorption capacity KF,j

[M−1 L3], reference concentration C0,j [M L−3], and exponent of non-linearity nj[-], respectively, for each dual continua zone j.


X = KF,j · C0,j

(C

C0,j

)njNote that for nj = 1, we recover the linear Freundlich isotherm. The solution distributioncoefficient, K ′d (Equation 2.111), for each dual continua zone in the domain is defined asthe slope of the nonlinear Freundlich isotherm

K ′d = dX

dC= nj ·KF,j

(C

C0,j

)nj−1

where j indexes the jth dual continua zone. Note that this command overrides the commandsDual distribution coefficient and Zoned dual distribution coefficient for the same species.

• • •

The following parameters affect the fracture domain solute properties:

Fracture decay constant


1. clambda f First-order decay constant [T−1].

Assigns a uniform value for the solute first-order decay constant, λf (Equation 2.106), forall discrete fracture zones in the domain. The default value is 0.0 (no decay).

• • •

Zoned fracture decay constant1. clambda f(j), j=1,nzones First-order decay constant [T−1] for each discrete fracture

zone j.

Assigns a unique value for the solute first-order decay constant, λf (Equation 2.106), toeach discrete fracture zone in the domain. The default value is 0.0 (no decay).

• • •

Fracture retardation factor1. rfrac Fracture retardation factor [-].

Assigns a uniform value for the fracture retardation factor, Rf (Equation 2.107), for alldiscrete fracture zones in the domain. The default value is 1.0 (no attenuation).

• • •

Zoned fracture retardation factor1. rfrac(j), j=1,nzones Retardation factor [-] for each discrete fracture zone j.

Assigns a unique value for the fracture retardation factor, Rf (Equation 2.107), to eachdiscrete fracture zone in the domain. The default value is 1.0 (no attenuation).

• • •

The following parameters affect the overland domain solute properties:

Overland decay constant1. clambda o First-order decay constant [T−1].

Assigns a uniform value for the solute first-order decay constant, λ (Equation 2.117), for alloverland flow zones in the domain. The default value is 0.0 (no decay).

• • •

Zoned overland decay constant


1. clambda o(j), j=1,nzones First-order decay constant [T−1] for each overland flowzone j.

Assigns a unique value for the solute first-order decay constant, λ (Equation 2.117), to eachoverland flow zone in the domain. The default value is 0.0 (no decay).

• • •

Overland retardation factor1. rolf Overland flow retardation factor [-].

Assigns a uniform value for the overland retardation factor, Ro (Equation 2.107), for alloverland zones in the domain. The default value is 1.0 (no attenuation).

• • •

Zoned overland retardation factor1. rfrac(j), j=1,nzones Retardation factor [-] for each overland flow zone j.

Assigns a unique value for the overland flow retardation factor, Ro (Equation 2.107), toeach overland zone in the domain. The default value is 1.0 (no attenuation).

• • •

The following instructions can be used to identify certain species. This is especially importantto calculate fluid density and viscosity (for variable-density transport) from individual speciesconcentrations and temperature. Note that fluid temperature is treated as a mobile species.

Sodium speciesThe presently defined species is identified as sodium, Na+.

• • •

The following instructions can be used likewise to identify other species:

Potassium speciesCalcium speciesMagnesium speciesChloride speciesSulphate speciesHydrogencarbonate speciesCarbonate speciesSalt mass fractionTemperature species


By default, no species impacts fluid density or viscosity. This default can be changed withthe following instruction:

Affects fluid propertiesWith this instruction, the presently defined solute has an impact on both fluid density andviscosity.

• • •

Relative concentration1. cmax The maximum relative concentration, corresponding to the fluid with maximum

density. This instruction proved to be especially useful to simulate the lab experimentsby Oswald and Kinzelbach [2004], where the concentration of the fluid with maximumdensity is not one.

2. rhomax The maximum fluid density (which corresponds to the maximum soluteconcentration).

Assigns the maximum relative concentration (defaults to 1) and the maximum fluid density(defaults to 0), respectively.

• • •

Note that instructions like Decay constant and Zoned decay constant are mutually exclusivefor a given solute, and should not appear in the same Solute. . .End block. This also appliesto distribution coefficient definitions for all types of media. You can however, define a solutewith decay or attenuation properties which are uniform throughout the domain while asecond solute has a zoned behaviour.

Since a new species is created each time the instruction Solute is used, any instructions (e.g.Make fractures, Specified concentration, Specified third-type concentration etc. which dependon it should be placed after it in the prefix.grok file.

The following simple example shows how to define a single, conservative, non-decayingsolute called ‘Species 1’ with a free-solution diffusion coefficient of (0.0) zero:

SoluteEnd solute

An example of a more complex system with two solutes and seven material zones is shown inFigure 2.7 for the first solute, called DCB, which only decays in zone 1, and has distributioncoefficients which vary from zone to zone.

solute


nameDCB

free-solution diffusion coefficient3.689e-5 ! free solution diffusion coefficient (m2/d)

zoned decay constant0.693 ! 1 first-order decay constant (1/d)0.0 ! 20.0 ! 30.0 ! 40.0 ! 50.0 ! 60.0 ! 7

zoned distribution coefficient0.0005 ! 1 distribution coefficient (kg/m3)0.0005 ! 20.0005 ! 30.0013 ! 40.005 ! 50.014 ! 60.020 ! 7

end solute

Figure 2.7: Definition of a parent solute with zoned properties.

Figure 2.8 shows how to define the second solute, called BAM, which is a daughter productof DCB, and does not decay. This solute has the same zoned distribution coefficients as thefirst solute.

solutenameBAM

free-solution diffusion coefficient3.7295e-5 ! free solution diffusion coefficient (m2/d)

parents1 ! i.e. DCB! parent # ! mass ratio!========== =============

1 1.0

decay constant


0.0 ! first-order decay constant (1/d)

zoned distribution coefficient0.0005 ! 1 distribution coefficient (kg/m3)0.0005 ! 20.0005 ! 30.0013 ! 40.005 ! 50.014 ! 60.020 ! 7

end solute

Figure 2.8: Definition of a daughter solute with zoned properties.

2.6.3.2 Travel Time Probability

Find zero age zonesHydroGeoSphere will automatically find the inlet (or outlet for the backward problem)nodes and assign the proper initial condition (or boundary condition for the moment equa-tions). This option is valid for the case of age/life expectancy computations at aquifer scale,in which case each node belonging to the inlet/outlet zone is to be assigned a zero age/lifeexpectancy condition.

• • •

Zero travel timeAssigns a zero travel time condition for the chosen nodes.

• • •

2.6.3.3 Heat Transfer

To enable heat transfer, you must define the temperature species in the solute definitionblock as described in Chapter 2.6.3.1. Note that the unit for temperature must be °C andthat all heat transfer properties must be given in the SI-units kilogram-meter-second-Celsius.The thermal properties of the solids are specified in the material property file. The followinginstructions can be used to control the heat transfer solution:

Do heat transfer...EndCauses grok to begin reading a group of heat transfer instructions until it encounters an


End instruction.• • •


Thermal conductivity of air1. k air [W L−1 K−1] Thermal conductivity of the air phase.

Assigns a uniform value to the thermal conductivity of air.• • •

Specific heat capacity of air1. c air [J kg−1 K−1] Specific heat capacity of the air phase.

Assigns a uniform value to the specific heat capacity of air.• • •

Density of air1. c air [kg m−3] Density of the air phase.

Assigns a uniform value to the density of air.• • •

Thermal conductivity of water1. k l [W L−1 K−1] Thermal conductivity of the liquid phase.

Assigns a uniform value to the thermal conductivity of water. If this instructions is used,the thermal conductivity of water is assumed constant and equal to kl. It is therefore notcalculated from the water temperature, which is the default setting.

• • •

Specific heat capacity of water1. c l [J kg−1 K−1] Specific heat capacity of the liquid phase.


Assigns a uniform value to the specific heat capacity of water. If this instructions is used,the specific heat capacity of water is assumed constant and equal to cl. It is therefore notcalculated from the water temperature, which is the default setting.

• • •

Mechanical heat dispersionCauses mechanical heat dispersion to be simulated. The default is no mechanical heatdispersion.

• • •

The following instruction can be used to define initial temperatures for the problem:

Initial temperature profile1. temp top [°C] The temperature at the top of the domain.

2. temp grad [m−1 K] The prevailing geothermal gradient.

Calculates a depth profile of temperature and assigns the values to the initial temperature.• • •

The following instructions can be used to define the heat source boundary condition:


2. ton val(i), toff val(i), (bc val(j), j=1,nspeciesmob), i=1,npanel Time on [T],time off [T], and mass of solute produced per unit volume of porous medium solids perunit time [M L−3].

Nodes in the chosen zones area assigned zero-order source boundary conditions.

A panel is a point in time at which the source term is set to a new value. The first panelwould normally start at time zero. The source term given for the last panel will be maintaineduntil the end of the simulation. You can assign a static source term for the duration of thesimulation by setting npanel to 1, ton val to 0.0 and toff val to a large number.


• • •

Exponential zero order source


1. heat q zero Heat production [M L−1 T−3] at time t = 0.

2. heat constant Constant [T−1] in the exponential function.

Nodes in the chosen zones area assigned an exponentially decreasing zero-order heat sourceboundary conditions.

• • •

2.6.3.4 Auxiliary Features

This section contains auxiliary transport related commands that do not belong to any of theprevious sections.

Effective diffusion coefficient by speciesScope: .grok

1. nzones, nspecies Number of zones and species, respectively.

This command assigns an effective diffusion coefficient for each species within a givengeological unit. The effective diffusion coefficient values by zones and species should beassigned in a material property file (e.g., .mprop) and thus, the command Effective diffusioncoefficient list is required to assign the values.

• • •

Effective diffusion coefficient listScope: .grok.mprops1. diff coeff(i), i=1,nspecies Effective diffusion coefficient [L2 T−1] for each species.

Within a material property file (e.g., .mprop), the effective diffusion coefficient for eachspecies is assigned with this command.

• • •

2.7 Boundary Conditions

2.7.1 General

The boundary condition input routines have been completely rewritten in this version ofHydroGeoSphere. The old routines were developed over the years by many differentdevelopers and for a host of reasons. There was a lack of continuity between the routines


that has made it increasingly difficult to update and maintain HydroGeoSphere. Withthis in mind, a more well defined data structure has been developed for defining boundaryconditions and, where possible, the functionality of the old routines has been incorporated.For the end user, this means having to learn a new approach to defining boundary conditions,but one that we hope will be more logical and therefore easier to understand and apply.

In its simplest form, a boundary condition is defined by a value that is associated witha node, for example, a specified head. In some cases, such as a well that has a variablepumping rate, the value may change temporally. If the well were turned off abruptly thenstarted up again at a later time, the value would not be applied continuously. Some inputsare not defined by a single value, but rather by a two- or three-dimensional field. Forexample, rainfall may be given in the form of 2-D raster data defined in a certain region.Other inputs might be in the form of tables of values at defined locations, which is oftenthe case when we incorporate information from another model. As you can see, we need acombination of data structure and input format that are general, yet flexible.

All flow boundary conditions require inputs for the boundary condition type, node and faceset, and the time-varying inputs described in Sections 2.7.3, 2.7.4, and 2.7.5. The constraintsand Tecplot options are optional values. A general boundary condition layout is shown asthe following instruction:

boundary conditiontype

bc_type

node set/face set/segment setbc_set_name

time value table/time raster table/time file tablebc_time(i), bc_file(i)...end

orbc_time(i), bc_raster(i)...end

orbc_time(i), bc_file(i)...end

constraints/tecplot options !optional not requiredend

Boundary condition...Endgrok reads instructions that define a new boundary condition until it encounters an Endinstruction.

• • •


2.7.2 Set Creation

The generic boundary condition format requires that either a node set, face set, or segmentset be created. Once you have selected nodes you can create the appropriate sets by issuingthe following commands:

Create node setCreates a node set from the selected nodes.

• • •

Create face setCreates a face set from the selected nodes.

• • •

Create segment setCreates a segment set from the selected nodes.

• • •

Additionally if you already have selected faces you can use:

Create face set from chosen facesThe selected faces become a face set that can be used with boundary condition assignments.

• • •

2.7.3 Type

To define what type of boundary condition (e.g. head, flux etc.) is to be applied use:

Type1. bc type The type of boundary condition to be applied.

The allowable flow boundary condition types are described below in detail.• • •


2.7.3.1 Specified Head

This is also known as a first-type, Dirichlet, or constant head boundary condition. It is anodal property so you should first define the subset of nodes for which you want to applythe condition and write them to a nodal data set.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign various specified head boundary conditions:

HeadSets the input type to be a general specified head boundary condition. Note that whenapplying a specified head boundary condition to the overland flow domain it is treated as‘‘water depth’’. If the value of the head boundary condition at an overland flow node isexactly equal to the elevation at that node, then this node will behave a like a sink and willnot add water to the system, even if the water table is below ground surface.

• • •

For example:


node setinflow


end

would define a specified head of 100.0 from time zero for the duration of the simulation forall of the nodes contained in the node set inflow.

These heads can be interpolated or turned on and off as discussed in Section 2.7.

Head equals elevationSets the input type to be a special form of the specified head boundary condition wherehead is set equal to the elevation of the node. This is normally the z-coordinate, unless theinstruction Y vertical has been issued, in which case the y-coordinate is used instead.

• • •

For example:


boundary conditiontypehead equals elevation

node setinflow

end

This example shows that a time-value table is not required, since heads are derived fromthe nodal elevation. However, if you wish to turn the boundary condition on or off, thenthis can be accomplished by including a Time value table instruction:

boundary conditiontypehead equals elevation

node setinflow

time value table0.0 1.010.0 -99999.end

end

The value 1.0 at time zero is ignored, but the NODATA value −99999 at time 10.0 causesthe boundary condition to be turned off and the nodes become unconstrained.

Head equals initialSets the input type to be a special form of the specified head boundary condition wherehead is set equal to the initial head at the node.

• • •

For example:

boundary conditiontypehead equals initial

node setinflow

end

This condition can be turned on and off as discussed above for Head equals elevation.


Each time you issue a Boundary condition...End instruction, a new boundary condition isformed with a unique ID number. HydroGeoSphere processes the boundary conditionsin order and later ones may take precedence over later ones. The position in the grok filedetermines the order.

If the node was assigned a specified head or fluid flux value by a previous instruction thenit might be overwritten by later head boundary conditions, depending on whether or notboth nodes are active at a given time.

2.7.3.2 Specified Flux

This is also known as a second-type, Neumann, specified or constant flux boundary condition.It is an areal property and so you should first choose the subset of faces for which you wantto apply the condition. These faces should normally be part of the outer boundary of thegrid.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign various specified flux boundary conditions:

FluxSets the input type to be a general specified flux boundary condition and converts fluxes tonodal volumetric fluxes [L3 T−1] by multiplying by the contributing area of the chosen face.

• • •

For example:

boundary conditiontypeflux

face settop

time raster table0.0 recharge.ascend

end

would define a specified flux that is mapped from the raster file recharge.asc and is appliedfrom time zero for the duration of the simulation for all of the nodes contained in the faceset top.

RainSets the input type to be a general specified flux boundary condition and converts fluxes to


nodal volumetric fluxes [L3 T−1] by multiplying by the contributing area of the chosen facewhen projected onto the xy-plane.

• • •

Flux nodalSets the input type to be a general specified flux boundary condition and treats the fluxesas nodal volumetric fluxes [L3 T−1] which are applied directly to nodes in the given node set.

• • •

For example, the following boundary condition declaration would assign a specified nodalflux that is read from the input file nflux.txt and is applied from time zero for the durationof the simulation for all of the nodes contained in the node set top. Note that the numberof entries in the file must be the same as the number of nodes in the set.

boundary conditiontypeflux nodal

node settop

time file table0.0 nflux.txtend

nodal flux reduction by pressure head0.010.1

end

These fluxes can be interpolated or turned on and off as discussed in Section 2.7. In caseswhere flux boundary inputs overlap, fluid fluxes will be accumulated. Note that the definitionof wells or tile drains (see Section 2.8.2.4) in the problem may create a non-zero specifiedflux boundary condition.

The following two instructions can be used to constrain the Flux nodal boundary condition.

Nodal flux reduction by pressure head1. min pressure head Minimum pressure head threshold hmin [L].

2. max pressure head Maximum pressure head threshold hmax [L].

The specified nodal flux can be optionally reduced as a function of the nodal pressure headto avoid pumping from the dry materials. Let Q0 denote the specified flux value and h the


pressure head. Then, for Q0 < 0 the updated flux value Q is defined as

Q =

0, h ≤ hminα2(1−α)Q0, hmin < h < hmaxQ0, h ≥ hmax

,

where α = (h− hmin)/(hmax − hmin).• • •

The old instructions Specified volumetric flowrate and Specified volumetric flowrate, headconstrained are no longer used, as they are covered by the boundary condition type Fluxnodal. If you want to force the nodal flux to operate within a specified hydraulic head range,you can do so with the following instruction.

Nodal flux head constraints1. bc constraint 1, bc constraint 2 Minimum and maximum constraining head values

[L] for positive nodal flux (i.e. inflow).

2. bc constraint 3, bc constraint 4 Minimum and maximum constraining head values[L] for negative nodal flux (i.e. outflow).

If the nodal flux is positive, and the head at the node is less than bc constraint 1, thenthe flux will be applied until such time as the head at the node exceeds bc constraint 2.Once the head at the node exceeds bc constraint 2, then the flowrate will be set to zerountil such time as the head at the node drops below bc constraint 1.

If the flowrate is negative, and the head at the node is greater than bc constraint 3,then the flowrate will be applied until such time as the head at the node drops belowbc constraint 4. Once the head at the node drops below bc constraint 4, then theflowrate will be set to zero until such time as the head at the node exceeds bc constraint 3.

• • •

Irrigation on demandSets the input type to be a general specified flux boundary condition that adds a prescribedvolume of water to the surface of the model over a given time duration. An irrigation eventis triggered if the pressure head at a user specified observation point in the porous mediadomain drops below a user specified threshold. The volume of water added is computed bymultiplying the contributing area of a chosen face when projected onto the xy-plane witha user specified water height applied uniformly over the set of chosen faces. An irrigationevent can occur only during the current growing season, which is defined by a time on/offtable. Moreover, within a growing season, irrigation events are restricted to occur at fixedtime intervals defined by the irrigation recurrence interval. For example:


boundary conditiontypeirrigation on demand

face settop

irrigation parametersobservation_pt ! name of observation point-10 ! pressure head threshold0.015 ! total height of water applied86400 ! duration of irrigation event604800 ! recurrence interval of irrigation12960000 23328000 ! time on and time off in year 144496000 54864000 ! time on and time off in year 2end

pressure irrigation table-1 0.015-2 0.035-3 0.045-4 0.05

-10 0.075end

end

In this example, irrigation events of duration one day (86400 s) can occur once per week(604800 s) within each growing season. The first potential irrigation event is at the start ofthe first growing season (12960000 s). The input parameters are specified by the commandIrrigation parameters and optionally by the command Pressure irrigation table described below.

• • •

Irrigation parameters1. obs pt name Name of the observation point at which pressure head is evaluated to

trigger an irrigation event.

2. thresh Pressure head [L] threshold to trigger an irrigation event.

3. height Height [L] of water applied during an irrigation event.

4. duration Time duration [T] of an irrigation event.

5. interval Time interval [T] between consecutive irrigation events.


6. ton(i), toff(i),...end Time on [T] and time off [T] table. The time values shouldsatisfy the following set of inequalities:

ton(1) < toff(1) < ton(2) < toff(2) < · · · < ton(n) < toff(n),

where n is the number of panels. An irrigation event can occur at time t if and only ifton(i) ≤ t < toff(i) for some i ∈ 1, . . . , n.

This command specifies the input parameters for the boundary condition type Irrigation ondemand.

• • •

Pressure irrigation table1. pressure(i), height(i),...end Pressure head [L] and irrigation water height [L] table.

This command specifies that the height of water applied for the duration of an irrigationevent be dependent on the pressure head at the observation point. It is an optional command,which if used, causes the water height to be defined via linear interpolation from the giventable. In the absence of this command, the height of water applied during an irrigationevent is given by the value specified in the command Irrigation parameters.

• • •

2.7.3.3 Fluid Transfer

This is also known as a third-type, or Cauchy boundary condition and consists of a headvalue at a distance and a hydraulic conductivity representing the intermediate material. Thedirection of fluid flow, either in, or out, of the boundary condition, is determined hydraulichead and the reference head at some distance. The flux rate is determined by the gradientand hydraulic conductivity. This boundary condition may be assigned to the faces at theedge (side) of a model to represent the regional influence on the model domain. For example:

boundary conditiontypefluid transfer

face setoutflow

time value table0 100end


fluid transfer coefficients1e-5 ! hydraulic conductivity1e3 ! distance

end

would assign a fluid transfer with a head value of 100 m at a distance of 1000 m and ahydraulic conductivity of 10−5 m/s for the material external to the boundary condition.

2.7.3.4 Free Drainage

Assigns a free drainage boundary condition, as described in Section 3.7.1 to nodes on allfaces in the specified set. These faces should be on the surface of the domain.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign free drainage boundary conditions:

Free drainageSets the input type to be a free drainage boundary condition.

• • •

For example:

boundary conditiontypefree drainage

face setoutflow

end

This example shows that a time-value table is not mandatory. However, if you wish to turnthe free drainage boundary condition on or off, then this can be accomplished by includinga Time value table instruction:

boundary conditiontypefree drainage

face setoutflow

time value table


0.0 1.010.0 -99999.0end

end


2.7.3.5 Potential Evapotranspiration

This is a special form of the second-type, Neumann, specified or constant flux boundarycondition which is used in conjunction with evapotranspiration properties which can bedefined as described in Section 2.8.5. It is an areal property and so you should first choosethe subset of faces for which you want to apply the condition. These faces should be part ofthe top boundary of the grid, and in this case the top boundary must be coincident withthe 2-D slice which was used to define the 3-D mesh. This means that you cannot usethe boundary condition if the Y vertical instruction has been used. This restriction arisesbecause of grid numbering assumptions which are made when applying evapotranspirationas a function of depth. Note also that if ET domains are not defined and this boundarycondition is applied, then grok will stop and issue a warning message.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign various specified flux boundary conditions:

Potential EvapotranspirationSets the input type to be a special specified flux boundary condition and converts theevaporative fluxes to nodal volumetric fluxes [L3 T−1] by multiplying by the contributingarea of the chosen face.

• • •

For example:

boundary conditiontypepotential evapotranspiration

face settop


end


would define a potential evapotranspiration of 0.001 from time zero for the duration of thesimulation for all of the nodes contained in the face set top.

Although this instruction is currently restricted to be applied to porous media only, thepotential evapotranspiration is applied to the surface water domain and subsurface domainin a stepwise manner. Nodes in the chosen faces and as a function of depth may be assigneda time-variable flux value, depending on factors such as the current nodal saturation, whichmay inhibit for example, transpiration from occurring.

2.7.3.6 River Flux

Assigns a river flux boundary condition, as described in Section 3.7.1 to nodes in the specifiedset. These nodes are normally located on the surface of the domain. For river flux nodes,water may flow in or out of the domain depending on the difference in head between theriver node and the specified river head value.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign a river flux boundary condition:

Simple riverSets the input type to be a river flux drainage boundary condition.

• • •

For example:

boundary conditiontypesimple river

node setmy_river

time value table0.0 25. 1.e-5end

end

This example shows the use of a Time value table instruction to define the river head (25)and river conductance (10−5) values. This would not be very useful in most cases, sinceconductance and head vary from node to node along a river. In such cases, the inputs wouldbe defined by a Time file table, with unique values given for each node:

boundary conditiontype


simple river

node setmy_river

time file table0.0 my_river.lst

1000. noneend

end

Here, the river flux boundary condition would become inactive after time 1000 and thenodes would become unconstrained. In this case, the file my river.lst would contain twovalues per line, the river conductance and head value, and one line for each node in the set.

2.7.3.7 Drain Flux

Assigns a drain flux boundary condition, as described in Section 3.7.1 to nodes in the specifiedset. These nodes are normally located on the surface of the domain. The fundamentaldifference between river and drain flux nodes is that drain nodes only allow water to flowout of the system, depending on the difference in head between the drain node and thespecified pressure head value.

The following instruction can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign a drain flux boundary condition:

Simple drainSets the input type to be a drain flux drainage boundary condition.

• • •

For example:

boundary conditiontypesimple drain

node setmy_drain

time value table0.0 25. 1.e-5end

end


This example shows the use of a Time value table instruction to define the pressure head(25) and drain conductance 10−5 values. This would not be very useful in most cases, sinceconductance and head would vary from drain node to drain node. In such cases, the inputswould be defined by a Time file table, with unique values given for each node:

boundary conditiontypesimple drain

node setmy_drain

time file table0.0 my_drain.lst

1000. noneend

end

Here, the drain flux boundary condition would become inactive after time 1000 and thenodes would become unconstrained. In this case, the file my drain.lst would contain twovalues per line, the drain conductance and head value, and one line for each node in the set.

2.7.3.8 Makeup Water

The boundary condition Makeup water is similar to Simple drain in that its behavior iscontrolled by the difference between the pressure head at a specified set of nodes and thespecified head value. These nodes typically belong the surface domain. The fundamentaldifference between them is that Makeup water only allows water to flow into the system,whereas Simple drain only allows water to flow out of the system. The following instructioncan be used as input to the Type instruction inside the Boundary condition...End instructiongroup to assign a Makeup water boundary condition:

Makeup waterAssigns a makeup water boundary condition to nodes in the specified set. These nodes canbe located in either the surface or porous media domains. The makeup water boundarycondition adds water to the system if the pressure head falls below the specified value andbecomes unconstrained if head is greater than the specified value. Note that water is onlyallowed to enter the system and cannot exit the system. For example:

clear chosen nodeschoose node100 100 100

create node set


nmakeup

boundary conditiontypemakeup water

node setnmakeup

time value table0.0 1.25 1e8end

end

This example shows the use of a Time value table instruction to define the pressure head(1.25) and conductance (108) values. In this case, the boundary condition will preventpressure head from dropping below 1.25 m. The high conductance value ensures that thereis no resistance to the addition of water.

• • •

2.7.3.9 Surface Loading

It is a nodal property, but because surface loading is applied to all nodes of a vertical columnof nodes, only one node of the column needs to be chosen.

Specified stress variation1. npanel Number of panels in the time-variable specified stress function.

2. ton val(i), bc val(i), i=1,npanel Time on [T] and specified stress variation [L T−1]list.

Chosen nodes in the currently active domain (see Section 2.8.1) are assigned a time-variablespecified stress variation value. The specified stress variation value corresponds to the term

∂ (σzz/ρg)∂t

(2.6)

which has units of [L T−1] and corresponds to an equivalent freshwater head change perunit time.

• • •

Specified stress variation from file


1. fname Name of the file that contains the list of nodes to which specified stress variationwill be assigned.

The input file must contain the following data for each node: the node number and numberof panels on one line, followed by a two column list with entries of time [T] and stressvariation [L T−1]. The length of the list must match the number of specified panels. Forexample:

n1 3t1 sv1t2 sv2t3 sv3n2 2t1 sv1t2 sv2n3 2t1 sv1t2 sv2: :

Nodes listed in the file and in the currently active domain (see Section 2.8.1) are assigned aunique stress variation value. The specified stress variation value is described in the previouscommand.

• • •

Echo 1d loading conditionsIf this command is included in the input file, a listing of the loading conditions will be issuedin the prefixo.eco file.

• • •

2.7.3.10 Hydromechanical Stress

Hydromechanical stresses can be computed externally and used as input to grok using thefollowing instruction:

Elemental stress field from files1. npanel Number of panels (i.e. files) defining the time-variable external stress field.

2. ton val(i), esvfile(i), i=1,npanel Time on [T] and name of file containing elementalstress values [L] list.


This information is passed to HydroGeoSphere. At each timestep, the current time iscompared to the array ton val to determine whether or not to apply the update the currentset of elemental stress values by reading the next file in the list.

Each file must be in ASCII format and contain a list of elemental stress values (i.e. onevalue for each element in the 3-D domain), expressed as equivalent freshwater head.

• • •

2.7.3.11 Surface Flow

Critical depth and zero-depth gradient boundary conditions can be assigned to segmentswithin a specified set as described in Section 3.7.2. These segments should be part ofthe overland flow domain and are typically located on the outer boundary. The reservoirboundary condition can be assigned to nodes within a specified set that belong to either theoverland flow domain or the 1-D channel flow domain.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group.

Critical depthSets the input type to be a critical depth boundary condition. For example:

boundary conditiontypecritical depth

segment setoutflow

end

This example shows that a time-value table is not mandatory. However, if you wish to turnthe critical depth boundary condition on or off, then this can be accomplished by includinga Time value table instruction:

boundary conditiontypecritical depth

segment setoutflow

time value table0.0 1.0

10.0 -99999.0


endend


• • •

Zero-depth gradientSets the input type to be a zero-depth gradient boundary condition. For example:

boundary conditiontypezero-depth gradient

segment setoutflow

end

If you wish to turn the zero-depth gradient boundary condition on or off, then this can beaccomplished by including a Time value table instruction.

• • •

ReservoirThe reservoir boundary condition facilitates the simulation of surface water managementschedules that aim to remove water from instream (overland and/or 1D channel domain)flow, store water, and release water into stream flow. While water removal from instreamflow is dependent upon water being present in the requisite domain, the storage is managedas an offline numerical reservoir, and hence volumetric storage is independent of meshdiscretization and topographic resolution. The reservoir boundary condition can be activein either the overland or the channel domain. For example:

boundary conditiontypereservoir

namenorth_dam

node setnorth_dam_control_node

time value table


0 0.52592000 07776000 -0.5

10368000 0end!-----------------------------reservoir storage detailsinitial reservoir storage0maximum reservoir storage1500000base reservoir storage100000!-----------------------------instream water withdrawal controlpressure head0.05 0.25 !-pressure head endpoints for interpolated withdrawalratestecplot output

end

In the above example, water would be removed from the target node in the overland (orchannel) domain at a rate of 0.5 m3 s−1 between 0 s and 2592000 s, and then released fromstorage back into the target node at a rate of 0.5 m3 s−1 between 7776000 s and 10368000 s.The pressure head endpoints specify the pressure (water depth) range wherein withdrawalrates are reduced (via linear interpolation) on account of limited water availability, withwithdrawal stopped below a pressure threshold of 0.05 m, and with the full withdrawal raterealized at pressures above 0.25 m.

• • •

2.7.3.12 Snowmelt

You can assign a snowmelt boundary condition to faces in the specified set. These facesshould be part of the overland flow domain and are typically located on the outer boundary.

The following instructions can be used as input to the Type instruction inside the Boundarycondition...End instruction group to assign snowmelt boundary conditions:

SnowmeltSets the input type to be a snowmelt boundary condition.

• • •

For example:

boundary condition


typesnowmelt

face settop

time value table! time snowfall air temperature

0 2.5848E-07 -72592000 2.0447E-07 -6.15184000 2.5463E-07 -0.97776000 0 6.210368000 0 12.912960000 0 1815552000 0 20.218144000 0 19.320736000 0 14.823328000 0 8.625920000 0 2.428512000 2.7006E-07 -431104000 2.7006E-07 -4

end

interpolate

snowmelt constants100.0d0 ! snow density5.78704E-06 ! melting constant0.0 ! sublimation constant0.0 ! threshold temperature0.1 ! initial snow depth

tecplot outputend

This example shows the use of a Time value table instruction to define the snowfall andair temperature values with the density of snow, melting constant, the rate of sublimation,threshold temperature, and the initial snow depth being assigned with Snowmelt constantsinstruction.

Snowmelt constants1. snow rho Snow density [M L−3].

2. snow melt Snow melting constant [M L−2 T−1 °C−1].


3. snow sublimation Snow sublimation constant [M L−2 T−1].

4. snow threshold temp Snow threshold temperature [°C].

5. snow initial depth Initial snow depth [L].

Defines values for the snow density, snow melting constant, snow sublimation constant,snow threshold temperature, and the initial snow depth.

• • •

2.7.4 Node and Face Sets

Some boundary condition types are applied to nodes (e.g. head) while others are applied tofaces (e.g. flux). To define the group of nodes use:

Node set1. bc set name Name of the node set to apply the boundary condition to.

• • •

To define the group of faces use:

Face set1. bc set name Name of the face set to apply the boundary condition to.

• • •

2.7.5 Time-Varying Inputs

To define more complex spatial and temporal properties for a boundary condition use:

Time value table1. bc time(i), bc val(i)...end The time [T] and boundary condition value list.

At time bc time(i) the value bc val(i) is applied and maintained until time bc time(i+1).The last value entered in the list will be applied until the end of the simulation.

• • •

Time raster table


1. bc time(i), bc raster(i)...end The time [T] and raster file name list.

At time bc time(i) the raster file bc raster(i) is applied and maintained until timebc time(i+1). The last raster file entered in the list will be applied until the end of thesimulation. HydroGeoSphere uses the node (or face centroid) xy-coordinate for eachmember of the set to interpolate a value for the boundary condition at that point.

• • •

The following instructions use the same input data structure except they are applied to xz-or yz-coordinates:

Time raster xz tableTime raster yz table

Time file table1. bc time(i), bc file(i)...end The time [T] and file name list.

At time bc time(i) the values read from file bc file(i) are applied and maintained untiltime bc time(i+1). The data from the last file entered in the list will be applied until theend of the simulation. HydroGeoSphere reads a list of values from the file and assignsthem in order to the current set of nodes or faces, depending on what type of boundarycondition is being applied. The number of values in the file must match the number ofnodes or faces in the set or grok will stop with an error message. Note that first value inthe file must be the number of data values in the file.

• • •

This instruction can be used in conjunction with other instructions to create files of nodalvalues and then read them in to define boundary conditions. For example, these instructions:

clear chosen nodeschoose nodes x plane0.01.e-5

nodal function z to fileinflow.txt! Z value0.0 0.3. 10.

10. 4.end

create node set


inflow

create a file inflow.txt which contains a value for each currently chosen node. It usesthe nodal z-coordinate to interpolate the value from the tabulated function of z-coordinateversus value. We can now use the file like this:


node setinflow

time file table0.0 inflow.txt11. noneend

end

Note that we use the node set inflow in conjunction with the file inflow.txt. Any mismatchin the number of nodes between the node set file and the data file will cause grok to stopwith an error message.

Time-field data table from regional1. filename The name of the local to regional sheet mapping file.

2. bc time(i), bc file(i)...end The time [T] and filename list.

This command reads a time-value table for head values from a regional model and mapsthem by sheet to the local model for a set of chosen nodes. The local to regional sheetmapping specifies for each sheet in the local model, the corresponding sheet in the regionalmodel to which it maps. This mapping is helpful when the local model does not have asmany layers as the regional model and thus the number of node sheets are different betweenthe two models. For example, in a local model with five sheets, the mapping file could looklike:

1 12 13 24 35 3


The regional model head files give the head values for each node in the regional model. Attime bc time(i) the values read from file bc file(i) are applied and maintained until timebc time(i+1). Values read from the last file are applied until the end of the simulation.

• • •

2.7.5.1 Interpolation

Time-varying boundary conditions change abruptly from value bc val(i) to value bc val(i+1)at time bc time(i+1). To have HydroGeoSphere use linear interpolation to smooth thevalues used between time panel endpoints use:

Interpolate

This command causes time-varying values to be interpolated between panel values for theboundary condition currently being defined. This results in a smoother application of thetime-varying function.

• • •

2.7.5.2 Scaling Factor

Sometimes it is desirable to scale the values being used in a boundary condition time serieswithout changing the actual values entered. This can be done by using the Scaling factorcommand which scales the entire time series. The scaling factor can be used with any of theTime value table, Time file table, and Time raster table inputs.

Scaling factor1. factor Scaling factor [-].

This command scales the values in a boundary condition time series without changing theactual values entered. For example, the following code block would cause the Flux boundarycondition to be scaled by a factor of two. Meaning, that from time t = 0 to t = 3000 a fluxof 10−5 would be applied to the boundary condition.

clear chosen nodeschoose nodes top

create face settop


boundary conditiontypeflux

face settop

time value table0.0 5e-6

3000.0 0.0end

scaling factor2.0

end

• • •

2.7.5.3 Intermittent Conditions

Boundary conditions can be turned on and off by assigning special NODATA values insteadof normal input in the time-value, time-raster and time-file tables. For example, the defaultNODATA value is −99999 and the following table:


... etc


1000.0 -99999.02000.0 100.0end

end

would apply the specified head of 100 from time 0.0 to time 1000.0 and then allow the nodeto revert to an unconstrained condition until time 2000.0, when a specified head of 100.0would again be applied for the duration of the simulation.

For rasters and files the default NODATA value is the string ‘‘none’’.


If for some reason you need to change the default NODATA value you can the commandNodata value.

Nodata value1. nodata value The value that indicates there is no data.

• • •

The following instructions may be used to change the NODATA values for rasters and files:

Nodata rasterNodata file

2.7.6 Tecplot Output

Tecplot formatted output files can be created for a specific boundary condition using thisinstruction:

Tecplot outputThis command causes node specific information about the boundary condition to be writtenat each output time. The results are written to a file called prefixo.bc.bcname.dat

• • •

2.7.7 Transport

There are three basic options available for assigning boundary conditions to the transportsolution. These are to specify either first-type (concentration), second-type (mass flux,concentration gradient), or third-type (Cauchy) at a node. Although these are typicallyapplied to nodes located on the surface of the domain, first- and second-type boundaryconditions can can also be applied to internal nodes.

Once they are defined, you can check the transport boundary conditions using the followinginstruction, which causes the current configuration to be written to the prefixo.eco file:

Echo transport boundary conditionsCauses the current boundary conditions to be written to the prefixo.eco file.

• • •


2.7.7.1 Specified Concentration

This is also known as a first-type, Dirichlet, or constant concentration boundary condition.It is a nodal property so you should first choose the subset of nodes for which you want toapply the condition and then issue one of the following instructions.

If the node was assigned a specified concentration, mass flux or third-type value by a previousinstruction then it will not be modified by subsequent specified concentration instructions.

Specified concentration1. npanel Number of panels in the time-variable concentration function.

2. ton val(i), toff val(i), (bc val(i,j), j=1,nspeciesmob), i=1,npanel Time on[T], time off [T], and specified concentration [M L−3] of each species.

Chosen nodes in the currently active domain (see Section 2.8.1) are assigned a time-variableconcentration value. If a node was previously assigned a specified concentration, it willremain in effect.

A panel is a point in time at which the specified concentration is set to a new value. Thefirst panel would normally start at time zero. The concentration given for the last panelwill be maintained until the end of the simulation. You can assign a static concentrationfor the duration of the simulation by setting npanel to 1, ton val to 0.0 and toff val to alarge number.

Note that if nspeciesmob is greater than 1, additional values of bc val should be included.For example, with three panels and two species the input format is

3 ! npanelton1 toff1 bcval11 bcval12ton2 toff2 bcval21 bcval22ton3 toff3 bcval31 bcval32

• • •

Specified concentration from file1. fname Name of the file which contains the time-varying concentration information.

This file should contain the following input data:

1. nnde Number of nodes to be assigned concentration data.

2. npanel Number of panels in the time-variable concentration function.

3. ton val(i), toff val(i), i=1,npanel Time on [T] and time off [T] list.


4. node(k), (bc val(i,j), i=1,npanel, j=1,nspeciesmob), k=1,nnde Node numberand specified concentration [M L−3] of each species.

For example, with two nodes, three panels, and three species the file format is

2 ! nnde3 ! npanelton1 toff1ton2 toff2ton3 toff3n1bcval11 bcval12 bcval13bcval21 bcval22 bcval23bcval31 bcval32 bcval33n2bcval11 bcval12 bcval13bcval21 bcval22 bcval23bcval31 bcval32 bcval33

Listed nodes are assigned the time-variable concentration values contained in the file. If anode was previously assigned a specified concentration it will remain in effect.

Although all nodes in the file share the same time on/time off panel information the concen-tration values in each panel can vary from node to node.

• • •

2.7.7.2 Specified Mass Flux

This is also known as a second-type, Neumann, or constant mass flux boundary condition,that is applied to a subset of nodes. You should therefore first choose the subset of faces forwhich you want to apply the condition.

If a selected node was assigned a specified concentration or third-type concentration by aprevious instruction then it will not be modified by further specified mass flux instructions.

If a selected node was assigned a specified mass flux value by a previous instruction thenmass fluxes assigned in by subsequent instructions will be cumulative. This is because massfluxes are applied to faces, and any node common to two such faces requires a contributionfrom each face

Specified mass flux1. npanel Number of panels in the time-variable mass flux function.

2. ton val(i), toff val(i), (bc val(i,j), j=1,nspeciesmob), i=1,npanel Time on[T], time off [T], and specified mass flux [M T−1] of each species.


Chosen nodes in the currently active domain (see Section 2.8.1) are assigned a time-variablemass flux value. This is a passive injection of solute mass which has no effect on the flowsolution. If a node was previously assigned a first or third-type concentration, it will remainin effect.

A panel is a point in time at which the specified mass flux is set to a new value. Thefirst panel would normally start at time zero. The mass flux given for the last panel willbe maintained until the end of the simulation. You can assign a static mass flux for theduration of the simulation by setting npanel to 1, ton val to 0.0 and toff val to a largenumber.

Note that the mass flux values are per unit time and the total mass which will be injectedfor a given timestep can be calculated by multiplying the value given here by the timesteplength and the number of chosen nodes.

Note that if nspeciesmob is greater than 1, additional values of bc val should be included.For example, with three panels and two species the input format is

3 ! npanelton1 toff1 bcval11 bcval12ton2 toff2 bcval21 bcval22ton3 toff3 bcval31 bcval32

• • •

Interpolate mass fluxThis command causes time-varying mass fluxes to be interpolated between panel values.This results in a smoother application of the mass flux function.

• • •

2.7.7.3 Specified Third-Type Concentration

This is also known as a third-type or Cauchy boundary condition. It is a distributed propertyso you should first choose the subset of faces for which you want to apply the condition andthen issue one of the following instructions.

If the node was assigned a specified concentration by a previous instruction then it will notbe modified by further specified mass flux instructions.

If the node was assigned a third-type concentration value by a previous instruction thenthird-type concentration fluxes assigned in subsequent instructions will be cumulative. Thisis because third-type concentrations are applied to faces, and any node common to two suchfaces requires a contribution from each face.


Specified third-type concentration1. calcflux A logical switch which determines how fluid fluxes are handled for this

third-type boundary condition. If false, read the following:

(a) userflux Fluid flux value [L T−1].


3. ton val(i), toff val(i), (bc val(j), j=1,nspeciesmob), i=1,npanel Time on [T],time off [T], and specified concentration [M L−3] of each species.

Chosen nodes in the currently active domain (see Section 2.8.1) are assigned a time-variablethird-type concentration value unless they were previously assigned a first-type concentration.

If the variable calcflux is true, nodal fluxes are calculated by HydroGeoSphere from theflow solution and used to calculate the third-type boundary condition. Only positive fluxes(i.e. flowing into domain) are used. If false, HydroGeoSphere reads a flux value userfluxwhich is used instead.

A panel is a point in time at which the specified third-type concentration is set to a newvalue. The first panel would normally start at time zero. The concentration given forthe last panel will be maintained until the end of the simulation. You can assign a staticconcentration for the duration of the simulation by setting npanel to 1, ton val to 0.0 andtoff val to a large number.

Note that if nspeciesmob is greater than 1, additional values of bc val should be included.For example, if calcflux is false, the number of panels is three, and the number of speciesis two, the input format is

falseuserflux3ton1 toff1 bcval11 bcval12ton2 toff2 bcval21 bcval22ton3 toff3 bcval31 bcval32

• • •

Specified third-type concentration from file1. fname Name of the file which contains the time-varying third-type concentration

information.


1. nelem Number of elements.



3. calcflux A logical switch which determines how fluid fluxes are handled for thisthird-type boundary condition. If false, read the following:


4. ton val(i), toff val(i), i=1,npanel Time on [T] and time off [T].

5. nel(k), n1(k), n2(k), n3(k), n4(k), (bc val(i,j), i=1,npanel, j=1,nspeciesmob),k=1,nelem Element number, four node numbers defining a face, and third-type con-centration [M L−3] history of each species.

For example, if the number of elements is two, the number of panels is three, the number ofspecies is two, and calcflux is false, the input format is

2 ! nelem3 ! npanelfalseuserfluxton1 toff1ton2 toff2ton3 toff3nel1 n1(1) n2(1) n3(1) n4(1)bcval11 bcval12bcval21 bcval22bcval31 bcval32nel2 n1(2) n2(2) n3(2) n4(2)bcval11 bcval12bcval21 bcval22bcval31 bcval32

Faces defined by the four nodes in the listed elements in the currently active domain (seeSection 2.8.1) are assigned a time-variable third-type concentration value unless they werepreviously assigned a first-type concentration. It is the responsibility of the user to ensurethat the nodes define a face that is on the exterior of the domain.

For 3-node faces, enter a value of zero for node n4.


If nspeciesmob is greater than 1, additional values of bc val should be included.

Although all elements in the file share the same time on/time off panel information theconcentration values in each panel can vary from element to element.


• • •

Specified third-type concentration from face file1. fname Name of the file which contains the time-varying third-type concentration

information.


1. nface Number of faces.


3. calcflux A logical switch which determines how fluid fluxes are handled for thisthird-type boundary condition. If false, read the following:


4. ton val(i), toff val(i), i=1,npanel Time on [T] and time off [T].

5. nfce(k), (bc val(i,j), i=1,npanel, j=1,nspeciesmob), k=1,nface Face numberand third-type concentration [M L−3] history of each species.

For example, if the number of faces is two, the number of panels is three, the number ofspecies is two, and calcflux is false, the input format is

2 ! nface3 ! npanelfalseuserfluxton1 toff1ton2 toff2ton3 toff3nfce1bcval11 bcval12bcval21 bcval22bcval31 bcval32nfce2bcval11 bcval12bcval21 bcval22bcval31 bcval32

Faces defined by the four nodes in the listed elements in the currently active domain (seeSection 2.8.1) are assigned a time-variable Listed faces in the currently active domain(see Section 2.8.1) and which are located on the exterior of the domain are assigned a


time-variable third-type concentration value unless they were previously assigned a first-typeconcentration.


If nspeciesmob is greater than 1, additional values of bc val should be included.

Although all faces in the file share the same time on/time off panel information the concen-tration values in each panel can vary from face to face.

• • •

Specified third-type flushing1. npanel Number of panels in the time-variable fluid flux function.

2. ton val(i), toff val(i), q val(i), i=1,npanel Time on [T], time off [T], and fluxper unit area [L T−1] list.

A flushing boundary condition q(t)C is applied using the time series of q for chosen faces.• • •

2.7.7.4 Thermal Energy

Specified temperature flux1. npanel Number of panels in the time-variable, specified temperature flux function.

2. ton val(i), toff val(i), bc val(i), bc temp(i), i=1,npanel Time on [T], timeoff [T], specified volume flux (of liquid) [L3 T−1] multiplied by the heat capacity[J kg−1 K−1] and density [M L−3] of the boundary medium, and temperature of waterentering [K] list.

Nodes in both the chosen faces and the currently active domain (see Section 2.8.1) areassigned a time-variable temperature flux value.

Although a fluid volume flux bc val is specified, this does not influence the flow solution inany way. It is merely intended to give the user a straightforward way to input a knownamount of energy to the system, as a function of fluid volume and temperature.

• • •


To define the atmospheric inputs discussed in Section 2.7.1.10, and summarized in Equa-tion 2.130, HydroGeoSphere requires the following set of instructions:

Atmosphere...Endgrok reads instructions that define atmospheric input parameters until it encounters anEnd instruction.

• • •

Incoming shortwave radiation1. npanel Number of panels in the time-variable, incoming shortwave radiation function.

2. ton val(i), value(i), i=1,npanel Time on [T] and incoming shortwave radiation[M T−3] (K↓ in Equation 2.131). Default value is 1.10× 102 J m−2 s−1.

• • •

Sinusoidal incoming shortwave radiation1. npanel Number of panels in the time-variable, sinusoidal incoming shortwave radiation

function.

2. ton val(i), value(i), amp(i), phase(i), period(i), i=1,npanel Time on [T], ver-tical shift [M T−3] (mid-point incoming shortwave radiation, K↓ in Equation 2.131),amplitude [M T−3], phase, and period [T].

• • •

Cloud cover1. npanel Number of panels in the time-variable, cloud cover function.

2. ton val(i), value(i), i=1,npanel Time on [T] and cloud cover [-] (Cc in Equa-tion 2.133). Default value is 0.5.

• • •

Incoming longwave radiation1. npanel Number of panels in the time-variable, incoming longwave radiation function.

2. ton val(i), value(i), i=1,npanel Time on [T] and incoming longwave radiation[M T−3] (L↓ in Equation 2.134). Default value is 3.0× 102 J m−2 s−1.


• • •

Temperature of air1. npanel Number of panels in the time-variable, air temperature function.

2. ton val(i), value(i), i=1,npanel Time on [T] and air temperature [K] (Ta in Equa-tion 2.135). Default value is 15 °C.

• • •

Sinusoidal temperature of air1. npanel Number of panels in the time-variable, sinusoidal air temperature function.

2. ton val(i), value(i), amp(i), phase(i), period(i), i=1,npanel Time on [T], ver-tical shift [K] (mid-point temperature, Ta in Equation 2.135), amplitude [K], phase,and period [T].

• • •

These instructions are used to define the sensible heat flux Qh in Equation 2.137 and latentheat flux QE in Equation 2.138.

Density of air1. npanel Number of panels in the time-variable, air density function.

2. ton val(i), value(i), i=1,npanel Time on [T] and density of air [M L−3] (ρa inEquation 2.137). Default value is 1.225 kg m−3.

• • •

Specific heat of air1. npanel Number of panels in the time-variable, air specific heat function.

2. ton val(i), value(i), i=1,npanel Time on [T] and specific heat of air [L2 T−2 K−1](ca in Equation 2.137). Default value is 7.17× 102 J kg−1 K−1.

• • •

Wind speed


1. npanel Number of panels in the time-variable, wind speed function.

2. ton val(i), value(i), i=1,npanel Time on [T] and wind speed [L T−1] (Va inEquation 2.137). Default value is 1.0 m s−1.

• • •

Sinusoidal wind speed1. npanel Number of panels in the time-variable, sinusoidal wind speed function.

2. ton val(i), value(i), amp(i), phase(i), period(i), i=1,npanel Time on [T], ver-tical shift [L T−1] (mid-point wind speed, Va in Equation 2.137), amplitude [L T−1],phase, and period [T].

• • •

Drag coefficient1. npanel Number of panels in the time-variable, drag coefficient function.

2. ton val(i), value(i), i=1,npanel Time on [T] and drag coefficient [-] (cD in Equa-tion 2.137). Default value is 2.0× 10−3.

• • •

Latent heat of vapourization1. npanel Number of panels in the time-variable, latent heat of vapourization function.

2. ton val(i), value(i), i=1,npanel Time on [T] and latent heat of vapourization[L2 T−2] (LV in Equation 2.138). Default value is 2.258× 106 J kg−1.

• • •

Specific humidity of air1. npanel Number of panels in the time-variable, air specific humidity function.

2. ton val(i), value(i), i=1,npanel Time on [T] and specific humidity of air [M M−1](SHa in Equation 2.138). Default value is 0.01062.

• • •

Soil-Water suction at surface


1. npanel Number of panels in the time-variable, soil-water suction at surface function.

2. ton val(i), value(i), i=1,npanel Time on [T] and soil-water suction at surface [L](ψg in Equation 2.140). Default value is 0.138 m.

• • •

Saturation vapour pressure1. npanel Number of panels in the time-variable, saturation vapour pressure function.

2. ton val(i), value(i), i=1,npanel Time on [T] and saturation vapour pressure[M L−1 T−2] (esat[Tg] in Equation 2.141). Default value is 1.704× 103 Pa.

• • •

Relative humidity1. npanel Number of panels in the time-variable, relative humidity function.

2. ton val(i), value(i), i=1,npanel Time on [T] and relative humidity [-]. Defaultvalue is 0.75.

• • •

Pressure of air1. npanel Number of panels in the time-variable, air pressure function.

2. ton val(i), value(i), i=1,npanel Time on [T] and air pressure [M L−1 T−2] (pa inEquation 2.141). Default value is 1.013× 105 Pa.

• • •

2.7.7.5 Immiscible Phase Dissolution Source

An immiscible phase dissolution source is one in which it is assumed that there is dissolutionof an immobile liquid or solid phase into the subsurface water until all dissolvable materialis exhausted. The following instruction can be used to define the source:

Immiscible phase dissolution data1. diss mass Mass of dissolvable material per unit volume of porous medium.


2. diss conc The aqueous solubility value for the immiscible phase in mass of solute perunit volume of aqueous solution.

Chosen nodes are assigned first-type concentration values equal to diss conc, which aremaintained until all the material associated with a node is dissolved, at which time the nodereverts back to an unconstrained condition. Once unconstrained, any water flowing in willgenerate mass due to the nonzero concentration, and so dissolution nodes should not belocated on the outer surface of the domain.

It is assumed that the total mass of dissolvable material is located in the matrix only.The total mass available for dissolution associated with a given node is then calculated bymultiplying contributing volume (from all shared elements) times the porosity times thevariable diss mass.

• • •

2.7.7.6 Zero-Order Source

A zero-order source is one in which the medium itself produces a solute. For example, somesoils produce radon gas as a result of radioactive decay.


2. ton val(i), toff val(i), (bc val(i,j), j=1,nspeciesmob), i=1,npanel Time on[T], time off [T] and mass of solute produced per unit volume of porous medium perunit time [M L−3 T−1].

Nodes that belong to the chosen zones are assigned zero-order source boundary conditions.

A panel is a point in time at which the source term is set to a new value. The first panelwould normally start at time zero. The source term specified for the last panel will bemaintained until the end of the simulation. You can assign a static source term for theduration of the simulation by setting npanel to 1, ton val to 0.0, and toff val to a largenumber.


• • •

Zero order source saturation threshold1. threshold(i), i=1,nspecies Water saturation threshold [-] for each species.


This command has no effect unless it is used in conjunction with the command Zero ordersource. For each species, it specifies a nodal water saturation threshold for the porous mediadomain. Only those nodes whose water saturation is greater than or equal to the thresholdmay act as zero-order source nodes. By default, the threshold defaults to zero for all species.Hence, any nodes selected by the command Zero order source always act as zero-order sourcenodes.

• • •

2.8 Materials and Material Properties

2.8.1 General

Currently, the following eight domains can be defined in HydroGeoSphere:

1. Porous media

2. Dual continua

3. Discretely-fractured

4. Surface flow

5. ET

6. Channel flow

7. Well

8. Tile

Porous media and dual continua domains are defined by three-dimensional 8-node (brick) or6-node (prism) elements, discretely-fractured, surface flow, and ET domains are defined bytwo-dimensional 4-node (rectangle) or 3-node (triangle) elements, and well, tile, and channelflow domains are defined by 1-node (line) elements. By default, every 3-D element in theproblem domain is a porous media element. Elements of the other four types of domainsmay or may not be defined for a specific problem.

Each porous media element is assigned a zone (i.e. material) number during grid generation.In simple cases, all elements are assigned a zone number of 1, while in more complex cases,elements may have been assigned different zone numbers. For example, if a multilayeredgrid was generated using the instruction Generate layers from slice then the elements wouldbe assigned zone numbers based on the layer number (i.e. elements in the lowest layernumber 1 would be assigned a material number of 1).

By default, all zones, and therefore all elements in the domain, are assigned the samedefault porous media properties, which are listed in Table 2.5. These values are fixed


HydroGeoSphere and cannot be modified by the user unless the code is changed andrecompiled. However, there are other ways of changing the porous media zone properties aswe will discuss below.

The first step in modifying zoned properties for a given problem is to indicate which type ofmedium is to be manipulated. The following instruction does this:

Use domain type1. zone type Can be one of the strings: ‘‘porous media’’, ‘‘dual’’, ‘‘fracture’’, ‘‘surface’’,

‘‘channel’’, ‘‘well’’, ‘‘tile’’, or ‘‘et’’.

Causes grok to read a string defining the type of domain to which additional instructionsshould be applied.

• • •

2.8.1.1 Defining a New Zone

In order to define a new zone, elements of the proper type must first be chosen using theinstructions given in Section 2.4. For example, 3-D block elements must first be selectedbefore a new porous media or dual zone can be defined, 2-D rectangular faces are selectedfor fracture or surface zones, and 1-D segments are selected for channel, well, and tile zones.

In a problem where there are to be dual, fracture, surface, channel, well, or tile zone types,a new zone must be defined since the default situation after grid generation is that there areno elements of these types. This is not the case for porous media zones, where by default all3-D elements are in porous media zone 1.

Once elements of the appropriate type have been chosen, the following command groupsthem into a single zone.

New zone1. num zone Zone number.

Chosen elements are assigned a new zone number.

If num zone is greater than the total number of zones of the current media type, the totalnumber of zones will be incremented and default properties for that media type will beassigned.

• • •

The following set of instructions, inserted in the prefix.grok file would create a new fracturezone.



clear chosen faceschoose faces z plane0.051.e-5

new zone1

Assign zone zeroAssign all elements to zone number zero.

• • •

This instruction was added for the case where we are using multiple surfaces to chooseelements and assign them unique zone numbers. If we first assign all elements to zone zero,we can then find elements that were not chosen by any surface and are still assigned to zonezero.

2.8.1.2 Saving and Retrieving Element Zone Numbers

The following commands can be used to store and retrieve porous media element zonenumbers.

Write zones to file1. zone file Name of the file to which element zone numbers will be written.

• • •

Read zones from file1. zone file Name of the file from which zone information will be read.

For example, if you want elements 1, 5, 9, and 44 to have the zone number 2 and element 8to have the zone number 3, the file would contain:

1 25 29 2


44 28 3

• • •

Read zones from raster for chosen elements1. zone raster Raster containing integers representing zones. Note: zone numbers

should be sequential starting from 1.

Assigns a zone number to selected elements based on a raster containing zone information.

• • •

Read overland zones from raster1. zone raster Raster containing integers representing zones. Note: zone numbers


Assigns a zone number to the overland elements based on a raster containing zone informa-tion. The raster information at the center of each element will be assigned to the element.

• • •

Read overland zones from raster, dominant class1. zone raster Raster containing integers representing zones. Note: zone numbers


Assigns a zone number to the overland elements based on a raster containing zone informa-tion. For each element, the most dominant zone number is assigned to the element by area.

• • •

Read pm zones from voxet fileScope: .grok

1. filename Filename of voxet file (exported to ASCII format), up to 256 characters.

2. colnum Column number in voxet file where zone numbers are found. An integervalue ≥ 4 (the first three columns are reserved for xyz-coordinates of voxel centers).

3. nearest Boolean value (true or false) that defines how the lookup behaves if the querypoint is not found. If true, the zone number of the voxel nearest to the query point isused. Otherwise, an error is raised.


This command assigns material zone information from a GoCAD voxet file that has beenexported to a simplified ASCII format, an example of which is given below. Note that thiscommand applies only to triangular prism or hexahedral block meshes.

# type: Voxet# domain: Depth# nu: 121# nv: 191# nw: 79# step_u: 25 0 0# step_v: 0 25 0# step_w: 0 0 -25# origin: 313150 6071000 400X Y Z Zone_Numbers313150 6071000 400 1313175 6071000 400 1313200 6071000 400 2313225 6071000 400 3313250 6071000 400 3313275 6071000 400 3313300 6071000 400 3

: : : :: : : :

• • •

2.8.1.3 Defining New Zones Using ArcView Files

The following commands can be used to assign porous media and surface flow element zonenumbers using files created by ESRI ArcView. Note that ArcView .shp and .dbf filesshould have the same prefix and be in the same directory. Currently, the following ArcViewfeatures are not supported:

1. Attributes with a date format.

2. Files containing anything except polygons.

3. Shape files with, for example, geographical projections or coordinate translations thatare stored in .shx and .prj files.

Zones from arcview ascii grid1. file name Name of the ArcView ASCII grid file.


2. nodata replace Zone number to assign an element that does not belong to any gridcell.

3. zone offset A nonnegative integer that is added to zone numbers read from theArcView ASCII grid file. Input a value of zero to use the original zone numbers fromthe file.

Chosen elements are assigned zone numbers from the ArcView ASCII grid file (.asc). Sincethese files are two-dimensional, elements with the same x- and y-coordinates will be assignedthe same zone number, regardless of their z-coordinates.

For cells where there is no data value, the variable nodata replace will replace the ArcViewdefault (usually −9999).

The variable zone offset can be used to preserve existing zone numbers. For example, ifa model already has zones defined that are numbered from 1 to 7, and the ArcView filecontains zones numbered from 1 to 4, you can set zone offset to 7, and zones assignedfrom the ArcView file will be numbered from 8 to 11.

• • •

Zones from arcview for chosen elements1. file name Name of the ArcView shapefile without the file extension.

2. nodata replace Zone number to assign an element that does not belong to anypolygon.

3. attribute Field name used to assign the zones, which must be written exactly as inthe .dbf file (case sensitive).

4. zone offset A nonnegative integer that is added to zone numbers read from theArcView shapefile. Input a value of zero to use the original zone numbers from the file.

Chosen elements are assigned zone numbers from the ArcView shapefile (.shp). Since thesefiles are two-dimensional, elements with the same x- and y-coordinates will be assigned thesame zone number, regardless of their z-coordinates.

If an element centroid falls within a polygon, it will receive the attribute of that polygon.Since a polygon may have several attributes, the variable attribute can be used to specifywhich one is to be applied. For example, a shapefile of the geology of a region may containpolygons having the attributes: age, type, domain, unit, formation, and name. Settingthe value of attribute to ‘domain’ will assign zone numbers based on the domain number.The choice of a different attribute will result in a different pattern of zone numbering.The variable attribute is chosen from the database file (.dbf), which can be opened in aspreadsheet program in order to choose the name.

The variable zone offset can be used to preserve existing zone numbers. For example, ifa model already has zones defined that are numbered from 1 to 7, and the ArcView file


contains zones numbered from 1 to 4, you can set zone offset to 7, and zones assignedfrom the ArcView file will be numbered from 8 to 11.

• • •

Since ArcView shapefiles created on a Windows platform may not be binary compatiblewith a UNIX platform, the zone numbers can be written to an ASCII file using the Writezones to file instruction and then read on the UNIX platform using the Read zones from fileinstruction (as described in Section 2.8.1.2. This process can also be useful in cases wherethe Zones from arcview for chosen elements instruction takes a long time to execute, sincethe results can be stored initially and then read much more quickly in subsequent runs.

2.8.1.4 Selecting Zones

These instructions can be used to alter the set of chosen zones for the current zone type (i.e.porous media, dual, fracture or surface.)

Clear chosen zonesReturns the set to the default state, in which no zones are chosen. This is recommended ifyou are unsure of which zones are chosen due to previously issued instructions.

• • •

Choose zones allSelects all zones. This is useful if you wish to assign a property to all zones in the grid.

• • •

Choose zone number1. num zone Zone number.

Selects the zone numbered num zone.• • •

2.8.1.5 Modifying Zoned Properties

There are a number of instructions which can be used to modify the property valuesassociated with a zone or group of zones. Before these instructions are issued, it is necessaryto select the appropriate type of media and then choose the zones which you want to modify.

For example, suppose that you wished to assign a new porous media hydraulic conductivity


to all zones, and thus to all elements in the problem. The following set of instructions,inserted in the prefix.grok file would accomplish this:

use domain typeporous media

clear chosen zones

choose zones all

k isotropic1.e-5

In this case, we are applying the instruction K isotropic to zones of the porous media domain,although it is equally valid to use it with dual-type zones. However, if you try to use thisinstruction with zones of type fracture or surface, warning messages will be issued to thescreen and prefixo.eco file and execution will halt.

The instructions which are valid in specific situations are discussed in the relevant sectionsof the manual. For example, instructions which can be used for defining saturated flowproperties are described in Section 2.8.2.

Another way to define zone properties is through the use of a material properties file, whichshould be located in the same directory as the prefix.grok file. This file contains lists ofmedia-specific instructions which can be used to define properties for one or more namedmaterials. These material properties can then be assigned to the current set of chosen zones.To assign new properties through the use of a material properties file, we first need to issuethe following instruction:.

Properties file1. props file name Name of the material properties file.

This file will be searched for materials given as input to the Read properties instructiondiscussed below.

• • •

The Properties file instruction has two benefits: first, it allows you to create sets of materialproperties and give them meaningful file names and second, it allows you to easily switchbetween material property sets merely by changing the file name given in the prefix.grokfile.

Any line in a material properties file which is completely blank or which begins with anexclamation point (!) is treated as a comment and is ignored by grok. This allows you toinclude comments whenever required.


Each distinct material in the file is identified by a unique label and may contain instructionswhich are to be applied to the current zone type. For example, instructions which can beused for defining porous media properties when simulating saturated flow (as described inSection 2.8.2.1) may be included. Figure 2.9 shows an example of a material defined for theverification problem discussed in Section 4.5.1.

!------------------------------------------Porous medium

k isotropic500.0

specific storage0.0

porosity1.0

longitudinal dispersivity10.0

transverse dispersivity0.1

transverse vertical dispersivity0.1

tortuosity0.1

end material

Figure 2.9: Example of a porous media domain property file prefix.mprops.

To make use of the material properties file, you would issue the following instruction:

Read properties1. mat name Name of the material.

Chosen zones are assigned properties of the material named mat name in the currentmaterial properties file as defined in a Properties file instruction.

• • •

So for example, the following set of instructions could be inserted in the prefix.grok file:



properties filemy.mprops

clear chosen zones

choose zones all

read propertiessand

The instruction Read properties would, in this case, search the porous media materialproperties file my.mprops for a material named sand. If found, it would read the instructionsdefining the material and modify the porous media properties for the current set of chosenzones.

A summary of the final data which has been defined for each zone is listed in the prefixo.ecofile, and an example is shown in Figure 2.10.

----------------------------------------------------------POROUS MEDIA PROPERTIES

ZONE: 1MATERIAL: porous mediumConsists of 100 elements out of 100Kxx: 500.000Kyy: 500.000Kzz: 500.000Specific storage: 0.00000Porosity: 1.00000

Longitudinal dispersivity 10.0000Transverse dispersivity 0.100000Transverse vertical dispersivity 0.100000Tortuosity 0.100000Bulk density 2650.00Immobile zone porosity 0.00000Mass transfer coefficient 0.00000

100 elements of 100 have been assigned properties

Figure 2.10: Example output for a porous media material.


In this example, because flow is saturated, no variably-saturated porous media flow propertiesneed to be defined in the material properties file. Also, default values for properties (e.g.bulk density, immobile zone porosity etc.) which have not been modified in the prefix.grokor material properties file are used.

2.8.2 Saturated Subsurface Flow

2.8.2.1 Porous Medium

HydroGeoSphere is designed to perform the flow simulation in saturated mode unlessinstructed otherwise, and unless you modify the default values, all zones (and elements) inthe domain will be assigned the default porous media properties which are listed in Table 2.5.These values are representative of a sand.

Note that the default state of the hydraulic conductivity tensor (K in Equation 2.2) is thatit is isotropic and that all off-diagonal terms are zero.

You can use the general methods and instructions outlined in Section 2.8.1 to modify thedefault distribution of saturated porous media properties. A general porous medium layoutis shown as the following instruction:


properties fileprops_file_name.mprops

clear chosen nodes/elements/segments/faces/faces by nodes/zoneschoose nodes/elements/segments/faces/faces by nodes/zoneschoose_description

new zonezone_type

clear chosen zoneschoose zone number

num_zone ! same as zone_type

read propertiesmat_name

Note that each instruction given here has an associated scope of operation. For example,some can only be used in the prefix.grok file, in which case they will affect the currentset of chosen zones or elements. Other instructions can only be used in a porous mediaproperties (.mprops) file, in which case they affect only the named material of which they


Table 2.5: Default values for porous media saturated flowproperties.

Parameter Value UnitName Default SandHydraulic conductivity terms:

Kxx 7.438×10−5 m s−1

Kyy 7.438×10−5 m s−1

Kzz 7.438×10−5 m s−1

Kxy 0.0 m s−1

Kxz 0.0 m s−1

Kyz 0.0 m s−1

Specific storage Ss 1.0×10−4 m−1

Porosity θs 0.375Poisson’s ratio ν∗ 0.3Solids compressibility γs 0.0 kg−1 m s2

Loading efficiency ζ 1.0Unsaturated flow relation type Pseudo-soil

are a part. Finally, some instructions can be used in both types of files, in which case theirbehaviour will be as described above, and will depend on which type of file (i.e. prefix.grokor .mprops) that they are placed in. It is very important that the user understand thisbehaviour, and the scope of each instruction will be clearly indicated as they are introducedand discussed below.

K isotropicScope: .grok .mprops

1. K val Hydraulic conductivity [L T−1].

Assign an isotropic hydraulic conductivity (i.e., Kxx = Kyy = Kzz).• • •

K anisotropicScope: .grok .mprops

1. K xx, K yy, K zz Hydraulic conductivities [L T−1] in the x-, y-, and z-directions,respectively.

Assigns anisotropic hydraulic conductivities.• • •


K anisotropic by ratioScope: .grok .mprops

1. kval, kratio Hydraulic conductivity [L T−1] in the x- and y-directions and a ratio tocompute the hydraulic conductivity in the z-direction.

Assigns anisotropic hydraulic conductivities such that Kxx = Kyy = kval and Kzz =kratio · kval.

• • •

K tensorScope: .grok .mprops

1. K xx, K yy, K zz Main-diagonal terms of the hydraulic conductivity tensorKxx,Kyy,and Kzz [L T−1].

2. K xy, K xz, K yz Off-diagonal terms of the hydraulic conductivity tensor Kxy,Kxz,and Kyz [L T−1].

Assign hydraulic conductivities which include the off-diagonal terms. Note that this optionwill only work if HydroGeoSphere is running in finite element mode and so this switchwill automatically be set.

• • •

Specific storageScope: .grok .mprops

1. val Specific storage [L−1], Ss in Equation 2.10.

• • •

PorosityScope: .grok .mprops

1. val Porosity [L3 L−3], θs in Equation 2.1.

• • •

Poisson ratioScope: .grok .mprops

1. val Poisson’s Ratio [-], ν∗ in Equation 2.28b.


• • •

Loading efficiencyScope: .grok .mprops

1. val Loading efficiency [-], ζ∗ in Equation 2.28b.

• • •

Compute loading efficiencyScope: .grok .mpropsThis command should be included in the input file if you want the pre-processor to computethe loading efficiency [-] based on Equation 2.28b. In this case, values of Poisson’s ratioand compressibility of solids and water for the current media will be used. Porous mediacompressibility will be computed from the specific storage value. If this command is notincluded, the default or user-defined loading efficiency value is used instead.

• • •

Solids compressibilityScope: .grok .mprops

1. val Solids compressibility [L T2 M−1], Ks in Equation 2.22.

• • •

Element K isotropicScope: .grok


Chosen elements are assigned isotropic hydraulic conductivities (i.e., Kxx = Kyy = Kzz).• • •

Element K anisotropicScope: .grok

1. K x, K y, K z Hydraulic conductivities [L T−1] in the x-, y-, and z-directions,respectively.


Chosen elements are assigned anisotropic hydraulic conductivities.• • •

Read elemental K from fileScope: .grok

1. input k file name Name of the file which contains the variable K data supplied bythe user.

This file should contain one of the following input data formats:

1. element number, K xx Element number, isotropic hydraulic conductivity [L T−1].

2. element number, K xx, K yy, K zz Element number, hydraulic conductivities[L T−1] in the x-, y-, and z-directions, respectively.

3. element number, K xx, K yy, K zz, K xy, K yz, K zx Element number, hy-draulic conductivity matrix components [L T−1].

All elements are assigned a variable K from the file. For example, if there are four elements,with Kxx = Kyy = 5 m d−1 and Kzz = 2 m d−1, the file would contain:

1 5.0 5.0 2.02 5.0 5.0 2.03 5.0 5.0 2.04 5.0 5.0 2.0

The user can supply variable values for any number of elements in file input k file name.grok will then produce data for all elements honouring any previous zoned values and theuser specified element-variable values, which are written to the file prefixo.elemental k.

• • •

Map isotropic K from rasterScope: .grok

1. rasterfile Name of the raster file containing the hydraulic conductivity [L T−1] values.This is a string variable. The file should be formatted as outlined in Section F.

For each element in the set of currently chosen zones, a value for the isotropic hydraulicconductivity (i.e. Kxx = Kyy = Kzz) will be interpolated from the raster file data.

• • •


Map anisotropic K from rasterScope: .grok

1. rasterfile x Name of the raster file containing the x-component (i.e. Kxx) hydraulicconductivities [L T−1]. This is a string variable. The file should be formatted asoutlined in Section F.

2. rasterfile y As above but for the y-component (i.e. Kyy) hydraulic conductivities[L T−1].

3. rasterfile z As above but for the z-component (i.e. Kzz) hydraulic conductivities[L T−1].

For each element in the set of currently chosen zones, values for the anisotropic hydraulicconductivity (i.e. Kxx,Kyy, and Kzz) will be interpolated from the raster file data.

• • •

Map porosity from rasterScope: .grok

1. rasterfile Name of the raster file containing the porosity [-] values. This is a stringvariable. The file should be formatted as outlined in Section F.

For each element in the set of currently chosen zones a value for the porosity will beinterpolated from the raster file data.

• • •

Read elemental porosity from fileScope: .grok

1. input por file name Name of the file which contains the variable porosity [-] datasupplied by the user.

The input file should contain the following data:

1. element number, por Element number, porosity [-].

Data is read from the file until end-of-file is reached. The user can supply variable porosityvalues for any number of elements in file input por file name. grok will then producedata for all elements honouring any previous zoned values and the user specified element-variable values, which are written to the file prefixo.elemental por.

• • •


Read elemental specific storage from fileScope: .grok

1. input stor file name Name of the file which contains the variable specific storagedata supplied by the user.


1. element number, stor Element number, specific storage [L−1], Ss in Equation 2.10.

Data is read from the file until end-of-file is reached. The user can supply variable specificstorage values for any number of elements in file input stor file name. grok will thenproduce data for all elements honouring any previous zoned values and the user specifiedelement-variable values, which are written to the file prefixo.elemental stor.

• • •

Map tortuosity from rasterScope: .grok

1. rasterfile Name of the raster file containing the tortuosity [-] values. The file shouldbe formatted as outlined in Section F.

For each element in the set of currently chosen zones, a value for the tortuosity will beinterpolated from the raster file data.

• • •

Read elemental tortuosity from fileScope: .grok

1. input tort file name Name of the file which contains the variable tortuosity datasupplied by the user.


1. element number, tort Element number, tortuosity [-].

Data is read from the file until end-of-file is reached. The user can supply variable valuesof tortuosity for any number of elements in file input por file name. grok will thenproduce data for all elements honouring any previous zoned values and the user specifiedelement-variable values, which are written to the file prefixo.elemental tort.

• • •


Write element KScope: .grok

1. file name Name of the file in which to write the hydraulic conductivity [L T−1]information.

Writes a file of element hydraulic conductivity values in ASCII format. The followingFortran code segment shows how the file is opened and the data is written:

open(itmp, file=filename, status=’unknown’)if (k_variable .or. k_rand) then

write(itmp, ’(i10,3e12.5)’) (i, kxx(i), kyy(i), kzz(i), i=1,ne)else

write(itmp, ’(i10,3e12.5)’) (i, kxx(iprop(i)), kyy(iprop(i)), &kzz(iprop(i)), i=1,ne)

endif

Here kxx, kyy, and kzz are the hydraulic conductivity values in the three principal directionsand ne is the number of elements in the mesh. If K values are zoned, then the variableiprop(i) refers to the element zone id number of element i.

• • •

Write element K at zScope: .grok

1. zfix z-coordinate for choosing which element to write.

2. rtol Distance from zfix for test.

3. filenm Name of the file in which to write the hydraulic conductivity information.

This command is identical to the command write element K except that information if onlywritten for elements whose centroid is within a distance of rtol of the z-coordinate zfix arewritten to the file.

• • •

Get average KScope: .grokFor the group of currently chosen elements, this instruction computes the average hydraulicconductivity and writes it to the .lst file. This is useful for example, when a randomconductivity field has been generated and the user would like to know the average hydraulicconductivity of a region of the domain.


• • •

AECL propertiesScope: .grok

1. aecl nd file Name of the file which contains the nodal coordinates for the AECLMotif mesh.

2. aecl ne file Name of the file which contains the element incidences and materialproperty numbers for the AECL Motif mesh.

AECL Motif grid element material numbers are mapped onto the existing HydroGeo-Sphere mesh. The mapping is performed based on the proximity of HydroGeoSphereand AECL Motif element centroids. Once the material numbers have been mapped, zonesshould be chosen and appropriate material properties should be assigned.

• • •

Random K field from FGENScope: .grok

1. fgenfile Name of file which contains the random hydraulic conductivity informationgenerated by FGEN.

2. x offset, y offset, z offset New origin of the FGEN coordinate system (xoff, yoff, zoff).

3. anisotropy y, anisotropy z The dimensionless ratios Kyy/Kxx and Kzz/Kxx.

4. xy rotation Angle to rotate the FGEN coordinate system.

A random K field which was generated by the program FGEN [Robin et al., 1993] ismapped onto the current mesh. HydroGeoSphere Automatically dimensions and treatsthe hydraulic conductivity vector as an elemental property, as opposed to a zoned property.Note that HydroGeoSphere assumes that values are ln(K) and takes the exponential toconvert the value to assign.

FGEN generates two cross-correlated random fields having user-specified geostatisticalproperties. The user can also control the type and degree of cross-correlation. The usershould contact the authors regarding the availability of FGEN.

The output from FGEN is in the form of values distributed on a rectangular grid which canbe either 2-D or 3-D. Normally, a 3-D distribution is used and values are mapped by firstdetermining which rectangular grid block the element centroid falls in, and then generatinga value at the centroid by trilinear interpolation of the eight neighbouring grid values. If anelement is located outside of the FGEN grid, it is assigned a missing value, which is readfrom the FGEN file.


If the FGEN data is 2-D, values are generated using bilinear interpolation. For example,suppose the FGEN values are distributed on a plane parallel to the xy-plane. In this caseany element whose centroid had xy-coordinates that fell inside the range of the FGEN datawould receive a value determined by bilinear interpolation from the four neighbouring gridvalues, but independent of the z-coordinate of the element centroid.

The resulting element-variable hydraulic conductivity data are written to the fileprefixo.elemental k.

• • •

Random KD field from FGENScope: .grok

1. fgenfile Name of file which contains the random distribution coefficient informationgenerated by FGEN.

2. x offset, y offset, z offset New origin of the FGEN coordinate system (xoff, yoff, zoff).

3. anisotropy y, anisotropy z These values are ignored by this command but areinput for consistency with the command Random K field from FGEN.

4. xy rotation Angle to rotate the FGEN coordinate system.

This command works in the same way as the command Random K field from FGEN.• • •

Soil Frost KScope: .grok

1. npanel Number of panels.

2. ton val(i), toff val(i), K val(i), i=1,npanel Time on [T], time off [T], and soilfrost hydraulic conductivity [L T−1] for each panel.

Modifies K values for chosen elements.• • •

Soil Frost K by ratioScope: .grok


2. ton val(i), toff val(i), K ratio(i), i=1,npanel Time on [T], time off [T], and theratio between soil frost hydraulic conductivity and the original soil conductivity [-] foreach panel.


Applies the ratio for chosen elements.• • •

Time dependent K for chosen elementsScope: .grok


2. ton val(i), K x(i), K y(i), K z(i), i=1,npanel Time on [T] and hydraulic con-ductivities [L T−1] in the x-, y-, and z-directions, respectively, for each panel.

• • •

Time dependent variable K for chosen elementsScope: .grok


2. ton val(i), k file name(i), i=1,npanel Time on [T] and the filename where hy-draulic conductivity values are listed for each panel. Each line of an input file specifiesthe hydraulic conductivities [L T−1] in the x-, y-, and z-directions (i.e., Kxx Kyy Kzz)for each chosen element.

• • •

K reduction by impedance factor for chosen elementsScope: .grok

1. imp fac The impedance factor [-].

2. npanel Number of time panels in the time on/off table.

3. ton val(i) toff val(i), i=1,npanel Time on [T] and time off [T] for each panel. Thetime values should satisfy the following set of inequalities:

ton(1) < toff(1) < ton(2) < toff(2) < · · · < ton(n) < toff(n),

where n is the number of panels.

This command modifies the hydraulic conductivity for chosen elements such that

Knew = K · 10−Ω·Sw(t=ton) for ton < t ≤ toff,

where Ω is the impedance factor. The impedance factor represents the maximum K-reduction in log-scale during the freezing season. The following example shows how to callthis command:


k reduction by impedance factor for chosen elements1.480.0 7689600.028339200.0 37584000.059184000.0 70675200.090547200.0 100396800.0120960000.0 134697600.0152841600.0 166838400.0184723200.0 195004800.0217123200.0 220665600.0

• • •

Time varying K by impedance factor via temperature rasterScope: .grok

1. impedance The impedance factor (> 0) [-].

2. freezing temperature The freezing temperature [°C].

3. time(i), filename(i)...end The time [T] and raster filename list.

This command, which applies to the porous media domain, uses the table of temperatureraster files to modify hydraulic conductivities [L T−1] in the x-, y-, and z-directions fora set of chosen (near-surface) elements when the temperature drops below the freezingtemperature. In particular, over the ith time window for each chosen element

Knew =K · 10−Ω·Sw(t=ti), T (t) < Tf

K, otherwise∀t ∈ (ti, ti+1],

where Ω is the impedance factor, Tf is the freezing temperature, and T (t) is the interpolatedtemperature over the time window at time t. The impedance factor represents the maximumK-reduction in log-scale during the freezing season. For example:

time varying k by impedance factor via temperature raster7 ! impedance factor0 ! freezing temperature! times raster files0 temperature1.asc2592000 temperature2.asc5184000 temperature3.asc7776000 temperature4.asc10368000 temperature5.asc12960000 temperature6.asc

end


Note that this command cannot be used in conjunction with the commands Time dependentK for chosen elements, Time dependent variable K for chosen elements, or K reduction byimpedance factor for chosen elements.

• • •

Permafrost formation from file1. filename Filename of the ASCII file containing permafrost formation locations and

times.

The input file consists of blocks of the form:

Elevation, Number of times (n)t1, true/falset2, true/false: :: :tn, true/false

Each block defines a time on/off table for a given elevation.• • •

Interpolate permafrostCauses interpolation of permafrost quantities over the time on/off tables defined by thecommand Permafrost formation from file.

• • •

Permafrost k1. K xx, K yy, K zz Permafrost hydraulic conductivities [L T−1] in the x-, y-, andz-directions, respectively.

Assigns anisotropic hydraulic conductivities of permafrost. The assigned values change withrespect to the times defined by the command Permafrost formation from file.

• • •

Permafrost porosity1. porosity Permafrost porosity [-].


This command allows the porosity to change as a result of permafrost status. It is notedthat the Permafrost porosity command used in transport simulations should be placed aftertransport command, i.e., after the Solute command block that defines solute properties.Otherwise, grok will terminate with an error message.

• • •

Permafrost effective diffusion coefficient1. diff coeff Permafrost effective diffusion coefficient [L2 T−1].

This command allows the effective diffusion coefficient to change as a result of permafroststatus. It is noted that the Permafrost effective diffusion coefficient command used in transportsimulations should be placed after transport command i.e., after the Solute command blockthat defines solute properties. Otherwise, grok will terminate with an error message.

• • •

2.8.2.2 Discrete Fractures

Unless you modify the default values, all discrete fracture zones (and 2-D fracture elements)in the domain will be assigned the default saturated properties which are listed in Table 2.6.These values are representative of a 100 micron fracture.

Table 2.6: Default values for fractured media saturated flow properties.

Parameter Value UnitName Default 100 micron fractureAperture wf 1.0× 10−4 mConductivity (computed) Kf (ρg w2

f )/(12µ) m s−1

Specific storage (computed) Ssf ρgαw m−1

Unsaturated flow relation type Pseudo-fracture

You can use the general methods and instructions outlined in Section 2.8.1 to modify thedefault distribution of saturated fractured media properties.

As was the case for the instructions which modify porous medium properties, these instruc-tions also have a scope of operation, the only difference being that they would appear in the.fprops file instead of the .mprops file.

ApertureScope: .grok .fprops

1. val Fracture aperture [L], wf in Equation 2.11.


• • •

High-K planeScope: .fprops

1. valx Thickness [L] for the high-conductivity plane.

2. valx Hydraulic conductivity [L T−1] for the high-conductivity plane.

Treat the fracture material as a high-conductivity plane where the hydraulic conductivityand thickness are given by the user.

• • •

Fracture zone porosityScope: .fprops

1. valx Porosity for the high-conductivity plane.

In the case that fracture aperture is given, the porosity is assumed to be unity and thiscommand has no effect.

• • •

Specific storageScope: .grok .fprops

1. val Specific storage [L−1], Ssf in Equation 2.14.

• • •

Coupling lengthScope: .grok .fprops

1. val Coupling length [L].

• • •

Coupling hydraulic conductivityScope: .grok .fprops

1. val Coupling hydraulic conductivity [L T−1].


• • •

Impermeable matrixScope: .grokThis command causes the matrix to be considered impermeable and so flow and transportwill only be computed for the fractures. This overrides any values defined in the prefix.grokor .fprops file so you do not have to alter them.

• • •

Generate individual fracture and read parameters from fileScope: .grok

1. filename Name of file that contains the fracture information.

This command assigns individual fracture information to a fracture domain mapped ontoeither a triangular prism or hexahedral block element mesh. The format of the input file isas follows:

1. nelems Number of fracture elements.

2. id(i), nd1(i), nd2(i), nd3(i), thk(i), cond(i), por(i), stor(i), i=1,nelems Ele-ment id, node ids (triangle), thickness [L], hydraulic conductivity [L T−1], porosity [-],and specific storage [L−1] of a mapped fracture element.

Note that fracture element ids must be listed in increasing order from one to the number offracture elements.

• • •

Make fractures from fgenScope:.grok

1. mat name Name of the fracture material whose properties are to be read and assigned.

2. fname Name of the FGEN file which contains the random aperture information.

Chosen faces are assigned to a new fracture zone and given the properties of materialmat name, which is read from the .fprops file fname. Any aperture information containedtherein will be overwritten by the information that is then read from the FGEN file. TheFGEN file aperture values are distributed on a rectangular grid with uniform spacings inthe three principal axis directions. Element aperture values are then interpolated to the


element face centroids by bilinear (if the FGEN data is on a 2-D plane) or trilinear (if theFGEN data is fully 3-D) interpolation.

grok assumes that the FGEN file contains log aperture values and so the following conversionis done:

wf = exp(wfFGEN )

where wfFGEN is the fracture aperture value read from the FGEN file.• • •

Map fractures from tecplot fileScope: .grok

1. tecplot frac file Name of the Tecplot file which contains the fracture triangle infor-mation.

2. label Name of the fracture material whose properties are to be read and assigned.

A new fracture zone is created based on triangle data given in the Tecplot file tec-plot frac file. Fracture zone properties are assigned from the material label.

The Tecplot file must contain one or more Tecplot ZONE statements. Each Tecplot ZONEstatement must contain, or be followed by a statement containing the string N= followed bythe number of vertices and then by the string E= followed by the number of triangles in theTecplot ZONE.

Comments beginning with the character # are allowed.

The Tecplot variables represent the xyz-coordinates of the vertices and must be given inthree-column, point format.

The fracture elements are defined so that they conform closely to the triangulated surfacegiven in the Tecplot file, and can include diagonal (i.e. inclined) faces.

• • •

The following Tecplot file produced the fracture elements shown in Figure 2.11.

VARIABLES="X", "Y", "Z"ZONE T="Fractures_primary"N=5, E=3, DATAPACKING=POINT, ZONETYPE=FETRIANGLE110. -1. -5.51. 102. -3.-3. 49. 99.0. 100. 1000. 0. 0.1 3 5


1 2 32 3 4

Figure 2.11: Example of fracture generation showing 3-D porous medium domain(grey cube), Tecplot triangles (yellow triangles), and the resulting fracture elements(blue triangles).

Map fractures from mofrac vtk fileScope: .grok

1. vtk filename Filename of the MoFrac VTK input file.

2. mapped filename Filename of the mapped fracture output file.

3. num fracs Maximum number of fractures in the MoFrac VTK input file.


4. tecplot output Logical value that if true causes the MoFrac VTK input file to beoutput to a Tecplot formatted file.

5. tecplot filename Filename of the Tecplot formatted output file.

This commands maps fractures that are triangulated and stored in the MoFrac VTK format.Fractures are mapped as triangles to match the input fracture geometry and the mapping isapplicable to both 3-D hexahedral and prism element mesh types. As part of the mapping,the mapped face IDs that correspond to the faces of hexahedral or prism elements are writtento the file Face id input.dat. An example of using this command after a fracture domainhas been defined is as follows.


properties../prop/fracture.fprops

map fractures from mofrac vtk filefracture.vtkfracture_mapped.txt10truefracture_tecplot.dat

• • •

Make recharge spreading layerScope: .grok

1. frack Hydraulic conductivity [L T−1] of the recharge spreading layer.

2. aperture Thickness [L] of the recharge spreading layer.

3. remove fixed head conn A logical switch which determines whether the rechargespreading layer is connected to an existing specified head boundary.

Chosen faces which are on the top of the domain are assigned to a new fracture zone whichhas the properties of a recharge spreading layer. A recharge spreading layer is a zone ofrelatively high hydraulic conductivity which allows recharge water to infiltrate preferentiallyinto zones with high hydraulic conductivity (e.g. fractures).

A recharge spreading layer may allow water to bypass the rest of the system if it is connectedto or in close proximity to a constant head boundary which can act as a discharge point


for the system. In such cases you can set the variable remove fixed head conn to betrue, to prevent such direct connections. If your intent is to distribute water preferentiallybetween fractures and low K matrix, experience has shown that recharge spreading layertransmissivities two orders of magnitude higher than the matrix are usually sufficient.

• • •

2.8.2.3 Dual Continuum

Unless you modify the default values, all dual-continuum zones (and elements) in the domainwill be assigned the default properties which are listed in Table 2.7. These values arerepresentative of a sand.

Table 2.7: Default values for dual-continuum saturated flow prop-erties.

Parameter Value UnitName Default SandHydraulic conductivity terms:

Kxx 7.438×10−5 m s−1

Kyy 7.438×10−5 m s−1

Kzz 7.438×10−5 m s−1

Specific storage Ssd 1.0×10−4 m−1

Porosity θsd 0.375Volume fraction of porous medium wd 0.01Unsaturated flow relation type Pseudo-soil

Note that the default state of the hydraulic conductivity tensor (Kd in Equation 2.17) isthat it is isotropic. It should also be noted that for dual continua, off-diagonal terms arenot considered.

You can use the general methods and instructions outlined in Section 2.8.1 to modify thedefault distribution of saturated dual-continuum properties.

As was the case for the instructions which modify porous medium properties, these instruc-tions also have a scope of operation, the only difference being that they would appear in the.dprops file instead of the .mprops file.

K isotropicScope: .grok .dprops


Assign an isotropic hydraulic conductivity (i.e. Kxxd = Kyyd = Kzzd).


• • •

K anisotropicScope: .grok .dprops

1. K xxd, K yyd, K zzd Hydraulic conductivities [L T−1] in the x-, y-, and z-directions,respectively.

Assigns anisotropic hydraulic conductivities.• • •

K anisotropic by ratioScope: .grok .dprops

1. kval, kratio Hydraulic conductivity [L T−1] in the x- and y-directions and a ratio tocompute the hydraulic conductivity in the z-direction.

Assigns anisotropic hydraulic conductivities such that Kxxd = Kyyd = kval and Kzzd =kratio · kval.

• • •

Specific storageScope: .grok .dprops

1. val Specific storage [L−1], Ssd, but defined in a similar way to Ss in Equation 2.10.

• • •

PorosityScope: .grok .dprops

1. val Porosity [L3 L−3], θsd in Equation 2.16.

• • •

Volume fraction dual mediumScope: .dprops

1. val Volume fraction [L3 L−3], wd in Equation 2.16.


The volume fractions of the dual medium and porous medium always add up to 1.0.• • •

First-order fluid exchange coefficientScope: .dprops

1. val First-order fluid exchange rate, αwd in Equation 2.69.

• • •

Interface kScope: .dprops

1. val Interface hydraulic conductivity [L T−1], Ka in Equation 2.69.

• • •

Convert pm k to macropore kScope: .dprops

1. val Porous medium background hydraulic conductivity Kbkgrd [L T−1].

We can express the bulk hydraulic conductivity of a dual-continuum Kbulk as the sum ofthe porous media Kbkgrd and fracture Kd components:

Kbulk = Kbkgrd (1− wd) +Kdwd (2.7)

where wd is the volume fraction [L3 L−3] in Equation 2.16.

If we assume that the observed (porous medium) hydraulic conductivity is equal to Kbulk,and supply an educated guess for Kbkgrd, we can rearrange the equation and calculate Kd

as :

Kd = [Kbulk −Kbkgrd (1− wd)]/wd (2.8)

For all elements in the currently chosen dual zones, the porous medium hydraulic conduc-tivity is replaced by Kbkgrd and the fracture hydraulic conductivity Kd is set equal to thecalculated value.

• • •


2.8.2.4 Wells

Well domains, can be set up using the following instructions, as outlined in Section 2.3.2.2and in Equation 2.55. The variable radius corresponds to rs, while the pumping rates Qw,use the new boundary condition format as described in Section 2.7. Unless the user modifiesthe default values, all well zones in the domain will be assigned the default properties.The default values, Table 2.8, can be and are recommend to be modified to fit the modelapplication.

Table 2.8: Default values for well properties.

Parameter Value UnitScreen Radius 1.0×10−5 mCoupled Conductivity 7.438×10−5 m s−1

Coupled Length 1.0×10−4 mWell Type Hagen–PoiseuilleManning’s Friction Coefficient 0.0548 m−1/3 sHazen–Williams Coefficient 130.0 m0.37 s−1

For example, the following set of instructions, with prefix.wprops file Figure 2.12, could beinserted into the prefix.grok file to produce a pumping well:

use domain typewell

properties fileprefix.wprops

clear chosen segmentschoose segments polyline !Screen interval2100. 100. 0.100. 100. 20.

new zone1

clear chosen zoneschoose zone number1

read propertieswell one

clear chosen nodes


choose node !Bottom of pump intake100. 100. 0.

create node setwell


namewell

node setwell

time value table0.0 -80.0e-3 !Pumping duration and rateend

end

The well domain example opens the property file prefix.wprops, shown in Figure 2.12, andcreates a 20 m long screen located at x = 100 m and y = 100 m with a pump intake locatedat z = 0 m. The well one properties are read into grok and a steady pumping rate is set at−80× 10−3 m3 s−1. If the flowrate is set to zero, the well is passive but can still transmitwater vertically through its screen.

!------------------------------------------well one

radius0.05d0

coupling length1.0e-4

coupling conductivity.0023

end

Figure 2.12: Example of a well domain property file prefix.wprops.


RadiusScope: .grok .wprops

1. WellScreenRadius Well Screen Radius [L].

The radius of the screen interval of the well.• • •

InfilledScope: .grok .wprops

1. WellPropsInfilled Infilled well properties name from .mprops file.

This command should be included in the input file for an infilled well. The default valuesare a sand as described in Table 2.7.

• • •

Hagen PoiseuilleScope: .grok .wpropsThis command should be included in the input for the Hagen–Poiseuille flow option.

• • •

Hazen WilliamsScope: .grok .wpropsThis command should be included in the input file for the Hazen–Williams flow option.

• • •

ManningScope: .grok .wpropsThis command should be included in the input file for the Manning flow option.

• • •

FrictionScope: .grok .wprops

1. well friction Manning’s friction [L−1/3 T] for wells.• • •


Hazen Williams coefficientScope: .grok .wprops

1. well hw coeffient Hazen–Williams coefficient [L0.37 T−1] for wells.

• • •

Saturated wellsScope: .grok .wpropsThis instruction causes wells to remain fully saturated.

• • •

Dual nodes for wellsScope: .grok .wpropsThis instruction causes well flow scheme to use dual node approach.

• • •

Coupling conductivityScope: .grok .wprops

1. WellPropsCplCond Coupling conductivity [L T−1] for wells.

Coupling conductivity parameter only required for the dual node approach for wells.• • •

Coupling lengthScope: .grok .wprops

1. WellPropsCplLngth Coupling length [L] for wells.

Coupling length parameter only required for the dual node approach for wells.• • •

2.8.2.5 Tile Drains

Tile drains, as outlined in Section 2.3.2.3, can be set up using the following instructions.Currently, this option requires that the system be variably-saturated. The default tile drainvalues, Table 2.9, can be and are recommend to be modified to fit the model application.


Table 2.9: Default values for tile drain properties.

Parameter Value UnitScreen Radius 1.0× 10−5 mCoupled Conductivity 7.438×10−5 m s−1

Coupled Length 1.0× 10−4 mCoupled Scheme SharedTile Drain Type Hagen–PoiseuilleManning’s Friction Coefficient 0.0548 m−1/3 sHazen–Williams Coefficient 130.0 m0.37 s−1

For example, the following set of instructions, with prefix.tprops file Figure 2.13, could beinserted into the prefix.grok file to produce a horizontal tile drain:

use domain typetile

properties fileprefix.tprops

clear chosen segmentschoose segments polyline ! Screen interval215. 1. 2.15. 29. 2.

new zone1


read propertiestile one

clear chosen nodeschoose node ! Tile drain intake15. 15. 2.

create node settile

boundary condition


typeflux nodal

nametile one

node settile

time value table0.0 -2 ! Pumping duration and rateend

end

The tile domain example opens the property file prefix.tprops, shown in Figure 2.13, andcreates a 28 m long screen between (15, 1, 2) and (15, 29, 2) with a pump intake located at(15, 15, 2). The tile one properties are read into grok and a steady pumping rate is set at−2 m3 s−1.

!------------------------------------------tile one

radius0.0108

! Coupling length and conductivity for dual node approachcoupling length1.0e-4

coupling conductivity0.0023

! Infilled tiled drain with properties from the mprops fileinfilledporous medium

end

Figure 2.13: Example of a tile drain domain property file prefix.tprops.

RadiusScope: .grok .wprops

1. TileScreenRadius Tile drain screen radius [L].


The radius of the screen interval of the tile drain.• • •

InfilledScope: .grok .wpropsThis command should be included in the input file for an infilled tile drain.

• • •

Hagen PoiseuilleScope: .grok .wpropsThis command should be included in the input for the Hagen–Poiseuille flow option.

• • •

Hazen WilliamsScope: .grok .wpropsThis command should be included in the input file for the Hazen–Williams flow option.

• • •

ManningScope: .grok .wpropsThis command should be included in the input file for the Manning flow option.

• • •

FrictionScope: .grok .wprops

1. tile friction Manning’s friction [L−1/3 T] for tile drains.

• • •

Hazen Williams coefficientScope: .grok .wprops

1. tile hw coeffient Hazen–Williams coefficient [L0.37 T−1] for tile drains.

• • •


Dual nodes for tilesScope: .grok .wpropsThis instruction causes the tile drain flow scheme to use the dual node approach.

• • •

Coupling conductivityScope: .grok .wprops

1. TilePropsCplCond Coupling conductivity [L T−1] for tile drains.

Coupling conductivity parameter only required for the dual node approach for tile drains.

• • •

Coupling lengthScope: .grok .wprops

1. TilePropsCplLngth Coupling length [L] for tile drains.

Coupling length parameter only required for the dual node approach for tile drains.• • •

2.8.2.6 Channel Flow

Channel domains, can be set up using the following instructions, as outlined in Section 2.3.2.4and in Equation 2.65. Unless the user modifies the default values, all channel zones in thedomain will be assigned the default properties. The default values, Table 2.10, can be andare recommend to be modified to fit the model application.

Table 2.10: Default values for channel properties.

Parameter Value UnitShape RectangleWidth 1.0 mManning’s Friction Coefficient 0.0548 m−1/3 sRiver Bank Height 1.0 mStreambed Thickness 0.001 mSteambed Conductivity 0.0001 m

For example, the following set of instructions, with prefix.cprops file Figure 2.14, could beinserted into the prefix.grok file to produce a channel:


use domain typechannel

properties fileprefixl.cprops

clear chosen segmentschoose segments polyline20.0 10.0 20.0100.0 10.0 10.0

new zone1


read propertieschannel one

clear chosen nodeschoose nodes allinitial head surface elevation

clear chosen nodeschoose node0.0 10.0 20.0

create node setinlet_node


nameinlet_node_flux

node setinlet_node



endend

clear chosen nodeschoose node100.0 10.0 10.0

create node setoutlet_node

boundary conditiontypechannel critical depth

namecd_outlet_node

node setoutlet_node

end

clear chosen nodeschoose nodes top block0.0 99.59.0 11.0.0 20.create node setinternal_node


nameinternal_flux

node setinternal_node

time value table0.0 0.601818e-2end

end


The channel domain example opens the property file prefix.cprops, shown in Figure 2.14,and creates a 1 m wide channel . The channel one properties are read into grok.

!------------------------------------------channel one

type rectangle1.0

friction0.01

rill storage height0.001

obstruction storage height0.0

streambed thickness0.3

streambed conductivity1.0e-4

bank height1.0

end

Figure 2.14: Example of a channel domain property file prefix.cprops.

Dual nodes for channel flowScope: .grokThis instruction causes the channel flow scheme to use the dual node approach.

• • •

Type rectangleScope: .grok .cprops

1. ChanWidth Channel width [L].

The width of the rectangular channel.


• • •

Type trapezoidScope: .grok .cprops

1. ChanWidth Channel width [L].

2. ChanTrapBankAngle Channel bank angle [degree].

The width of the bottom of the trapezoidal channel and the angle of the bank from thevertical line.

• • •

Type circleScope: .grok .cprops

1. ChanRadius Channel radius [L].

The radius of the circular channel.• • •

Type generalScope: .grok .cprops

1. ntab Number of water depth values in the table.

2. ChanTabD(i), ChanTabAF(i), ChanTabWP(i), ChanTabTW(i), i=1,ntabTables for water depth [L], area of flow [L2], wetted perimeter [L], and top width [L].

A tabular form of data can be used to specify the area of flow, wetted perimeter, and topwidth for given water depth values.

• • •

FrictionScope: .grok .cprops

1. ChanFrictn Manning friction [L−1/3 T] for the channel.

Manning friction coefficient for the zone chosen.• • •


Rill storage heightScope: .grok .cprops

1. ChanRillStor Channel rill storage height [L].

A minimum water depth required for flow.• • •

Obstruction storage heightScope: .grok .cprops

1. ChanOnstructStor Channel obstruction storage height [L].

Obstruction storage height.• • •

Streambed thicknessScope: .grok .cprops

1. ChanStrmBedThick Thickness of streambed [L].

Streambed thickness that defines the coupling between channel and subsurface.• • •

Streambed conductivityScope: .grok .cprops

1. ChanStrmBedK Hydraulic conductivity [L T−1] of streambed.

Streambed hydraulic conductivity together with thickness to define the coupling conductancebetween channel and subsurface.

• • •

Bank heightScope: .grok .cprops

1. ChanBankHeight Height of river bank [L].

River bank height to define the interaction between the channel and overland flow domains.

• • •


2.8.2.7 Cutoff Walls

Cutoff walls can be used to represent internal impermeable boundaries which could occur,for example, in a funnel-and-gate system.

Cutoff Walls1. nwalls Number of impermeable cutoff walls to be defined.

2. Read the following for i=1,nwalls:

(a) iorient(i) Wall orientation number.(b) avalue(i), afrom(i), ato(i), verfrom(i), verto(i) Position [L], lateral mini-

mum extent [L], lateral maximum extent [L], vertical minimum extent [L], andvertical maximum extent [L].

For example, with three cutoff walls the command format is

3iorient1avalue1 afrom1 ato1 verfrom1 verto1iorient2avalue2 afrom2 ato2 verfrom2 verto2iorient3avalue3 afrom3 ato3 verfrom3 verto3

The orientation parameter iorient should be set to 1 if the cutoff wall is in the xz-plane. Inthis case avalue is the y-coordinate of the wall and afrom and ato are the x-coordinatesof the ends of the wall. If iorient is 2 the cutoff wall is in the yz-plane and avalue is thex-coordinate of the wall and afrom and ato are the y-coordinates of the ends of the wall.In either case verfrom and verto are the z-coordinates of the bottom and top of the wallrespectively.

Note that only vertical cutoff walls are allowed and cutoff walls are restricted to rectangularblock element grids.

• • •

2.8.2.8 Imported from FRACTRAN

Fractran propertiesThis instruction is to be used after a mesh has been loaded using the Read fractran 2dgrid described in Section 2.3.5.1. It uses the FRACTRAN prefix defined there to read theassociated properties.


• • •

2.8.3 Variably-Saturated Subsurface Flow

As discussed in Section 2.1, one of the requirements for simulating variably-saturated flow isthat we define the constitutive relationships that govern the relation between the pressurehead, saturation and relative permeability. These relationships must be defined for theporous medium, discrete fractures and the dual continuum and, for each of these types ofmedia, the choice is to use either pseudo-soil, functional or tabular relationships. Wells area special case and are handled automatically by HydroGeoSphere.

Media specific instructions and default values for porous media, discrete fractures and dualcontinua are given in Sections 2.8.3.1, 2.8.3.2 and 2.8.3.3 respectively.

General instructions for modifying the default functional and tabular relationships are givenin Sections 2.8.3.4 and 2.8.3.5 respectively.


By default, all porous media zones (and elements) in the domain will use a constitutiverelationship based on the pseudo-soil relation, as developed by Huyakorn et al. [1994].Essentially, in the pseudo soil relationship, the medium is assigned a nodal saturation of 1above the water table and 0 (zero) below it. Relative permeability is applied to horizontalflow only and water travels vertically under saturated hydraulic conductivity conditions.

If you wish to use Van Genuchten or Brooks–Corey functions to describe the constitutiverelationship you can do so using the instructions given in Section 2.8.3.4. Unless you modifythem, the default values given in Table 2.11 will be used to define the functional relationships.

If you wish to use tables to describe the constitutive relationships you can do so usingthe instructions given in Section 2.8.3.5. Unless you modify them, the default values ofwater saturation versus pressure head and saturation versus relative permeability listed inTable 2.12 will be used to define the tabular relationships.

Relative permeability xyScope: .grok .mpropsWhen using functions or tables to define the constitutive relationships, this instruction causesgrok to apply the relative permeability to horizontal flow only so that water travels verticallyunder saturated hydraulic conductivity conditions, similar to the behaviour of the pseudo-soilrelation. This instruction should be applied to porous media, as discussed in Section 2.8.1.

• • •


Table 2.11: Default values for functions defining the porousmedia constitutive relationships, for the Van Genuchten andBrooks–Corey models.

Parameter Value UnitCommon

Residual water saturation, Swr 0.053Pore-connectivity, lp 0.5Beta (power index), β 3.1768

Van GenuchtenAlpha (power index), α 3.5237 m−1

Gamma (Power index, computed), γ 1− 1/βBrooks–Corey

Exponent (computed) 2/β + lp + 2Air entry pressure, ψae −0.16 mAlpha (power index, computed), α −1/ψae m−1

Table 2.12: Default pressure-saturation andsaturation-relative permeability tables forvariably-saturated porous media.

Pressure (m) ψ Saturation Sw

−10.0 0.0530.0 1.0

Saturation Sw Relative Permeability krw0.053 0.0531.0 1.0


By default, all discrete fracture zones (and elements) in the domain will use a constitutiverelationship based on the pseudo-soil relation, as developed by Huyakorn et al. [1994].Essentially, in the pseudo soil relation, the medium is assigned a nodal saturation of 1 abovethe water table and 0 (zero) below it. Also by default, the effective area available for flowacross the fracture-matrix interface is maintained at its maximum value, regardless of thestate of fracture saturation.

If you wish to use Van Genuchten or Brooks–Corey functions to describe the constitutiverelationships you can do so using the instructions given in Section 2.8.3.4. Unless youmodify them, the default values given in Table 2.13 will be used to define the functionalrelationships.

If you wish to use tables to describe the constitutive relationships you can do so using


Table 2.13: Default values for functions defining the discretefracture constitutive relationships, for the Van Genuchtenand Brooks–Corey models.

Parameter Value UnitResidual water saturation, Swr 0.053Power index (alpha), α 3.5237 m−1

Power index (beta), β 3.1768Power index (gamma, computed), γ 1− 1/βPore-connectivity, lp 0.5Brooks–Corey exponent 2/β + lp + 2

the instructions given in Section 2.8.3.5. Unless you modify them, the default values ofwater saturation versus pressure head and saturation versus relative permeability listed inTable 2.14 will be used to define the tabular relationships.

Table 2.14: Default pressure-saturation andsaturation-relative permeability tables forvariably-saturated discrete fractures.


−10.0 0.0530.0 1.0


If you wish to modify the default relationship between pressure, saturation and effectivearea you can do so using the instructions given below. For each instruction we will againindicate its scope (i.e. .grok, .fprops). Note that the functional relationships are alwaysapplied in a similar way to all fracture zones in the domain, while tabular relationships canvary from fracture zone to fracture zone if so desired.

The following instructions should be applied to discrete fractures, as discussed in Section 2.8.1.

Effective area tables...EndScope:.grok .fpropsCauses grok to use tables to describe the pressure-effective area relationship for the fractureand to begin reading a group of effective area table instructions until it encounters an Endinstruction.

By default values of contact area versus pressure head listed in Table 2.15 will be used.• • •


Table 2.15: Default pressure-effective area table forvariably-saturated discrete fractured media.

Pressure (m) ψ Effective Area (m2)0.0 1.0

These instructions are available for modifying the default pressure-effective area relationship:

Pressure-effective areaScope: .grok .fprops

1. pressure(i), effective area(i)...end Pressure [L] and effective area [L2].

Causes HydroGeoSphere to begin reading instructions which describe the pressure-contactarea table that defines the relationship for the fracture. Paired values of pressure ψ andeffective area, which varies between 0 (full reduction) and 1 (no reduction), should beentered from lowest pressure (i.e. most negative) to highest pressure, usually zero. Thelast line of the table must be an End instruction, and the number of entries in the list arecounted automatically to determine the table size.

• • •

Effective area Wang-Narasimhan functionsScope:.grokCauses HydroGeoSphere to use the approach of Wang and Narasimhan [1985], as dis-cussed in Section 4.1.4, for computing the pressure-effective area relationship for the fractures.These functions will automatically be applied to all fracture zones.

• • •


Dual continua zones (and elements) in the domain will use a constitutive relationship basedon the pseudo-soil relation, as developed by Huyakorn et al. [1994]. Essentially, in thepseudo soil relationship, the medium is assigned a nodal saturation of 1 above the watertable and 0 (zero) below it. Relative permeability is applied to horizontal flow only andwater travels vertically under saturated hydraulic conductivity conditions.

If you wish to use Van Genuchten or Brooks–Corey functions to describe the constitutiverelationships you can do so using the instructions given in Section 2.8.3.4. Unless youmodify them, the default values given in Table 2.16 will be used to define the functionalrelationships.


If you wish to use tables to describe the constitutive relationships you can do so usingthe instructions given in Section 2.8.3.5. Unless you modify them, the default values ofwater saturation versus pressure head and saturation versus relative permeability listed inTable 2.17 will be used to define the tabular relationships.

Relative permeability xyScope: .grok .dpropsWhen using functions or tables to define the constitutive relationships, this instructioncauses HydroGeoSphere to apply the relative permeability to horizontal flow only so thatwater travels vertically under saturated hydraulic conductivity conditions, similar to thebehaviour of the pseudo-soil relation. This instruction should be applied to dual continua,as discussed in Section 2.8.1.

• • •

Table 2.16: Default values for functions defining the dualcontinua constitutive relationships, for the Van Genuchtenand Brooks–Corey models.

Parameter Value UnitResidual water saturation, Swr 0.053Power index (alpha), α 3.5237 m−1

Power index (beta), β 3.1768Power index (gamma, computed), γ 1− 1/βPore-connectivity, lp 0.5Brooks–Corey exponent 2/β + lp + 2

Table 2.17: Default pressure-saturation andsaturation-relative permeability tables forvariably-saturated dual continua.


−10.0 0.0530.0 1.0


When simulating a system with porous and dual continua, the constitutive relationships ofthe interface between the two continua must also be defined. The following instructionsprovide this functionality:

Interface unsaturated tables


Interface unsaturated van genuchten functionsInterface unsaturated brooks-corey functionsInterface relative permeability xy

Input is identical to the generic forms of the commands discussed in the following sections,except that the scope is restricted to .dprops.

We will now discuss instructions of a general nature which can be used to modify the defaultconstitutive relationships for the various media, beginning with the functional relationships.

2.8.3.4 Functional Constitutive Relationships

The instructions described here can be used to modify the default variably-saturatedproperties for a porous medium, discrete fracture or dual continuum. Before issuing themit is necessary to choose which type of medium they should be applied to, as discussed inSection 2.8.1.

For each instruction we will again indicate its scope (i.e. .grok, .mprops, .dprops,.fprops). Recall that if an instruction is used in the prefix.grok file, it will affect thecurrent set of chosen zones, while in a properties (e.g. .mprops) file, it will only affect thenamed material of which it is a part.

Unsaturated brooks-corey functions...EndScope: .grok .mprops .fprops .dpropsCauses grok to use Brooks–Corey functions (Equation 2.5) to describe the constitutiverelationships for the medium and to begin reading a group of instructions that define thefunction until it encounters an End instruction.

• • •

Unsaturated van genuchten functions...EndScope: .grok .mprops .fprops .dpropsCauses grok to use Van Genuchten functions (Equation 2.7) to describe the constitutiverelationships for the medium and to begin reading a group of instructions that define thefunction until it encounters an End instruction.

• • •

The previous two instructions are used to choose between the Brooks–Corey of VanGenuchten approaches for defining the functions. In either case, if no further instruc-tions are issued, the default function parameter values given in Tables 2.11, 2.13 and 2.16will be used for porous media, discrete fractures and dual continua respectively.

In the case of porous and dual media, these instructions override the pseudo-soil default sothat relative permeability factors are applied to both horizontal and vertical flow.


The following instructions can be used to modify the parameters which define the constitutiverelationships:

Residual saturationScope: .grok .mprops .fprops .dprops

1. val Residual water saturation Swr [-].• • •

AlphaScope: .grok .mprops .fprops .dprops

1. val Power index alpha α [L−1].

For the Brooks–Corey function, this parameter is computed automatically from the air entrypressure. If you use this instruction you will be prompted to enter an air-entry pressureinstead and grok will stop.

• • •

BetaScope: .grok .mprops .fprops .dprops

1. val Power index beta β [-].

For the Van Genuchten function, this parameter must be greater than 1.0. If you enter avalue less than 1.0 you will be warned and grok will stop. This value is used to compute νaccording to Equation 2.9.

For the Brooks–Corey formulation, this value is used to recalculate the exponent in Equa-tion 2.6 unless the instruction Exponent has been used previously for this material.

• • •

Pore connectivityScope: .grok .mprops .fprops .dprops

1. val Pore connectivity lp [-]. The default value is 0.5.

Note that the default value of pore connectivity of 0.5 is a value recommended for the VanGenuchten formulation, so your will probably want to redefine it for the Brooks–Coreyformulation. The value recommended in this case is 2.0.

For the Brooks–Corey formulation, this value is used to recalculate the exponent in Equa-tion 2.6 unless the instruction Exponent has been used previously for this material.


• • •

Air entry pressureScope: .grok .mprops .fprops .dprops

1. val Air entry pressure [L]. Default value of −0.016 m (assuming Brooks–Corey).

For the Brooks–Corey function, this value is used to compute α [L−1] according to Equa-tion 2.5. For the Van Genuchten function, this parameter is not used. If you use thisinstruction you will be prompted to remove it and grok will stop.

• • •

ExponentScope: .grok .mprops .fprops .dprops

1. val Exponent [-] in Equation 2.6, which is used to compute kr in the Brooks–Coreyfunction. By default, the exponent is computed automatically from β and lp. Thisinstruction allows you to enter a different value.

For the Van Genuchten function, this parameter is not used. If you use this instruction youwill be prompted to remove it and grok will stop.

• • •

Minimum relative permeabilityScope: .grok .mprops .fprops .dprops

1. val Minimum relative permeability [-].

During a simulation, the model will choose the maximum value for relative permeabilitybetween the minimum value specified here and the value computed from the active function,either Van Genuchten or Brooks–Corey. This option may improve convergence of thenon-linear solution.

• • •

The following instructions can be used to generate pressure-saturation and saturation-relativepermeability tables using the Van Genuchten or Brooks–Corey parameters defined for themedium. In addition to the instructions given above which define the function, theseadditional instructions affect the properties of the tabular data.

Table smoothness factorScope: .grok .mprops


1. val Smoothness factor [-]. Smaller values cause more points to be generated for asmoother, more accurate table. The default value is 10−3.

• • •

Table minimum pressureScope: .grok .mprops

1. val Minimum pressure [L] value in the pressure-saturation table. The default value is−1000 m.

• • •

Table maximum s-k slopeScope: .grok .mprops

1. val Maximum slope [-] of the saturation-relative permeability curve when nearing fullsaturation. The default value is 100.

• • •

Generate tables from unsaturated functionsScope: .grok .mpropsThis instruction generates the tables from the previously defined function parameters andwrites the pressure saturation data to the file prefixo.p s table.material.dat and thesaturation-relative permeability data to the file prefixo.s k table.material.dat. Thesefiles are written in Tecplot compatible format so they can be easily plotted. The tabularvalues in the files can be copied into the .mprops file for use with the unsaturated tableinstructions described in Section 2.8.3.5

• • •

For example, if the following Van Genuchten function parameters were defined in the.mprops file:

unsaturated van genuchten functionsalpha2.25beta1.89residual saturation0.16


minimum relative permeability1e-2

table smoothness factor1e-2

table minimum pressure-10.

generate tables from unsaturated functions

end ! functions

then the contents of the pressure-saturation output file would be:

Title = "test.mprops/porous medium"# Van Genuchten function:# Residual water saturation 0.160000# Alpha 2.25000# Power index (beta) 1.89000# Pore connectivity 0.500000# Computed power index (gamma) 0.685218# Minimum relative permeability 0.100000E-01# Table minimum pressure -10.0000# Table maximum s-k slope 100.000# Table smoothness factor 0.100000E-01variables="Pressure","Saturation"zone t="Pressure - Saturation"#unsaturated tables#pressure-saturation-10.0000000000000 0.174869375404582-7.50000000000000 0.181552629607745-5.00000000000000 0.196301039876425-3.75000000000000 0.212424751627904-2.50000000000000 0.247430530192203-1.87500000000000 0.284639681867462-1.25000000000000 0.361026934163956-0.937500000000000 0.435114163471319-0.625000000000000 0.5645282090327470.000000000000000E+000 1.00000000000000#end ! pressure-saturation

The values used to define the table are included as comments, as are the instructions neededfor incorporating the tabular data in the .mprops file.


Figure 2.15 is a plot of the resulting constitutive relationships. Note that the .mprops fileand material names are used to form the Tecplot title and appear on the plot.

0 0.2 0.4 0.6 0.8 10

-2

-4

-6

-8

-10

Pre

ssur

e

Saturation0 0.2 0.4 0.6 0.8 1

0

0.2

0.4

0.6

0.8

1

Rel

ativ

e P

erm

eab

ility

Pressure-SaturationSaturation-Relative Permeability

Figure 2.15: Example of using functional parameters to generate tabular constitutiverelationships.

If desired, the .mprops file can be modified to use the tabular relationships. It is recommendedthat the Van Genuchten parameters that were used to generate the tabular data are retainedin the file, either as comments or inside a Skip on. . .Skip off section. For our example, wecould do the following:

skip onunsaturated van genuchten functions...etc...end ! functionsskip off

unsaturated tablespressure-saturation


-10.0000000000000 0.174869375404582-7.50000000000000 0.181552629607745-5.00000000000000 0.196301039876425-3.75000000000000 0.212424751627904-2.50000000000000 0.247430530192203-1.87500000000000 0.284639681867462-1.25000000000000 0.361026934163956-0.937500000000000 0.435114163471319-0.625000000000000 0.5645282090327470.000000000000000E+000 1.00000000000000end ! pressure-saturation

saturation-relative k0.000000000000000E+000 1.000000000000000E-0020.500000000000000 2.340977494655262E-0020.750000000000000 0.1801803622767890.875000000000000 0.3986020127583780.937500000000000 0.5916183070401001.00000000000000 1.00000000000000end ! saturation-relative kend ! unsaturated tables

We will now move on to discuss instructions which can be used to define tabular relationships.

2.8.3.5 Tabular Constitutive Relationships

The instructions described here can be used to modify the default variably-saturatedproperties for a porous medium, discrete fracture or dual continuum. Before issuing themit is necessary to choose which type of medium they should be applied to, as discussed inSection 2.8.1.

For each instruction we will again indicate its scope (i.e. .grok, .mprops, .fprops,.dprops). Recall that if an instruction is used in the prefix.grok file, it will affect thecurrent set of chosen zones, while in a properties (e.g. .mprops) file, it will only affect thenamed material of which it is a part.

Unsaturated tablesScope: .grok .mprops .fprops .dpropsCauses grok to use tables to describe the constitutive relationships for the medium andto begin reading a group of instructions that define the tables until it encounters an Endinstruction.

If no further instructions are issued, the default tabular parameter values given in Tables 2.12,2.14 and 2.17 will be used for porous media, discrete fractures and dual continua respectively.


In the case of porous and dual media, this instruction overrides the pseudo-soil default sothat relative permeability factors are applied to both horizontal and vertical flow.

• • •

The following instructions can be used to modify the default tables which define theconstitutive relationships:

Pressure-saturationScope: .grok .mprops .fprops .dprops

1. pressure(i), saturation(i)...end Pressure ψ [L] and saturation S [-].

Paired values of pressure ψ and saturation S should be entered from lowest pressure (i.e.most negative) to highest pressure, usually zero. The last line of the table must be an Endinstruction, and the number of entries in the list are counted automatically to determinethe table size.

• • •

Saturation-relative kScope: .grok .mprops .fprops .dprops

1. saturation(i), rel perm(i)...end Saturation S [-] and relative permeability krw [-].

Paired values of saturation S and relative permeability krw should be entered from lowestto highest saturation. The last line of the table must be an End instruction, and the numberof entries in the list are counted automatically to determine the table size.

• • •

2.8.4 Surface Flow

Unless you modify the default values, all zones (and elements) in the surface flow domainwill be assigned the default properties listed in Table 2.18.

For each instruction we will again indicate its scope (i.e. .grok, .oprops). Recall that ifan instruction is used in the prefix.grok file, it will affect the current set of chosen zones,while in a properties (e.g. .oprops) file, it will only affect the named material of which it isa part.

X frictionScope: .grok .oprops

1. val x friction factor [L−1/3 T], nx in Equation 2.35.


Table 2.18: Default properties for surface flow.

Parameter Value UnitName Surface flow defaultsX friction factor 0.0548 m−1/3 sY friction factor 0.0548 m−1/3 sRill storage height hds 0.0 mObstruction storage height ho 0.0 mNode coupling scheme SharedCoupling length 0.0001 m

• • •

Y frictionScope: .grok .oprops

1. val y friction factor [L−1/3 T], ny in Equation 2.36.

• • •

Time varying friction...EndScope: .oprops

1. time(i), nmann(i)...end Time [T] and Manning roughness coefficient [L−1/3 T].

Reads a table of time vs Manning roughness coefficient (nx = ny) instructions until itencounters an End instruction.

• • •

Time varying surface friction by temperature rasterScope: .grok

1. scale Friction scale factor [-]. Must be a strictly positive real value.

2. freezing temperature The freezing temperature [°C].

3. time(i), filename(i)...end The time [T] and raster filename list.

In cold regions during the winter, free surface water flow may be restricted as a result ofwater freezing at the ground surface. Freezing reduces the conductivity of the surface domain


toward water. To represent this phenomenon, the surface conductivity can be reduced byan increase in surface friction at freezing temperatures. This command uses the table oftemperature raster files to increase the surface friction by the provided scaling factor whenthe temperatures of the chosen surface elements drop below the freezing temperature. Forexample:

time varying surface friction by temperature raster10000 ! scale factor0.0 ! freezing temperature! times raster files0 temperature1.asc2592000 temperature2.asc5184000 temperature3.asc7776000 temperature4.asc10368000 temperature5.asc12960000 temperature6.asc

end

Note that this command cannot be used in conjunction with the command Time varyingfriction.

• • •

Rill storage heightScope: .grok .oprops

1. val Rill storage height [L], Hd in Section 2.2.2.2.

• • •

Obstruction storage heightScope: .grok .oprops

1. val Obstruction storage height [L], Ho in Section 2.2.2.2.

• • •

Coupling lengthScope: .grok .oprops

1. val Coupling length [L], lexch in Equation 2.71.

• • •


Maximum flow depthScope: .grok

1. val Maximum flow depth [L], in Equations 2.42 and 2.43, the maximum of do.• • •

Minimum elemental energy slopeScope: .grok

1. val Minimum elemental energy slope [-], in Equations 2.42 and 2.43, the minimum of∂ho/∂s.

• • •

Read rill storage from rasterScope: .grok

1. raster filename Path to the raster file containing the surface elevation [L] values.

2. scale factor Rill storage scaling factor [-]. Must be a strictly positive real value.

This command computes the rill storage height from the elevation values in the raster file foreach element in the surface layer of the mesh. It overrides any rill storage values specified bya properties (i.e., .oprops) file. The computed rill storage values are written to a Tecplotfile elemental rill storage.dat for visualization.

• • •

2.8.5 Evapotranspiration

NOTE: Moisture contents referred to below and in Section 2.5.3 are actually input in grokas saturations, which are less prone to error as they always vary between zero and one,while moisture content varies between zero and porosity.

Unless you modify the default values, all zones (and elements) in the ET domain will beassigned the default properties listed in Table 2.19.

For each instruction we will again indicate its scope (i.e. .grok, .etprops). Recall that ifan instruction is used in the prefix.grok file, it will affect the current set of chosen zones,while in a properties (e.g. .etprops) file, it will only affect the named material of which itis a part.

Canopy storage parameterScope: .etprops


Table 2.19: Default properties for evapotranspiration.

Parameter Value UnitName Default ET (grass)Canopy storage parameter 1.5 mmInitial interception storage 1.5 mmTranspiration fitting parameters:

C1 0.5C2 0.0C3 1.0

Transpiration limiting saturations:Wilting point 0.05Field capacity 0.2Oxic limit 0.6Anoxic limit 0.8

Evaporation limiting saturations:Minimum 0.5Maximum 0.1

Leaf area index 1.0Root zone depth 0.2 mEvaporation depth 0.2 m

1. cint et Canopy storage parameter [L], cint in Equation 2.73.• • •

Note that canopy evaporation is assumed to be zero when LAI is less than 10−8.

Initial interception storageScope: .etprops

1. init sint et initial canopy interception storage value [L], S0int in Equation 3.61.

• • •

Transpiration fitting parametersScope: .etprops

1. C 1 Coefficient C1 [-] in Equation 2.75.

2. C 2 Coefficient C2 [-] in Equation 2.75.

3. C 3 Coefficient C3 [-] in Equation 2.77. By default, this coefficient is set to 1.0, whichgives a linear ramping function whereas higher values would give higher order rampingfunctions.


• • •

Transpiration limiting saturationsScope: .etprops

1. thwp et Saturation [-] at wilting point, θwp in Equation 2.77.

2. thfc et Saturation [-] at field capacity, θfc in Equation 2.77.

3. tho et Saturation [-] at oxic limit, θo in Equation 2.77.

4. than et Saturation [-] at anoxic limit, θan in Equation 2.77.

• • •

Transpiration limiting pressure headScope: .etprops

1. Hwp et Pressure head [L] at wilting point, ψwp = ψ(θwp).

2. Hfc et Pressure head [L] at field capacity, ψfc = ψ(θfc).

3. Ho et Pressure head [L] at oxic limit, ψo = ψ(θo).

4. Han et Pressure head [L] at anoxic limit, ψan = ψ(θan).

This is an alternative to the Transpiration limiting saturations command.• • •

Evaporation limiting saturationsScope: .etprops

1. the2 et Saturation [-] below which evaporation is zero, θe2 in Equation 2.85.

2. the1 et Saturation [-] above which full evaporation can occur, θe1 in Equation 2.85.

• • •

Evaporation limiting pressure headScope: .etprops

1. He2 et Pressure head [L] below which evaporation is zero, ψe2 = ψ(θe2).

2. He1 et Pressure head [L] above which full evaporation can occur, ψe1 = ψ(θe1).


This is an alternative to the Evaporation limiting saturations command• • •

The following instruction can be used to modify the default value (1.0 for all time) of theleaf area index (LAI):

LAI tables...EndScope: .etprops

1. time(i), lai(i)...end Time [T] and leaf area index [-].

Reads a table of time and leaf area index until it encounters an End instruction. Pairedvalues of time t and leaf area index LAI should be entered from earliest to latest time. Thenumber of entries in the list are counted automatically to determine the table size.

Observed values of leaf are index [Scurlock et al., 2001] and maximum rooting depth [Canadellet al., 1996] for various terrestrial biomes are shown in Table 2.20.

• • •

Root depthScope: .etprops

1. root depth et Maximum root depth [L].

A normalized root depth function is mapped onto porous media elements above this maxi-mum depth. Currently, four root depth functions are available; constant, linear, quadraticand cubic, as shown in Figure 2.16. These functions are defined such that the area underthe normalized function is 1.0.

• • •

By default, the linear form of the depth function is used. The following instructions areavailable for using the other forms:

Rdf constant functionRdf quadratic decay functionRdf cubic decay function

Root growth...Endgrok reads instructions that define a root growth function until it encounters an Endinstruction.

• • •

Root growth can be defined by a table using the command:


Table 2.20: Observed values of leaf area index [Scurlock et al., 2001] and maximumrooting depth [Canadell et al., 1996] for various terrestrial biomes.

Vegetative cover Leaf area Maximum rootingindex depth (m)

Desert 1.31 9.5Tundra, circumpolar and alpine 2.69 0.5Wetlands, temperate and tropical 6.34Grasslands, temperate 2.50 2.6Grasslands, tropical 2.50 15.0Crops, temperate and tropical 4.22 2.1Shrubland, heath or Mediterranean-type vegetation 5.2Forest:

boreal deciduous broadleaf 2.64 2.0boreal evergreen needleleaf 3.50 2.0boreal/temperate deciduous needleleaf 4.63 2.0temperate deciduous broadleaf 5.12 2.9temperate evergreen needleleaf 6.70 3.9temperate evergreen broadleaf 5.82tropical deciduous broadleaf 3.92 3.7tropical evergreen broadleaf 4.90 7.3Plantations (managed forests) 8.72

Overall mean 5.23


Figure 2.16: Normalized root depth functions.


Time-root depth table...EndReads a time and root depth time series until it encounters an End instruction.

• • •

Root growth can also be defined by a logistic growth function via the following commands:

Root growth period1. Rg period Period for vegetation growth [T], typically one year.

• • •

Growth beginning time1. Rg begin Start time of root growth [T].

• • •

Harvest time1. Rg harvest Crop harvest time [T].

• • •

Initial root depth1. Rg initdepth Initial crop root depth [L].

• • •

Maximum root depth1. Rg maxdepth Maximum crop root depth [L].

• • •

Verhulst-Pearl growth, time-depth1. Rg vptime, Rg vpdepth Time [T] and crop root depth [L] data that is used to

derive a Verhulst–Pearl growth function.


• • •

Verhulst-Pearl growth, 50% max depthFor Verhulst–Pearl growth, 50% of the maximum crop root depth is assumed to be reachedafter 50% of the growing season.

• • •

The following is an example of defining root growth via a logistic growth function.

root growth! option #1! time-root depth table! end! option #2

root growth period365.0d0growth beginning time160.0d0harvest time250.0d0initial root depth0.1maximum root depth80.d0! verhulst-pearl growth, time-depth! 205.0 40.0d0! option #3verhulst-pearl growth, 50\% max depth

end

Evaporation depthScope: .etprops

1. evap depth et Evaporation depth [L].

Evaporation as a function of depth is treated in a similar fashion as the root zone depthdescribed above.

• • •

By default, the linear form of the evaporation function is used. The following instructionsare available for using the other forms:


Edf constant functionEdf quadratic decay functionEdf cubic decay function

Canopy evaporation intervalScope: .grok

1. time interval The canopy evaporation time interval [T] (non-negative real value).The default value is zero.

The canopy evaporation interval ∆tcan controls the calculation of canopy evaporation Ecanby limiting the canopy evaporation rate over that time interval. Effectively, canopy storageis allowed to empty only once per interval. For each element in the porous media domain atsimulation time t

Ecan = min(EP, cint · LAI/∆tcan, PCP + S0

int/∆t), ∆tcan > 0min(EP, PCP + S0

int/∆t), otherwise,

where EP is the potential evaporation, PCP is the precipitation, cint is the canopy storageparameter, LAI is the leaf area index, ∆t is the timestep, and S0

int is the interception storagecomputed at the previous simulation time.

• • •

Potential evaporation using transpirationScope: .grokWith this instruction potential evaporation is calculated using Equation 2.81. By defaultpotential evaporation is calculated from Equation 2.83.

• • •

Echo et at pointScope: .grok

1. x1, y1 xy-coordinate.

This instruction finds the column of nodes that the given coordinate falls within and thenwrites the pertinent evapotranspiration information to the o.eco file.

• • •

For example:

ET properties for element column


ZONE: 1ET MATERIAL: dense deciduous forest

Canopy storage parameter = 0.0Transpiration fitting parameter C1 = 0.3Transpiration fitting parameter C2 = 0.2Transpiration fitting parameter C3 = 3.0E-6Moisture content at wilting point = 0.32Moisture content at field capacity = 0.2Moisture content at oxic limit = 0.76Moisture content at anoxic limit = 0.9Moisture content at at energy limiting maximum = 0.32Moisture content at at energy limiting minimum = 0.2Initial interception storage = 0.0

Tabular data:Time LAI

0.00000 2.080000.100000E+42 2.08000

Maximum evaporative zone depth = 2.0Depth EDF

0.00000 2.000001.00000 0.00000

Maximum root zone depth = 4.0Depth RDF

0.00000 2.000001.00000 0.00000

ELEMENT ET FLAG DEPTH EDF RDF12889 T 0.00000 0.281045 0.14630511528 T 0.303244 0.234783 0.13474010167 T 0.606488 0.188522 0.1231748806 T 0.909732 0.142261 0.1116097445 T 1.21298 0.959994E-01 0.1000446084 T 1.51622 0.497381E-01 0.884783E-014723 T 1.81946 0.765174E-02 0.769130E-013362 T 2.1227 0.00000 0.653477E-012001 T 2.4259 0.00000 0.537824E-01640 T 2.7292 0.00000 0.422171E-01

------------ ------------Totals 1.00000 0.942610

In this case, the element column falls in ET zone 1, and the default linear root depth andevaporation depth functions have been used and mapped onto it. All of the evaporative


potential has been distributed to the element column, as indicated by a total EDF value of1.0. However, only a portion (0.942610 or 94%) of the total RDF of 1.0 has been mappedonto it, because the maximum root zone depth (4 m) exceeds the total depth of the elementcolumn at this point (2.7292 m).

2.8.6 Transport


By default, all porous media zones (and elements) in the domain will be assigned defaultporous media transport properties which are listed in Table 2.21. Included here are pa-

Table 2.21: Default values for porous media transport properties.

Parameter Value UnitLongitudinal dispersivity αl 1.0 mHorizontal component of transverse dispersivity αt 0.1 mVertical component of transverse dispersivity αt 0.1 mBulk density ρ 2031.25 kg m−3

Tortuosity τ 0.1Immobile zone porosity θImm 0.0Immobile zone mass transfer coefficient αImm 0.0 s−1

Reverse fractionation rate kr 0.0 s−1

Fractionation factor αr 0.0Mass ratio, solid to water phases xr 0.0Thermal conductivity of the solids ks 3.0 W m−1 K−1

Specific heat capacity of the solids cs 738.0 J kg−1 K−1

Density of the solids ρs 2650.0 kg m−3

rameters for modifying the porous medium so that it acts as a double-porosity medium forsimulating transport, as described in Section 2.7.1.3 and also for isotopic fractionation, asdescribed in Section 2.7.1.4.

The following instructions can be applied to porous media, as discussed in Section 2.8.1, tomodify the default transport parameters. For each instruction we will indicate its scope (i.e..grok .mprops). Recall that if an instruction is used in the prefix.grok file, it will affectthe current set of chosen zones, while in a properties (e.g. .mprops) file, it will only affectthe named material of which it is a part.

Longitudinal dispersivityScope: .grok .mprops

1. val Longitudinal dispersivity [L], αl in Equation 2.104.• • •


Transverse dispersivityScope: .grok .mprops

1. val Horizontal component of the transverse dispersivity [L], αt in Equation 2.104.

• • •

Vertical transverse dispersivityScope: .grok .mprops

1. val Vertical component of the transverse dispersivity [L], αt in Equation 2.104.

• • •

TortuosityScope: .grok .mprops

1. val Tortuosity [-], τ in Equation 2.104.

• • •

Effective diffusion coefficient listScope: .grok .mprops

1. diff coeff(i), i=1,nspecies Effective diffusion coefficient [L2 T−1] for each species.

Assigns an effective diffusion coefficient for each species.• • •

Anisotropic tortuosity ratioScope: .grok .mprops

1. y tortratio Tortuosity ratio [-] in the y-direction. Default value is 1.

2. z tortratio Tortuosity ratio [-] in the z-direction. Default value is 1.

By default, tortuosity is isotropic, since the ratio values are set to 1 in both the y- andz-directions. You may make tortuosity anisotropic by entering a value greater than 0 andless than 1. These values will be used to multiple the tortuosity, τ in the y- and z-directionsrespectively, to obtain the directional values.

• • •


Bulk densityScope: .grok .mprops

1. val Bulk density of dry soil [M L−3]. If necessary, the bulk density of a solid iscalculated as ρs = ρb/(1− θs).

• • •

By default, the porous medium acts as a single-porosity medium (i.e. the immobile zoneis inactive) because the porosity and mass transfer coefficient are set to zero. In order toactivate the double porosity feature, you can enter non-zero values for these parametersusing the following two instructions:

Immobile zone porosityScope: .grok .mprops

1. val Immobile zone porosity [-], θImm in Equations 2.108, 2.144 and 2.145.

• • •

Immobile zone mass transfer coefficientScope: .grok .mprops

1. val Immobile zone mass transfer coefficient [T−1], αImm in Equation 2.143.

• • •

Isotope fractionation data...EndScope: .mpropsCauses grok to begin reading a group of isotope fractionation instructions until it encountersan End instruction.

If no further instructions are issued, the default isotopic fractionation parameter valueslisted in Table 2.21 will be used.

• • •

The following three instructions can be used to change these values:

Reverse rateScope: .mprops

1. val Reverse fractionation rate [L−1], kr in Equation 2.152.


• • •

Fractionation factorScope: .mprops

1. val Fractionation factor [-], αr in Equation 2.152.

• • •

Rock-water mass ratioScope: .mprops

1. val Isotopic rock-water mass ratio [-], xr in Equation 2.109.

• • •

The next instructions can be used to change the thermal properties of the porous medium:

Thermal conductivity of solidScope: .grok .mprops

1. val Temperature invariant thermal conductivity of the solids [W L−1 K−1]. The bulkthermal conductivity is computed internally from the volume fractions of the solidand liquid phases.

• • •

Temperature-dependent thermal conductivity of solidScope: .grok .mprops

1. k s1 Thermal conductivity [W L−1 K−1] at temperature t s1.

2. t s1 Temperature [°C] at which the thermal conductivity is equal to k s1.

If this instruction is specified, then the thermal conductivity of the solid phase is temperaturedependent. The bulk thermal conductivity is also temperature dependent and is computedinternally from the volume fractions of the solid and liquid phases. It is assumed here thatthe thermal conductivity of the solids decreases at a constant rate of 1% per 10 °C increase intemperature and the relationship between thermal conductivity and temperature is definedby the pair of values (k s1, t s1).

• • •


Geometric bulk thermal conductivity relationScope: .mpropsThe default equation used to compute the bulk thermal conductivity is Equation 2.123.If that instruction is specified, the thermal conductivity of the porous medium is insteadcomputed with Equation 2.126.

• • •

Nonlinear bulk thermal conductivity relationScope: .mprops

1. k sat Thermal conductivity of the saturated porous medium [W L−1 K−1].

2. k dry Thermal conductivity of the dry porous medium [W L−1 K−1].

3. k C Fitting parameter [-].

The default equation used to compute the bulk thermal conductivity is Equation 2.123.If that instruction is specified, the thermal conductivity of the porous medium is insteadcomputed with Equation 2.127.

• • •

Specific heat capacity of solidScope: .grok .mprops

1. val Specific heat capacity of the solid phase [J kg−1 K−1]. The default value is 730.0J kg−1 K−1.

• • •

Note that the density of the solid phase of the porous medium is now computed automaticallyfrom the bulk density and porosity.


By default, all fracture zones (and elements) in the domain will be assigned default transportproperties which are listed in Table 2.22.

The following instructions can be applied to discrete fractures, as discussed in Section 2.8.1,to modify the default transport parameters. For each instruction we will indicate its scope(i.e. .grok .fprops). Recall that if an instruction is used in the prefix.grok file, it willaffect the current set of chosen zones, while in a properties (e.g. .fprops) file, it will onlyaffect the named material of which it is a part.


Table 2.22: Default values for discrete fracturetransport properties.

Parameter Value UnitLongitudinal dispersivity αl 1.0 mTransverse dispersivity αt 0.1 m

Longitudinal dispersivityScope: .grok .fprops

1. val Longitudinal dispersivity [L], similar to αl in Equation 2.104.

• • •

Transverse dispersivityScope: .grok .fprops

1. val Transverse dispersivity [L], similar to αt in Equation 2.104.

• • •

Coupling dispersivityScope: .grok .oprops

1. val Dispersivity value [L] to be applied during exchange between the overland flowand subsurface domains. Default value is 0.0.

• • •


By default, all dual continua zones (and elements) in the domain will be assigned defaulttransport properties which are listed in Table 2.23.

The following instructions can be applied to dual continua, as discussed in Section 2.8.1, tomodify the default transport parameters. For each instruction we will indicate its scope (i.e..grok .dprops). Recall that if an instruction is used in the prefix.grok file, it will affectthe current set of chosen zones, while in a properties (e.g. .dprops) file, it will only affectthe named material of which it is a part.

Longitudinal dispersivityScope: .grok .dprops


Table 2.23: Default values for dual-continua transport properties.

Parameter Value UnitLongitudinal dispersivity αld 1.0 mHorizontal component of transverse dispersivity αtd 0.1 mVertical component of transverse dispersivity αtd 0.1 mBulk density ρbd 2650.0 kg m−3

Tortuosity τd 0.1First-order mass transfer coefficient αs 0.0 s−1

1. val Longitudinal dispersivity [L], αld in Equation 2.112.

• • •

Transverse dispersivityScope: .grok .dprops

1. val Horizontal component of the transverse dispersivity [L], αtd in Equation 2.112.

• • •

Vertical transverse dispersivityScope: .grok .dprops

1. val Vertical component of the transverse dispersivity [L], αtd in Equation 2.112.

• • •

TortuosityScope: .grok .dprops

1. val Tortuosity [-], τd in Equation 2.112.

• • •

Anisotropic tortuosity ratioScope: .grok .mprops

1. y tortratio Tortuosity ratio [-] in the y-direction. Default value is 1.

2. z tortratio Tortuosity ratio [-] in the z-direction. Default value is 1.


By default, tortuosity is isotropic, since the ratio values are set to 1 in both the y- andz-directions. You may make tortuosity anisotropic by entering a value greater than 0 andless than 1. These values will be used to multiple the tortuosity, τd in the y- and z-directionsrespectively, to obtain the directional values.

• • •

Bulk densityScope: .grok .dprops

1. val Bulk density [M L−3], ρbd in Equation 2.111.

• • •

First-order mass exchangeScope: .dprops

1. val First-order mass transfer coefficient [L−1], αs in Equations 2.147 and 2.148.

• • •

2.8.6.4 Surface Runoff

By default, all surface flow zones (and elements) in the domain will be assigned defaulttransport properties which are listed in Table 2.24.

Table 2.24: Default values for surface flow trans-port properties.

Parameter Value UnitLongitudinal dispersivity αlo 1.0 mTransverse dispersivity αto 1.0 mCoupling dispersivity 0.0 m

The following instructions can be applied to the surface flow domain, as discussed in Sec-tion 2.8.1, to modify the default transport parameters. For each instruction we will indicateits scope (i.e. .grok, .oprops). Recall that if an instruction is used in the prefix.grok file,it will affect the current set of chosen zones, while in a properties (e.g. .oprops) file, it willonly affect the named material of which it is a part.

Longitudinal dispersivityScope: .grok .oprops


1. val Longitudinal dispersivity [L], αlo. Analogous to αl in Equation 2.104.

• • •

Transverse dispersivityScope: .grok .oprops

1. val Horizontal component of the transverse dispersivity [L], αt. Analogous to αt inEquation 2.104.

• • •

Coupling dispersivityScope: .grok .oprops

1. val Dispersivity value [L] to be applied during exchange between the overland flowand subsurface domains. Default value is 0.0.

• • •

Dry albedoScope: .grok .oprops

1. Value Dry albedo [-] for soil type, αdry in Equation 2.132. Default value is 0.35.

• • •

Saturated albedoScope: .grok .oprops

1. Value Saturated albedo [-] for soil type, αsat in Equation 2.132. Default value is 0.18.

• • •

Heat coupling lengthScope: .grok .oprops

1. Value Heat coupling length [L]. The depth of the surface/subsurface exchange zoneused to compute αo in Equation 2.151. Default value is 10−4 m.

• • •


2.9 Winter Processes

2.9.1 Groundwater Flow with Freezing and Thawing of Pore Water

The following commands can be used to control the freezing and thawing of pore water inthe porous medium and dual continuum domains (see Sections 2.6.2–2.6.3).

Pore water freezing-thawing...EndDefines the pore water freezing and thawing parameters for the porous medium and dualcontinuum domains until it encounters an End instruction. Note that all temperatures mustbe specified in terms of degrees Celsius. For example:

pore water freezing-thawingsurface temperature

0 -7.02592000 -6.15184000 -0.97776000 6.210368000 12.912960000 18.015552000 20.218144000 19.320736000 14.823328000 8.625920000 2.428512000 -4.031104000 -7.0

end

thermal diffusivity2.0e-7

background temperature6.0

melting temperature-0.5

freezing temperature0.5

maximum freezing depth2.0


integration convergence criteria0.01

memory length for convolution integral15552000.0

interpolate surface temperatureend

• • •

The Pore water freezing-thawing...end command is composed of the following subcommands:

Surface temperature1. time(i), val(i)...end The time [T] and surface temperature [°C] value list.

At time time(i) the value val(i) is applied and maintained until time time(i + 1). Thelast value entered in the list will be applied until the end of the simulation. Note that thiscommand cannot be used in conjunction with the command Surface temperature from raster.

• • •

Surface temperature from raster1. time(i), filename(i)...end The time [T] and raster file name list.

At time time(i) the raster file filename(i) is applied and maintained until time time(i+1).The last raster file entered in the list will be applied until the end of the simulation. Hydro-GeoSphere uses the nodal xy-coordinate to interpolate a value for the surface temperature[°C] at each time and location. Note that this command cannot be used in conjunction withthe command Surface temperature.

• • •

Thermal diffusivity1. thermal diff Thermal diffusivity [L2 T−1]. Default value of 2× 10−7 [m2 s−1].

• • •

Background temperature


1. background temp Background temperature [°C].

• • •

Melting temperature1. melting temp Melting temperature [°C].

• • •

Freezing temperature1. freezing temp Freezing temperature [°C].

• • •

Maximum freezing depth1. freezing depth Maximum freezing depth [L].

• • •

Integration convergence criteria1. tol Integration convergence criteria [T−1/2 °C]. Default value of 0.01 [s−1/2 °C].

Controls the approximation quality of the integral that defines the porous medium tempera-ture. If In is the approximation of the integral on n points and I2n is the approximation ofthe integral on 2n points, then convergence of this approximation is defined by

|I2n − In| ≤ tol,

where n = 2kn0 for k = 0, 1, 2, . . ..• • •

Integration maximum iterations1. maxits Maximum number of iterations for integration convergence. Default value of

20.

Terminates the approximation of the integral that defines the porous medium temperatureafter maxits iterations and issues a warning message to the screen and the .lst file.


• • •

Memory length for convolution integral1. memory length Memory length for convolution integral [T]. Default value of

15,552,000.0 [s] (6 months).

The memory length of the convolution integral can be set to control the amount of thermalmemory in the system. After a certain amount of time relative to the past, there shouldbe no influence on the present value of the porous medium temperature. In practice, thememory length of the convolution integral should be set to half the surface temperaturecycle length. For example, if seasonally varying ground surface temperature is cyclic over aperiod of a year, then an appropriate memory length is 6 months (in consistent time units).If a diurnal temperature cycle was being simulated, then an appropriate memory lengthwould be 12 hours.

• • •

Interpolate surface temperatureCauses the surface temperature to be interpolated over the time window that contains thecurrent simulation time. Otherwise, by default, the surface temperature is held constantover the time window and is equal to the temperature at the left endpoint of the window.

• • •

The following commands can be used to control freezing and thawing in the dual continuumdomain.

No freezing in dual domainTurns off freezing in the dual domain. Note that this command cannot be used in conjunctionwith the command Dual freezing by pm temperature.

• • •

Dual freezing by pm temperature1. transfer coeff Thermal transfer coefficient [T °C−1].

Makes the freezing rate of the dual domain a linear function of porous medium temperaturebelow the freezing temperature. The slope of the linear relationship is given by the thermaltransfer coefficient. Note that this command cannot be used in conjunction with the com-mand No freezing in dual domain.


• • •

2.10 Output

During execution, grok and HydroGeoSphere create many output files, for which acomplete list with brief descriptions can be found in Appendix A. Here, we will discuss inmore detail the output which is of most interest to the user.

The main mechanism for generating output from HydroGeoSphere is through the useof the Output times instruction. For each output time defined by the user, there will be aproblem dependent set of output files which will be generated automatically. Here is a partiallist of the files which were created by the verification problem described in Section 4.5.2:

f_cdo.head.0001f_cdo.velocity_darcy.0001f_cdo.velocity_darcy_fracture.0001f_cdo.velocity_linear.0001f_cdo.velocity_linear_fracture.0001f_cdo.fracture_aperture.0001f_cdo.concentration.Radium.0001f_cdo.concentration.Thorium.0001f_cdo.concentration.Uranium.0001f_cdo.concentration.Radium.0002f_cdo.concentration.Thorium.0002f_cdo.concentration.Uranium.0002

As you can see, file names are made up of the problem prefix, in this case f cd, a descriptor,for example o.concentration.Radium. and a 4-digit number such as 0001, which relatesthe data contained in the file to an output time number. Note that for output time number0001, there are quite a few more output files than for number 0002. This is because the flowsolution in this case is steady-state, and so it is fully described by one set of output. Fortimestep 0002, only variables which have changed are output, in this case the concentrationsof the three species in the transport solution. Finally, the set of files which gets generatedis problem dependent, and so certain types of files may or my not appear. For example,since this problem has discrete fractures, we are seeing some fracture velocity and apertureoutput.

In order to conserve disk space and increase the efficiency of file I/O, these files are all storedin binary format, so they can not be viewed with a standard text editor. However, throughthe use of the post-processing tool HSPLOT, which is described in Section E, it is possibleto create ASCII versions of the data contained in these files which are also compatible withthe third-party visualization tools Tecplot and Paraview.


By default, simulation time is written in listing and output files in a fixed format using theFortran F format descriptor f17.5, which is not suitable for outputting times greater than999,999 or less than 0.00001. If you prefer to use scientific notation, you can choose it usingthe instruction:

Time output scientific format

The other option is to use the Fortran G format descriptor (i.e. general format) in which amix of fixed and scientific format is used depending on the magnitude of the output. If youprefer this notation, you can choose it using the instruction:

Time output general format

Since these instructions can be used in the debug.control file (see Section B), it mightsometimes be useful to switch back to fixed format. To do so, use the instruction:

Time output fixed format

Similarly, mass balance output can be controlled by the instructions:

Mass balance output scientific formatMass balance output general formatMass balance output fixed format

2.10.1 Grid

The following instructions can be useful in checking the results of the grid generation section.

Echo coordinatesCauses node coordinates to be written to the prefixo.eco file.

• • •

Echo incidencesCauses element incidences to be written to the prefixo.eco file.

• • •

Echo fracture incidencesCauses fracture element incidences to be written to the prefixo.eco file.

• • •

List surface flow nodesCauses the list of surface flow nodes to be written to the prefixo.eco file.


• • •

Write faces and segmentsWhenever HydroGeoSphere generates a 3-D mesh, it makes lists of the nodes whichcomprise each unique face and line segment. This information is used by certain instructionswhich choose faces or segments. You can use this instruction to write the information toa file which will receive the name prefixo.fac. These files can become quite large, so thedefault is not to save them. See also Section 2.3.8.

• • •

2.10.1.1 GMS

The following instructions can be used to export data generated by grok (e.g. 2-D and 3-Dmeshes, wells, fractures etc.) to GMS.

Mesh to gms1. gmsfile Name of the file to which the 3-D mesh information (blocks or prisms) will

be written in GMS-readable format.

• • •

2D mesh to gms1. gmsfile Name of the file to which the 2-D mesh information (quadrilaterals or triangles)

will be written in GMS-readable format.

• • •

Rectangles to triangles1. ofile Name of the file to which the 2-D triangular mesh information will be written in

GMS-readable 2-D mesh file format. Each rectangle in the 2-D mesh is split into twotriangles. Nodal coordinates are written first followed by element node lists.

• • •

The following instructions should be placed near the end of the prefix.grok file after anyinstructions which are used to generate wells or fractures.

Wells to gms


1. gmsfile Name of the file to which the 1-D line information (wells and/or tile drains)will be written in GMS-readable borehole file format.

• • •

Fractures to gms1. gmsfile Name of the file to which the 2-D fracture element information which will be

written in GMS-readable 2-D mesh file format.

• • •

2.10.1.2 Tecplot

The following instructions can be used to export data generated by grok to Tecplot.

Mesh to tecplot1. tecfile The name of the file to which the 3-D mesh information (blocks or prisms) will

be written in Tecplot readable format.

• • •

Wells to tecplot1. tec wells file Name of the file to which the 1-D well element information will be

written in Tecplot LINE3D geometry format.

• • •

Tiles to tecplot1. tec tiles file Name of the file to which the 1-D tile drain element information will be

written in Tecplot LINE3D geometry format.

• • •

K to tecplot1. tecfile Name of the file to which the elemental hydraulic conductivity information

will be written in Tecplot readable format.


This instruction will also force grok to create prefixo.ElemK pm(dual).0001 that can beprocessed by HSPLOT. Elemental K will be included in the Tecplot file generated byHSPLOT. The elemental hydraulic conductivity values are written as cell-based variables.

• • •

Porosity to tecplot1. tecfile The name of the file to which the porosity information (blocks or prisms) will

be written in Tecplot readable format.

• • •

Tortuosity to tecplot1. tecfile The name of the file to which the tortuosity information (blocks or prisms)

will be written in Tecplot readable format.

• • •

ET zones to tecplotScope: .grok .etprops

1. tecfile The name of the file to which the ET zones information (blocks or prisms) willbe written in Tecplot readable format.

• • •

2.10.2 Flow Solution

The following instructions affect the I/O for the flow solution.

Echo to outputCauses heads, saturations,concentrations and velocities for the subsurface domain to bewritten to the .lst file as well as to the binary output files.

• • •

Flux output nodes1. new noutfc Number of new output nodes desired.


2. ioutfc(i), i=1,new noutfc Flux output node number.

Listed nodes are flagged as flux output nodes, at which detailed fluid flux [L3 T−1] informationfor the subsurface domain is output at each timestep. Flux output is written to a file calledprefixo.flu. For each timestep in the flow solution, one line per flux output node willbe written to the file. Each line contains the node number, time, fluid flux and nodalcoordinates. Such output can be imported into an editor (e.g., Microsoft Excel) and sortedby column to facilitate, for example, the creation of a plot of fluid flux versus time at anode.

For an example which uses flux output nodes, see verification problem in Section 4.5.1.• • •

Flux output nodes from chosenThis instruction works in a similar way to Flux output nodes except that all currently chosennodes are flagged as flux output nodes.

• • •

Binary flux output nodesThis instruction works in a similar way to Flux output nodes and requires identical input.However, it creates a binary file called prefixo.flu b.

• • •

Binary flux output nodes from chosenThis instruction works in a similar way to Binary flux output nodes except that all currentlychosen nodes are flagged as flux output nodes.

• • •

Output saltwater headBy default, when running density-dependent flow problems, the equivalent freshwater headis written to the head file (e.g. f cdo.head.0001). This instruction causes salt water headsto be written instead.

• • •

Soil water balanceThis instruction generates the information on the amount of water in the partially-saturatedand fully-saturated subsurface, and in the surface. The information includes the amountof water in the top 10 cm and top 1 meter of the subsurface. The file is named pre-


fixo.soil balance.dat.• • •

Report exchange for olf zonesThis instruction generates the information on the exchange flux for each overland zoneseparately in the file named prefixo.fluid exchange olfz.dat.

• • •

Report exchange flux for chosen nodesScope: .grok

1. label Descriptive name for the exchange flux up to 80 characters.

This command generates time series output of the exchange fluxes for the current domain(overland flow or channel flow) and the current set of chosen nodes. Output is written tothe file named prefixo.fluid exchange domain.label.dat, where domain is either olf orchan. Note that labels must be unique across multiple instantiations of this command.

• • •

Compute water volume by zoneWith this instruction, the model reports the water volume stored in each of porous mediumand overland flow zones in prefixo.water volume pm zone.dat andprefixo.water volume olf zone.dat.

• • •

Output ET detailsThis instruction generates the information of ET details for each PET boundary inET Detailed Info bcname.dat.

• • •

2.10.2.1 Observation Wells and Points

The following instructions are used to output hydraulic head, pressure head, saturation (ifvariably-saturated) and nodal fluid flux at a single node or a group of nodes lying on a line.

Output is written to a Tecplot formatted file called prefixo.observation well flow.-obs well name.dat.

If the problem is formulated as a dual continuum then extra columns of output will be


produced with the dual continuum head, pressure head, saturation (if variably-saturated)and fluid flux. If the node is not a dual continuum node, no data values (currently −999.0)will be written instead.

If the problem is formulated with a surface flow domain then extra columns of output willbe produced with surface flow total and pressure head and fluid flux. If the node is not asurface flow node, a no data value (currently −999.0) will be written instead.

These instruction do not affect the flow solution.

Make observation point1. well name Descriptive name for the well up to 40 characters.

2. x1, y1, z1 xyz-coordinates of the observation point.

The node closest to this point will be flagged as an observation point node.

Data for each timestep in the flow solution is written as one line in the output file. Each linecontains the time and then the porous medium hydraulic head, pressure head, saturation (ifvariably-saturated), fluid flux, node coordinates and node number.

• • •

Make interpolated observation pointScope: .grok

1. well name Descriptive name for the well up to 40 characters.

2. x, y, z xyz-coordinates of the observation point.

Output values are linearly interpolated from the nodal values at the vertices of the elementthat contains the observation point (x, y, z). Depending on the model setup, each linecontains the time, porous medium hydraulic head, pressure head, saturation, ice saturation,transpiration, evapotranspiration, the observation point coordinates, and the element id.Note that this command applies only to the porous medium domain.

• • •

Make node observation point1. well name Descriptive name for the well up to 40 characters.

2. nnumber The number of the node to be made an observation point.

This node will be flagged as an observation point node. Data for each timestep in the flowsolution is written as one line in the output file. Each line contains the time and then the


porous medium hydraulic head, pressure head, saturation (if variably-saturated), fluid flux,node coordinates and node number.

• • •

Make observation well1. well name Descriptive name for the well up to 40 characters.

2. x1, y1, z1 xyz-coordinates of one end of the observation well.

3. x2, y2, z2 xyz-coordinates of the other end of the observation well.

Element face edges (i.e. segments) which form the shortest path between the two nodesclosest to the end points of the well (i.e. (x1, y1, z1) and (x2, y2, z2)) will be chosen toproduce output.

Each timestep in the flow solution represents a Tecplot zone in the output file, and eachzone contains one line per observation well node. Each line contains the porous mediumhydraulic head, pressure head, saturation (if variably-saturated), fluid flux, node coordinatesand node number. Note that fluid fluxes at internal nodes are currently reported as zerounless they are constant head or specified flux nodes.

• • •

Make observation well from xy1. well name Descriptive name for the well up to 40 characters.

2. x1, y1 xy-coordinates of the observation well.

3. isheet1, isheet2 Bottom and top sheet numbers.

This instruction creates a observation well located at the closest point from x- and y-coordinates between two sheet numbers.

• • •

2.10.2.2 Fluid Mass Balance

By default, fluid mass balance information is computed at each time step and written to theprefixo.lst file. Figure 2.17 illustrates some sample output as it appears in the .lst file.

--------------------------------------------------------------------FLUID BALANCE, TIME: 0.500000000000000

--------------------------------------------------------------------


RATE OF FLUID EXCHANGE IN OUT NET(IN-OUT)TOTAL

Fixed flux 0.0059395897 0.0000000000 0.0059395897Critical depth 0.0000000000 0.0000000000NET1 EXCHANGE RATE (IN-OUT) 0.0059395897

RATE OF FLUID ACCUMULATION [L**3/T]Porous medium 0.0003197172Overland 0.0057208226NET2 ACCUMULATION RATE 0.0060405397

FLUID BALANCE ERRORAbsolute: (NET1-NET2) -0.0001009500Relative: (NET1-NET2)/(abs(NET1)+abs(NET2))/2.0 0.0168529029Percent: abs(NET1-NET2)/NET1(+ve)*100.0d0 1.6996119929

FLUID EXCHANGE BETWEEN SURFACE AND SUBSURFACE DOMAINInfiltration 0.0003219343Exfiltration 0.0000000000

Figure 2.17: Example of fluid balance information written to file prefixo.lst.

This detailed fluid balance information is also written to a Tecplot formatted ASCII outputfile called prefixo.water balance.dat so that it can be easily visualized. For each timestepin the flow solution one line is written to the file. The number of columns in the file dependson the nature of the problem. For example, for problems with no overland flow component,no overland flow data will be written to the file.

The first section of the fluid balance information relates to the rate at which water is entering(IN) or leaving (OUT) the domain via the various types of sources and sinks. Columnheadings that could appear in this section are:

• 1st+ 1st- The rate at which water is entering or leaving the domain via porous mediafirst-type nodes.

• 1stdual+ 1stdual- The rate at which water is entering or leaving the domain viadual continuum first-type nodes.

• 1stSurface+ 1stSurface- The rate at which water is entering or leaving the domainvia overland flow first-type nodes.

• 2nd+ 2nd- The rate at which water is entering or leaving the domain via second-typenodes.

• EvapoTrans- The rate at which water is leaving the domain via evapotranspiration.

• Well+ Well- The rate at which water is being added to or removed from the domainvia wells.

• Tile+ Tile- The rate at which water is being added to or removed from the domainvia tile drains.


• River+ River- The rate at which water is entering or leaving the domain via rivernodes, as defined in Section 2.3.2.4.

• Drain- The rate at which water is entering or leaving the domain via drain nodes, asdefined in Section 2.3.2.3.

• ZeroDepth- The rate at which water is leaving the domain via zero-depth gradientboundaries.

• CritDepth- The rate at which water is leaving the domain via critical depth bound-aries.

• FreeDr- The rate at which water is leaving the domain via free drainage boundaries.

• NET1 Sources/Sinks The total rate of all water entering or leaving the domainthrough sources and sinks, ±Q.

The next section of the fluid balance information relates to the changes in storage thatoccurred in the various media. Column headings that could appear in this section are:

• PM Rate of accumulation in the porous medium.

• Overland Rate of accumulation in the overland flow domain.

• Dual Rate of accumulation in the dual continuum.

• Fracture Rate of accumulation in discrete fractures.

• Tiles Rate of accumulation in tile drains.

• Wells Rate of accumulation in wells.

• NET2 Accumulation The rate of change of storage for the entire domain ∆S.

In a perfectly balanced system the rate at which water enters or leaves the domain ±Q andthe rate of change in storage ∆S would be equal and the fluid balance error ε would be:

ε = ±Q−∆S = 0 (2.9)

The next section of the fluid balance information relates to the fluid balance error, whichcan be expressed in various ways:

• ERROR (NET1-NET2) The absolute error ε.

• Error rel The relative error εR:

εR = ε

(| ±Q|+ |∆S|)/2 (2.10)


• Error percent The percent error εP :

εP = |ε|Q>0

100 (2.11)

The final section of the fluid balance output gives the amount of water that has movedbetween the overland flow domain and the subsurface domain:

• Infilt The amount of water that has infiltrated the subsurface (i.e moved from overlandflow domain to subsurface domain).

• Exfilt The amount of water that has discharged from the subsurface (i.e moved fromthe subsurface domain to the overland flow domain).

2.10.3 Surface Flow Hydrographs

The following instructions affect the I/O for the surface flow solution.

Set hydrograph nodes1. label hyd Descriptive name for the hydrograph up to 80 characters.

Chosen nodes are flagged as hydrograph nodes, at which detailed total fluid flux [L3 T−1]information is output at each timestep. Output is written to a Tecplot formatted file calledprefixo.hydrograph.hydrograph.dat. For each timestep in the flow solution, one line willbe written to the file. Each line contains the time, surface domain flux, porous media fluxand total flux.

• • •

2.10.4 Transport

The following instructions affect the I/O for the transport solution.

Flux output nodes1. new noutfc Number of new output nodes desired.

2. ioutfc(i), i=1,new noutfc Flux output node number.

Listed nodes are flagged to generate detailed mass flux [M T−1] information to the fileprefixo.flm. For each timestep in the transport solution, one line per flux output node perspecies will be written to the file which contains the species number, node number, time,concentration, mass flux and nodal coordinates. Such output can be imported into an editor


(e.g. Microsoft Excel) and sorted by column to facilitate, for example, the creation of a plotof concentration or flux versus time for a given species at a node.

For an example which uses flux output nodes, see Section 4.5.1.• • •

Flux output nodes from chosenThis instruction works in a similar way to Flux output nodes except that all currently chosennodes are flagged as flux output nodes.

• • •

Flux volume output nodes1. fvol name Descriptive name for the volume up to 40 characters.

Chosen nodes are used to define a volume for which detailed mass flux information will bewritten to the Tecplot formatted file prefixo.mass entering volume.volume.species.dat,where the prefix, volume and species portions would be the user-defined prefix, volumename and species (i.e. solute) name respectively. For each timestep in the flow solution,one line will be written to the file. Each line contains the time, the average concentrationand instantaneous mass flux for all media (i.e. porous, dual, fractured or overland) and thecumulative mass flux for the volume.

Active nodes (the surface of the volume) and contributing nodes (just outside the surface ofthe volume) are defined automatically by searching for 3-D elements that contain a mixtureof chosen and unchosen nodes. For such elements, chosen nodes are flagged as active andunchosen nodes are flagged as contributing.

Mass fluxes reported for the volume are positive if mass is entering the volume and negativeif mass is leaving the volume.

• • •

In some cases, it may be necessary to restrict the computation of mass flux to a slice ofnodes. The following instructions can be used to do this:

Slice flux output nodes from chosen1. fvol name Descriptive name for the volume up to 40 characters.

This instruction works in a similar way to Flux volume output nodes except that all currentlychosen nodes are flagged as active nodes for the mass flux calculation.

• • •


The preceding instruction must be used in conjunction with the following instruction:

Slice flux contributing nodes from chosenThis instruction flags all currently chosen nodes as contributing nodes for the mass fluxcalculation. Note that grok checks that both instructions are issued in the correct orderand that there is at least one element that shares an active and contributing node.

• • •

Vertical slice flux by layer1. fvol name Descriptive name for the volume, up to 40 characters.

2. contributing name Name of contributing node set, up to 40 characters.

3. active name Name of active node set, up to 40 characters.

4. minlayer, maxlayer Minimum and maximum layers (inclusive), respectively.

This command is similar to the command combination Slice flux output nodes from chosenand Slice flux contributing nodes from chosen. For each node set (active or contributing) itgenerates a vertical slice over the input layer range (minlayer to maxlayer). The active andcontributing node sets should be generated by the command Create node set. Each node setis treated as a 2-D node set by projecting all nodes to the bottom sheet of the model. Themain difference with this command is that the contribution to the total mass flux by eachlayer in the porous media domain is written to the output file. Note that this commandapplies only to triangular prism or hexahedral block meshes.

• • •

Plot concentration penetration depth1. threshold conc Threshold concentration [M L−3].

This instruction causes HydroGeoSphere to write the distance from domain top tothe elevation of the threshold concentration contour versus time to a file called pre-fixo.penetration depth. This command is especially useful in conjunction with density-dependent flow simulations where the migration of a dense plume from the domain top intothe aquifer versus time is of interest.

• • •

Plot maximum velocityCauses HydroGeoSphere to write the maximum porous matrix velocity versus time to afile called prefixo.maxvel pm. If fractures are present, the additional file prefixo.maxvel fm


is created, containing the maximum fracture velocity versus time data.• • •

Compute statistical properties of plumeThis instruction causes HydroGeoSphere to write the statistical properties of solute plumein porous media at each time step (zeroth to fourth order moments). Output is written tothe file prefixo.Statistical Plume Props.dat.

• • •

2.10.4.1 Observation Wells and Points

The following instructions are used to output concentration at a single node or a group ofnodes lying on a line.

These instruction do not affect the transport solution.

Make observation point1. well name Descriptive name for the well up to 40 characters.

2. x1, y1, z1 xyz-coordinates of the observation point.

The node closest to this point will be flagged as an observation point node.

Output is written to a Tecplot formatted file called prefixo.observation well conc.-obs well name.dat. Data for each timestep in the flow solution is written as one line in theoutput file. Each line contains the time and porous medium concentration (and immobilezone concentration if dual porosity).

If the problem is formulated as a dual continuum then an extra column of output will bewritten with the dual continuum concentration. If the node is not a dual continuum node, ano data value (currently −999.0) will be written instead.

If the problem is formulated with a surface flow domain then an extra column of output willbe produced with the surface flow concentration. If the node is not a surface flow node, ano data value (currently −999.0) will be written instead.

The line ends with the node coordinates and number.• • •

Make observation well1. well name Descriptive name for the well up to 40 characters.


2. x1, y1, z1 xyz-coordinates of one end of the observation well.

3. x2, y2, z2 xyz-coordinates of the other end of the observation well.

Element face edges (i.e. segments) which form the shortest path between the two nodesclosest to the end points of the well (i.e. (x1, y1, z1) and (x2, y2, z2)) will be chosen toproduce output.

Output is written to a Tecplot formatted file called prefixo.observation well flow.-obs well name.dat. Each timestep in the flow solution represents a Tecplot zone in theoutput file, and each zone contains one line per observation well node. Each line containsthe porous medium concentration (and immobile zone concentration if dual-porosity).

If the problem is formulated as a dual continuum then an extra column of output will bewritten with the dual continuum concentration. If the node is not a dual continuum node, ano data value (currently −999.0) will be written instead.

If the problem is formulated with a surface flow domain then an extra column of output willbe produced with the surface flow concentration. If the node is not a surface flow node, ano data value (currently −999.0) will be written instead.

The line ends with the node coordinates and number.• • •

2.10.4.2 Solute Mass Balance

By default, solute mass balance information for each species is computed at each time stepand written to the prefixo.lst file. Figure 2.18 illustrates some sample output as it appearsin the .lst file.

**********************************************************************************MASS BALANCE SPECIES 1 - Uranium**********************************************************************************

(Time = 1999.00999999978 Time-step = 9.999999776482582E-003 )RATE OF MASS EXCHANGE IN OUTTOTAL

Fixed head nodes 100.0000006818 0.0000000000Fixed concentration nodes 150.0985515732 0.0000000000NET1 EXCHANGE RATE (IN-OUT) 250.0985522550

MASS ACCUMULATION COMPONENT SUBTOTALIn storage:

Porous medium 2.5001748233Porous medium (sorbed) 35749.9997988755

ACCUMULATED 35752.4999736989Lost by decay:

Porous medium 0.0000000708Porous medium (sorbed) 0.0010116896


DECAYED 0.0010117604EXCHANGED (via chemical reactions) 0.0000000000INITIAL (stored at start of timestep) 35750.0000000000NET2 RATE OF ACCUMULATION 250.0985515100

i.e. (ACCUMULATED -DECAYED +(-)EXCHANGED -INITIAL)/delta

NET (since start of simulation) 250.0985515100

MASS BALANCE ERRORAbsolute: (NET1-NET2) 0.0000007450Relative: (NET1-NET2)/(abs(NET1)+abs(NET2))/2.0 0.0000000015

**********************************************************************************

Figure 2.18: Example of solute mass balance information written to file prefixo.lst.

No solute mass balanceThis instruction prevents solute mass balance information from being written to the listingfile.

• • •

This detailed mass balance information is also written to a Tecplot formatted ASCII outputfile called, for example, prefixo.mass balance species 001 so that it can be easily visualized.

Summary mass balance information is written to a Tecplot formatted ASCII output filecalled, for example, prefixo.mass balance summary so that it can be easily visualized. Foreach timestep in the transport solution, one line per species is written to the file. Each linehas seven columns labelled as follows:

1. time Simulation time.

2. Tmass Total mass in the system.

3. dBoundary Change in mass due to sources and sinks.

4. dStored Change in mass stored.

5. dBoundary - dStored Error.

6. (dBoundary - dStored)/Tmass*100) Normalized error.

7. Species Species number.

Besides being plotted with Tecplot, such output can be imported into an editor (e.g. MicrosoftExcel) and sorted to facilitate, for example, the creation of a plot of mass balance errorversus time for a given species.

Cumulative mass balance information is written to a Tecplot formatted ASCII output filecalled, for example, prefixo.mass balance cumulative so that it can be easily visualized.


For each timestep in the transport solution, one line per species is written to the file. Eachline has seven columns labelled as follows:

1. time Simulation time.

2. In (cumulative) Mass in since start of simulation.

3. Out (cumulative) Mass out since start of simulation.

4. Stored Change in mass stored since start of simulation.

5. In+Out-Stored Error.

6. Species Species number.

Besides being plotted with Tecplot, such output can be imported into an editor (e.g. MicrosoftExcel) and sorted to facilitate, for example, the creation of a plot of mass balance errorversus time for a given species.

2.10.4.3 Travel Time Probability

Output travel time statisticsHydroGeoSphere will perform descriptive statistics, following Eqs. (2.163) and (2.164).Mean travel time, mode, and standard deviation will be calculated at each node/element.

• • •

Integrate production zone1. fname Name of the file which contains the list of elements that contain a mass source

function and the tabulated functions. It is formatted as follows:

(a) nprodel Number of production elements. Read the following nprodel times:i. nel, ifunc The element number and the ID (number) of the associated

tabulated function.(b) maxdatprod, delta conv Size of the largest set of tabulated data which follows

and the timestep size delta conv for evaluating the convolution integral inEquation 2.12. Read the following for each of the ifunc time-series:

i. ndata Number of data to read for the current time-series.ii. time, val Time and corresponding source value.

If ifunc = 0, then m∗ corresponds to a unit and instantaneous mass input function, andthus no time-series are required in the input file.


The element nel with the maximum value of ifunc determines how many sets of time-seriesdata must be supplied.

This option is meant to simulate a forward transport solution by means of a backwardsolution. It requires the problem to be backward-in-time. Integration of the backwardtravel time PDFs will be performed over a series of element numbers, which are input inthe .np file. In a forward transport run, these elements would contain a mass source m∗.The following equation is solved at each time-step in order to simulate the output mass fluxJO(t) resulting from a forward transport (see [Cornaton, 2003]):

JO(t) =∫

∆

∫ t

0gt(t− u,x)m∗(x, u) du dΩ (2.12)

if m∗ is an arbitrary mass source function [M L−3 T−1], or

JO(t) =∫

∆gt(t,x)δ(x− xi) dΩ (2.13)

if m∗ is a unit and instantaneous mass input function [L−3 T−1]. ∆ denotes the domain ofelements where m∗(x, t) 6= 0.

• • •

References

Canadell, J., R.B. Jackson, J.R. Ehrlinger, H.A. Mooney, O.E. Sala, and E.D. Schulze,1996. Maximum rooting depth of vegetation types at the global scale, Oecologia,108:583–595.

Cooley, R.L., 1983. Some new procedures for numerical simulation of variably-saturatedflow problems, Water Resour. Res., 19(5):1271–1285.

Cornaton, F., 2003. Deterministic models of groundwater age, life expectancy and tran-sit time distributions in advective-dispersive systems. Ph.D. Thesis, University ofNeuchatel, Neuchatel, Switzerland.

Huyakorn, P.S., Y.S. Wu, and N.S. Park, 1994. An improved sharp-interface model forassessing NAPL contamination and remediation of groundwater systems, Journal ofContaminant Hydrology, 16:203–234.

Letniowski, F.W. and P.A. Forsyth, 1991. A control volume finite element method forthree-dimensional NAPL groundwater contamination, Int. J. Num. Meth. Fluids,13(8):955–970.

Oswald, S.E. and W. Kinzelbach, 2004. Three-dimensional physical benchmark experimentsto test variable-density flow models, J. Hydrol., 290:22–42.

Robin, M.J.L., A.L. Gutjahr, E.A. Sudicky, and J.L. Wilson, 1993. Cross-correlatedrandom field generation with the direct Fourier Transform method, Water Resour.Res., 29(7):2385–2397.

Scurlock, J.M.O., G.P. Asner, and S.T. Gower, 2001. Worldwide Historical Estimates ofLeaf Area Index, 1932–2000, prepared for the Oak Ridge National Laboratory, OakRidge, Tennessee. ORNL/TM-2001/268.

Wang, J.S.Y. and T.N. Narasimhan, 1985. Hydrologic mechanisms governing fluid flow in apartially saturated, fractured, porous medium, Water Resour. Res., 21(12):1861–1874.

265

Appendix A

Output Files

Unless otherwise stated, the files described in this section are ASCII formatted.

These general use files are created by grok during execution:

array sizes.defaultSee Section 2.1.3.1 in the reference manual.

grok.dbgGeneral purpose output file for debugging information.

These scratch files are usually created when grok scans input files and removes commentsand blank lines:

scratch grokCleaned up copy of prefix.grok file.

scratch dpropsCleaned up copy of .dprops file.

scratch fpropsCleaned up copy of .fprops file.

scratch mpropsCleaned up copy of .mprops file.

scratch opropsCleaned up copy of .oprops file.

scratch etpropsCleaned up copy of .etprops file.

266

APPENDIX A. OUTPUT FILES 267

scratch cpropsCleaned up copy of .cprops file.

scratch WellPropsCleaned up copy of well properties file.

scratch TilePropsCleaned up copy of tile properties file.

fractran2f3d.lstListing file created if Read fractran 2d grid is used.

These files are created by grok as data for a specific problem is processed. Most are binaryfiles that are read later by HydroGeoSphere:

prefixo.ecogrok listing file.

prefixo.genGeneral input data (binary).

prefixo.coordinates3-D subsurface mesh node coordinates (binary).

prefixo.coordinates overland2-D surface flow mesh node coordinates if dual approach used (binary).

prefixo.elements3-D subsurface mesh porous media element node lists (binary).

prefixo.elements dual3-D subsurface mesh dual continua element node lists (binary).

prefixo.elements overland2-D surface flow mesh element node lists if dual approach used (binary).

prefixo.elements fracture2-D discrete fracture element node lists (binary).

prefixo.fac3-D subsurface mesh face node lists (binary).

prefixo.seg3-D subsurface mesh segment node lists (binary).


prefixo.speciesSpecies (i.e. solute) data (binary).

prefixo.hiInitial nodal heads (binary).

prefixo.ciInitial nodal concentrations (binary).

prefixo.sizArray size data determined by grok and used by HydroGeoSpherefor run-time array allocation.

These files are created by grok if the 2-D Random Fracture Generator, as described inSection 2.3.4 is used:

prefixo.rfrac.fracturesListing file with fracture zone information.

prefixo.rfrac.aperturesListing file with fracture aperture information.

prefixo.rfrac.lengthsListing file with fracture length information.

prefixo.rfrac.orientationsListing file with fracture orientation information.

This general use file is created by HydroGeoSphere during execution:

hs.dbgGeneral purpose output file for debugging information.

These files are created by HydroGeoSphere for use with the Run-Time Debug Utilitydescribed in Appendix B:

debug.controlYou can edit this file to change the run-time debug behaviour.

scratch debugCleaned up copy of debug.control file.

progress.datTecplot formatted file of CPU time vs system time.


These files are created by HydroGeoSphere for a specific problem as the simulationprogresses:

prefixo.lstHydroGeoSphere listing file.

prefixo.satElemental saturation (binary).

prefixo.henFinal heads for restart (binary).

prefixo.cenFinal concentrations for restart (binary).

prefixo.balMass balance information (binary).

prefixo.velPorous medium elemental velocity (binary).

prefixo.water balance.datFluid mass balance summary for each timestep.

prefixo.mass balance cumulative.species.datCumulative solute mass balance for each timestep.

prefixo.mass balance summary.species.datSolute mass balance summary for each timestep.

prefixo.mass crossing sliceMass crossing a slice if Slice flux output used.

prefixo.mass balance rawspecies.datMass balance information for each timestep for a species.

prefixo.observation well flow.well.datObservation well/point flow solution output.

prefixo.fluFluid flux if Flux output nodes used.

prefixo.flu bFluid flux if Binary flux output nodes used (binary).


prefixo.river fluxFluid flux if Make river nodes used.

prefixo.drain fluxFluid flux if Make drain nodes used.

prefixo.hydrograph.hydrograph.datTotal flux for each timestep for a set of hydrograph nodes.

prefixo.wvoElemental velocity in wells.

prefixo.observation well conc.well.species.datConcentration at observation wells.

prefixo.flmMass flux if Flux output nodes used.

prefixo.flm bMass flux if Binary flux output nodes used (binary).

prefixo.mf interpInterpolated mass flux if used.

These files may be created by HydroGeoSphere for a specific problem for each outputtime, in this case number 0001, as the run progresses:

prefixo.head.0001Porous medium head.

prefixo.saturation.0001Porous medium saturation.

prefixo.concentration.species.0001Porous medium concentration.

prefixo.immobile concentration.species.0001Porous medium immobile zone concentration.

prefixo.velocity linear.0001Porous medium average linear groundwater velocity.

prefixo.velocity darcy.0001Porous medium Darcy velocity.


prefixo.head dual.0001Dual continuum head.

prefixo.saturation dual.0001Dual continuum saturation.

prefixo.concentration dual.species.0001Dual continuum concentration.

prefixo.velocity linear dual.0001Dual continuum average linear groundwater velocity.

prefixo.velocity darcy dual.0001Dual continuum Darcy velocity.

prefixo.head overland.0001Surface flow head.

prefixo.velocity overland.0001Surface flow velocity.

prefixo.exchange flux.0001Surface/subsurface exchange flux.

prefixo.et pm evap.0001Subsurface evaporation flux.

prefixo.et pm trans.0001Subsurface transpiration flux.

prefixo.et surf evap.0001Surface evaporation flux.

prefixo.et tot.0001Total evapotranspiration flux.

prefixo.fracture aperture.0001Discrete fracture aperture.

prefixo.velocity linear fracture.0001Discrete fracture average linear groundwater velocity.

prefixo.velocity darcy fracture.0001Discrete fracture Darcy velocity.

Appendix B

Run-Time Debug Utility

When using HydroGeoSphere to solve complex problems, especially non-linear ones, it isoften the case that the end user would like to, for example, view intermediate results, modifyinput parameters or print out the contents of various matrices. Normally, the programdeveloper would carry out such tasks with the aid of a debugger, which is normally suppliedas part of a program development package. Unfortunately, most end users do not haveaccess to such a package, and even if they did, running a code which has been compiled indebug mode is generally much slower than when it has been optimized for release to thepublic.

In order to address some of these problems, we have developed a run-time debug utilitywhich operates on the optimized HydroGeoSphere executable and is able to be activatedand deactivated interactively without halting the execution of the program.

At various points during program execution, HydroGeoSphere checks for the presenceof a file called debug.control in the same directory as the prefix.grok file and, if found,performs certain actions as indicated in the file. If it is not found, a file will be createdwhich contains instructions for performing run-time debug actions.

If you want to prevent HydroGeoSphere from performing run-time debugging (includingchecking the debug control file), you can do so using the instruction No runtime debug.

The head and tail of the debug.control file are shown in Table B.1.

debug off! ------------------------------------- Pause execution! pause timestep! pause at time! 10000.00000! pause flow convergence loop! ------------------------------------- Produce output! write output files! write saturated flow matrices

272

APPENDIX B. RUN-TIME DEBUG UTILITY 273

...etc...

! ------------------------------------- Adaptive timestep targets! concentration change target! 0.05000! mass change target! 0.10000E+21! mass error target! 100.00000! minimum timestep multiplier! 0.50000! maximum timestep multiplier! 2.00000

Figure B.1: Sample contents of debug.control file.

Lines beginning with the comment character (!) are ignored. When first generated, theonly uncommented line is the first one, debug off, which causes HydroGeoSphere torun normally, and not to take any run-time debug actions.

The contents of the file depend on the nature of the problem which is being simulated. Forexample, if it has no transport component there will not be any transport-related informationwritten to the file.

To activate the debug utility, just comment out the debug off instruction, and uncommentone or more of the remaining instructions as desired.

For example, if you modified and saved debug.control so it appeared as shown in Table B.2

!debug off! ------------------------------------- Pause executionpause timestep

...etc...

Figure B.2: Modified debug.control file.

then HydroGeoSphere would pause at the end of the next timestep.

Note that if the debug control file becomes corrupted, or if you modify the problem insome way (e.g. activate transport) you can automatically generate a fresh copy by deletingor renaming it before or during HydroGeoSphere execution.

The effect caused by uncommenting the various instructions in the debug.control file willnow be described, and input data requirements will be discussed as required.

Debug off


Ignore the rest of the contents of the debug control file, whether or not they are uncom-mented. To activate the run-time debug feature, this line should be commented out.

• • •

Pause timestepPause at the beginning of the next timestep and issue the following message on the screen:

DEBUG CONTROL: pause timestep, press a key to continue

This command is usually used to prevent other instructions, such as Write output files, fromproducing too much output.

• • •

Pause at time1. time Simulation time [T].

Proceed until the given simulation time is reached and then pause.• • •

Pause newton loopPause at the beginning of the next Newton iteration.

• • •

Pause flow convergence loopPause at the beginning of the next flow solver iteration.

• • •

Write output filesTreat each timestep as if it was defined in the prefix.grok file as an output time (i.e. usingthe instruction Output times). Head, concentration, saturation, etc. output files will bewritten at each timestep. This instruction is usually used in conjunction with Pause timestep.

• • •

Watch node list...end


1. node(i)...end Node number list.

A list of node numbers for which you want detailed output.• • •

For each watch node, the following instructions write detailed output to the hs.dbg file:

Write flow matricesWrite transport matricesWrite overland flowWrite fracture (dual node) flowWrite evapotranspiration

Detailed output usually consists of the coefficient matrix and right-hand side vector for thewatch node.

In the case of the Write evapotranspiration instruction, the quantities of fluid that are removedby the various process (e.g. canopy evaporation, evaporation, transpiration, etc.) and theremaining potential evapotranspiration are printed out at each timestep.

When using a feature such as Write flow matrices for example, be aware that Hydro-GeoSphere may write a lot of information to disk, and so they should be activated anddeactivated for only a few timesteps at a time.

Write delval node infoDetailed information, including xyz-coordinate, head, saturation, and relative permeability,for the node corresponding to the absolute maximum value of the linear solve solution(delval) at each timestep is written to the .lst file.

• • •

Write resval node infoDetailed information, including xyz-coordinate, head, saturation and relative permeability,for the node corresponding to the absolute maximum value of the Newton residual (resval)at each timestep is written to the .lst file.

• • •

Write seepage face output to .lst fileDetails of the seepage node calculations, including which nodes are currently acting asseepage nodes and the fluid flux exiting the domain at each active seepage node are writtento the .lst file.

• • •


Time progressCauses FRAC3DVS to write a Tecplot file which contains values of simulation time versusreal time. The slope of this line is a measure of how efficient an HydroGeoSphere is,and can be used to gauge how effective changes in parameter values are in speeding up thesimulation. The first time this instruction is executed, the file progress.dat is created,and data is written to it as the run progresses. The results for a given simulation are taggedwith a date and timestamp. Results from subsequent are appended to the file so they canbe compared from run to run.

• • •

Write krw file1. fname Name of the file to write the hydraulic conductivity values.

For each principal direction and for each element, outputs the product of the relativepermeability and the saturated hydraulic conductivity to the file fname. This file can thenbe read in a subsequent simulation using the instruction Read elemental k from file.

• • •

Time format1. type An integer value indicating the type of format to use when writing time values

to output files. Acceptable values are:

1 Fixed.2 Scientific.3 General.

• • •

Mass balance formatAs above except for mass balance output.

• • •

Nodal flow check1. flow check If true, this logical switch turns on the nodal flow check feature, otherwise,

it turns it off.• • •


Force timestep1. delta t Timestep [T].

Subsequent timesteps will be set to this value.• • •

The following commands are identical to those used in the .grok input file and will just belisted here. They are used to modify parameter values while HydroGeoSphere is running.Note that if you change a parameter here, HydroGeoSphere will continue to use the newvalue even if you disable run-time debugging (i.e. uncomment instruction Debug off) orcomment out the instruction that was used to change the value.

Flow solver convergence criteriaFlow solver detailFlow maximum iterationsTransport solver convergence criteriaTransport solver detailTransport solver maximum iterationsNewton maximum iterationsNewton absolute convergence criteriaNewton residual convergence criteriaCompute underrelaxation factorNodal flow check toleranceNewton maximum update for headNewton maximum update for depthNewton absolute maximum residualNewton maximum residual increaseMaximum timestepMinimum timestep multiplierMaximum timestep multiplier

The following commands can be used to set the values of the various targets used in theadaptive timestepping procedure.

Head change targetSaturation change targetWater depth change targetNewton targetConcentration change targetMass change targetMass error target

Appendix C

Run-Time Timestep Output

In this section we discuss the run-time output produced by HGS at each timestep whencomputing the flow solution. This information is useful for tracking the progress andconvergence behaviour of the simulation as well as for diagnosing and remedying any poorperformance issues. Before we dig in, a brief overview of the solution process in HGS willaide our discussion. At each timestep, HGS employs the Newton–Raphson iterative schemeto solve the nonlinear equations that arise from discretizing the flow equations. If we denotethe solution vector by x (typically pressure head), then the nonlinear equations being solvedcan be expressed as F (x) = 0. In its most basic form, the Newton–Raphson iterative schemefor solving F (x) = 0 can be written as follows.

1: Set the initial guess for x2: while not converged do3: Build the Jacobian matrix J ← F ′(x) and Newton residual r ← F (x)4: Solve the linear system Js = −r for the Newton step vector s5: Update the relaxation factor λ (if using), otherwise λ← 16: Update the solution: x← x+ λ · s7: Check for convergence: ‖s‖∞ ≤ τ or ‖r‖∞ ≤ ε8: end while

We will use the symbols and steps defined here when discussing the run-time output.

The screen capture illustrated in Figure C.1 shows the run-time timestep output producedby HGS when running the Abdul verification problem. The output consists of three sections:simulation progress, summary of the nonlinear iteration, and the adaptive timesteppingupdate. We will discuss each of these sections in detail.

278

APPENDIX C. RUN-TIME TIMESTEP OUTPUT 279

Figure C.1: Run-time timestep output for the Abdul verification problem.

C.1 Simulation Progress

• Global Target Time: This is the next target time that HGS is working toward. Inthe brackets () we can see that it is the third such target time out of nine total.

• %done: The percentage of the simulation completed as measured from the initialstart time to the previous successful simulation time. Note that the final target timeis used as the end time of the simulation.

• Time: The previous successful simulation time.

• delta t: The distance between the previous successful simulation time and the simu-lation time that is currently being computed.

• Tnext: The simulation time at which the solution is currently being computed.

C.2 Summary of the Nonlinear Iteration

• Iter: The iteration number of the nonlinear solve step.

• Relfac: The underrelaxation factor λ for the Newton iteration.


• Delval: The element of the Newton step vector s that gives the absolute maximumvalue, i.e., arg maxi |si|.

• @Node: The index at which the absolute maximum occurs.

• NcNode: The number of elements for which |si| > τ (see the command Newtonabsolute convergence criteria).

• Resval: The element of the Newton residual vector r that gives the absolute maximumvalue, i.e., arg maxi |ri|.

• @Node: The index at which the absolute maximum occurs.

• NcNode: The number of elements for which |ri| > ε (see the command Newtonresidual convergence criteria).

• Solv: The linear system Js = −r is solved approximately via an iterative solver, bydefault, BiCGStab. This value is the number of iterations required by the linear solveto satisfy its convergence criteria (see the commands Flow solver convergence criteriaand Flow solver maximum iterations).

• Dom: The domains at which Delval and Resval are achieved, respectively.

The final lines of this section indicate that convergence was achieved after two iterations ofthe nonlinear solver. It shows the values of Delval and Resval, and their correspondingconvergence tolerances. Note that only one such convergence criterion needs to be satisfied.

C.3 Adaptive Timestep Update

• Variable: The quantity being tracked (i.e., head, water depth, saturation, and numberof nonlinear solver iterations).

• Max. change: The absolute maximum difference in the specified quantity betweenthe last successful simulation time and the one being computed.

• Target change: The targeted or expected change in the specified quantity over asingle timestep as specified in the debug.control file (see Appendix B). For example,in the case of head, it would be the command Head change target.

• Dt multiplier: The ratio of Max. change to Target change for the specifiedquantity.

• At node: The index at which the maximum absolute difference occurs.

At the end of the timestep output it indicates that the solution at time Tnext was accepted.It then shows how the next timestep is computed. The timestep multiplier, αt, is definedas the minimum of all the Dt multiplier values, restricted to the interval [αt,min, αt,max]


(see commands Minimum timestep multiplier and Maximum timestep multiplier). The nexttimestep, ∆tnew, is then computed from the previous timestep, ∆t, according to the formula:

∆tnew = max (min(αt ·∆t, ∆tmax), ∆tmin)

The minimum and maximum timesteps can be set by the commands Minimum timestep andMaximum timestep, respectively.

Appendix D

HSBATCH: Batch Run Utility

A common requirement of a computer program is that it be able to run several differentproblems in sequence, hopefully without user intervention. For example, a Monte Carloapproach could require the user to do several hundred runs with slightly varying data orparameter sets, or a developer might want to execute a suite of verification runs with eachnew release of the software.

With HydroGeoSphere you have the capability to carry out multiple batch runs by usingthe program HSBATCH. To meet our own requirements, we have set up the verificationexamples for HydroGeoSphere to be run in batch mode, and the end user can easily adaptthe approach to meet their own requirements.

The first step in setting up batch runs is to create directories that contain all of the datafiles necessary to run the simulations. In the case of the HydroGeoSphere verificationproblems, the verification directory nested under the HydroGeoSphere installationdirectory (C:\Program Files\HydroGeoSphere\verification on Windows) contains oneor more subdirectories for each verification problem. A partial list of its contents are shownhere:

Directory of C:\program_files\HydroGeoSphere\verification

16/05/2006 11:47 AM <DIR> .16/05/2006 11:47 AM <DIR> ..16/05/2006 11:33 AM <DIR> abdul16/05/2006 11:01 AM <DIR> digiammarco16/05/2006 11:08 AM <DIR> dual...etc...16/05/2006 11:05 AM <DIR> ward16/05/2006 11:05 AM <DIR> yang16/05/2006 10:50 AM 1,025 dev_path.hsbatch16/05/2006 10:50 AM 403 install.hsbatch

282

APPENDIX D. HSBATCH: BATCH RUN UTILITY 283

First, a file with the extension .hsbatch is set up to run the desired suite of batch problems.In this case we called it install.hsbatch, and here is a partial listing of its contents:

! HydroGeoSphere batch processor input file

! verification problemsbatch directory listdigiammarcodualf_cd

...etc...

smith_woolhiserpandaysaltpool1!elderend

The file can contain comments, which begin with an exclamation point (!), blank lines, andInclude instructions.

The instruction Batch directory list is followed by a list of subdirectories, one per line, thatcontain the problem data to be run in batch mode, followed by an End instruction. Eachsubdirectory should contain one set of problem data, and in order for the executables torun without prompting the user for the problem prefix, it is necessary to create a file calledbatch.pfx that consists of a single line containing the problem prefix, in each problemdirectory.

This example shows the simplest configuration that an .hsbatch file can have, in which it usesdefault locations for both the executables and the problem data. Executables in Windows arefound by searching the default search path, which should contain C:\Program Files\HydroGeoSpherefollowing a typical program installation. Problem data are to be found in subdirectories of thedirectory where the .hsbatch file is located, in this case C:\Program Files\HydroGeoSphere\verification.

To run HSBATCH for this example, open a command prompt, change directories toC:\Program Files\HydroGeoSphere\verification, and type:

hsbatch

You will see the program banner. Next, supply the .hsbatch file prefix, in this case:

install

As the program runs, output from grok, HydroGeoSphere, and HSPLOT are echoed to


the screen. A log of the HSBATCH process, including program run times, is written tothe file prefixo.eco hsbatch.

A more complex situation could be one in which a user wants to use a set of executablesthat are not in the default search path, or problem data from more than one directory. Thefile dev path.hsbatch illustrates how to handle these types of situations:

! HydroGeoSphere batch processor input file!! If you use this file without hardwiring paths to the executables,! it will use the ones it finds in the default search path.

! NOTE: always use an absolute path e.g. c:\program_files\hydrogeosphere\! and not relative e.g. ..\grok\release\

grok pathc:\program_files\hydrogeosphere\

hydrogeosphere pathc:\program_files\hydrogeosphere\

hsplot pathc:\program_files\hydrogeosphere\

! If you use this file without hardwiring the path to the data parent! directory, it will use the .hsbatch file directory as the parent.

! First run a verification problemchange directoryc:\program_files\hydrogeosphere\verification

batch directory listpm_cdend

! Now run an illustrative problemchange directoryc:\program_files\hydrogeosphere\illustration

batch directory listreactive_iron_barrier_in_fracturesend

In this case, the instructions Grok path, Hydrogeosphere path and Hsplot path point to the


locations where the program executables can be found. The command Change directory setsthe parent directory to apply to all subdirectories listed in the subsequent Batch directorylist. As you can see, the file can contain multiple sets of Change directory and Batch directorylist instructions. In this case, the location of the .hsbatch file is not critical, since absolutepaths to the problem data are supplied.

Appendix E

HSPLOT: VisualizationPost-Processor

The utility program HSPLOT can be used to convert raw HydroGeoSphere output intofiles that are compatible with third-party visualization packages.

Like grok and HydroGeoSphere, when HSPLOT starts executing, it requires a problemprefix that can be entered interactively from the keyboard or supplied via the batch.pfxfile.

The first time you run HSPLOT for a specific problem, it creates the plot control file,prefix.plot.control, which contains a list of instructions that affect the output file formatand contents. Note that if the plot control file becomes corrupted you can automaticallygenerate a fresh copy by deleting or renaming it before executing HSPLOT.

We will now discuss the various sections of the plot control file and how they can be modifiedto produce the desired outputs.

E.1 Output Format Modes

Currently, HSPLOT supports Tecplot and Paraview output formats. The first two lines ofthe plot control file are:

tecplot mode! paraview mode

Lines beginning with the comment character (!) are ignored, and so by default, the file is setup to generate Tecplot formatted output (i.e. Tecplot mode instruction is uncommented).Uncommenting one of these two instructions has the following effect:

Tecplot mode

286

APPENDIX E. HSPLOT: VISUALIZATION POST-PROCESSOR 287

Causes HSPLOT to generate Tecplot formatted output.• • •

Paraview modeCauses HSPLOT to generate Paraview formatted output.

• • •

E.2 Porous Media Output

The next section of the plot control file controls the output of porous media (i.e. 3-D domain)data:

write 3d domain file! no 3d heads! no 3d linear velocities (vx, vy, vz)! no 3d darcy velocities (vx, vy, vz)! no elemental hydraulic conductivity! no elemental porosity! isolate node! 1 ! node number! 0 ! extension factor! truncate 3d domain! -0.10000000E+21 0.10000000E+21! -0.10000000E+21 0.10000000E+21! -0.10000000E+21 0.10000000E+21! truncate time domain! -0.10000000E+21 0.10000000E+21! ----------------------------

This section begins with a general instruction that controls whether or not porous mediaoutput is written, followed by a group of instructions that can be used to tailor the porousmedia output.

Write 3d domain fileCauses HSPLOT to write the output files for the porous media domain. The defaultTecplot formatted output file would contain all available data (i.e. heads, saturations,concentrations, velocities, etc.) at each output time and for the entire 3-D domain andwould be named:

prefixo.dat All data


• • •

The following instructions prevent HSPLOT from writing the named variables to theoutput file:

No 3d headsNo 3d saturationsNo 3d compactionNo 3d linear velocities (vx, vy, vz)No 3d darcy velocities (qx, qy, qz)No 3d concentrationsNo 3d immobile zone concentrationsNo 3d fracture aperturesNo permafrostNo elemental hydraulic conductivityNo elemental hydraulic conductivity dualNo elemental porosityNo elemental specific storageNo elemental tortuosityNo elemental peclet numbers

Note that the presence of the instructions listed above can be dependent on the nature ofthe simulation. For example, saturations would not have been written unless the system isvariably-saturated, and the No 3d saturations instruction would not then appear in the plotcontrol file.

Truncate 3d domain1. x1, x2 x-range of the domain.



Causes HSPLOT to restrict the output domain size to within the given xyz-ranges. Thiscommand is used to zero in on an interesting subregion of the 3-D domain or to reduce thesize of the output file and speed up file I/O.

• • •

For example, the following instructions:

truncate 3d domain100.0 200.00.0 1000.0-0.10000000E+21 0.10000000E+21


would reduce the domain size to the x-range from 100 to 200, the y-range from 0 to 1000,but would leave the z-range at its full extent.

Isolate node1. NodeNumber Number of node to be isolated.

2. ExtensionFactor An integer with a value of zero or greater.

Causes HSPLOT to restrict the output domain so that only elements that contain Node-Number are plotted (ExtensionFactor = 0). Increasing ExtensionFactor causes neigh-bouring elements to be plotted as well. For example, ExtensionFactor = 1 would beused to include elements that share a node with an element that contains NodeNumber.

• • •

Truncate time domain1. t1, t2 Time range [T] of the domain.

Causes HSPLOT to restrict the time range of the output so that only output times thatare between times t1 and t2 (inclusive) are included. Note that the first output time isalways included.

• • •

Compare heads 3d domain1. x1, x2 x-range of the domain.



Causes HSPLOT to write a Tecplot formatted output file called prefixo.compare heads.datthat contains simulated versus observed head data. Only head data that falls within therestricted region defined by the xyz-ranges is included. Note that this instruction will onlybe present in the plot control file if an observed head data file called prefix.observed headsis present in the directory with the prefix.grok file.

• • •

The file prefix.observed heads should be of the following form:

12558.29842E+05 2.41079E+06 2.85000E+02 2.85000E+028.34476E+05 2.39450E+06 2.86900E+02 2.95100E+02...etc.


where the first line is the number of observed head points in the file, followed by one linefor each point that contains the xyz-coordinates and observed head value at each point.

Plot pm depth below ground surfaceCauses HSPLOT to generate a Tecplot formatted output file prefixo.pm DepthToSurf.datof nodal depth below ground surface.

• • •

E.3 Dual Continuum Output

The following instructions affect how HSPLOT handles the output for the dual continuumdomain:

Write dual-permeability results to 3d domain fileCauses HSPLOT to write the dual-permeability results to the 3-D domain output file.Although it is not necessary to define all porous media elements as dual continuum elements,HydroGeoSphere treats the dual continuum output as being the same size as the porousmedium, and uses missing values (heads, saturations, and concentrations = −9999, zonenumber = 0) to designate regions where the dual continuum is absent. These values can beused to blank dual continuum output in Tecplot.

• • •


No 3d dual-permeability headsNo 3d dual-permeability saturationsNo 3d dual-permeability linear velocities (vx dual, vy dual, vz dual)No 3d dual-permeability darcy velocities (qx dual, qy dual, qz dual)No 3d dual-permeability concentrations

Note that the presence of the instructions listed above can be dependent on the nature ofthe simulation.

E.4 Discrete Fracture Output

The following instructions affect how HSPLOT handles the output for the discrete fracturedomain:

Write fracture domain file


Causes HSPLOT to write the output files for the discrete fracture domain. The defaultTecplot formatted output file would contain all available data (i.e. heads, saturations,concentrations, velocities, etc.) at each output time and for the entire fracture domain andwould be named:

prefixo.fracture.dat All data

When using the common node approach, the full set of nodal output is written to the outputfile along with the 2-D fracture element data. In the dual-node approach, only the fracturenode data and elements are written to the file.

• • •

These instructions have similar effects as those described above for porous media output:

Truncate fracture domainTruncate fracture time domain


No fracture headsNo fracture linear velocities (vx, vy, vz)No fracture darcy velocities (vx, vy, vz)No fracture concentrationsNo fracture/subsurface solute exchange fluxNo fracture immobile zone concentrationsNo fracture apertures

Note that the presence of the instructions listed above can be dependent on the nature ofthe simulation. The following instruction is written in the plot control file at the end of theporous medium section if the common node approach is used:

Write fracture elements to 3d domain fileCauses HSPLOT to append the fracture element data to the 3-D domain output fileprefixo.dat. This command causes fractures to appear as shown in Figure E.1.

• • •

E.5 Surface Flow Output

The following instructions affect how HSPLOT handles the output for the surface flowdomain:

Write surface flow domain file


Causes HSPLOT to write the output files for the surface flow domain.

The default Tecplot formatted output file would contain all available data (i.e. heads, depth,concentrations, velocities, etc.) at each output time and for the entire surface flow domainand would be named:

prefixo.overland.dat All data

• • •

These instructions have similar effects as those described above for porous media output:

Truncate surface flow domainTruncate surface time domain


No surface flow headsNo surface log10(depth)No surface flow linear velocities (vx, vy, vz)No etNo surface flow concentrationsNo surface/subsurface exchange fluxNo surface/subsurface solute exchange

Note that the presence of the instructions listed above can be dependent on the nature ofthe simulation.


Figure E.1: Example output of instruction Write fracture elements to 3d domain file.

Appendix F

Raster File Formats

Raster data consists of a set of values that are laid out on a rectangular grid with uniformspacing in the x- and y-directions. The raster coordinates need not coincide with grok meshnodes and can even fall outside the model domain.

The raster must consist of header information containing a set of keywords, followed by cellvalues in row-major order. The file format is based on the ArcGIS ASCII file conventionsand must consist of the following:

NCOLS xxxNROWS xxxXLLCORNER xxxYLLCORNER xxxCELLSIZE xxxNODATA_VALUE xxxrow 1row 2...row n

where NCOLS and NROWS are the number of rows and columns in the raster respectively,XLLCORNER and YLLCORNER are the x- and y-coordinates of the lower left corner of theraster, CELLSIZE is the size of each raster cell, NODATA VALUE is the value in the ASCII filerepresenting cells whose true value is unknown (i.e. missing) and xxx is a number. Row 1of the data is at the top of the grid, row 2 is just under row 1, and so on. For example:

ncols 480nrows 450xllcorner 378923yllcorner 4072345

294

APPENDIX F. RASTER FILE FORMATS 295

cellsize 30nodata_value -3276843 2 45 7 3 56 2 5 23 65 34 6 32 54 57 34 2 2 54 635 45 65 34 2 6 78 4 2 6 89 3 2 7 45 23 5 8 4 1 62 ...

Cell values should be delimited by spaces. No carriage returns are necessary at the end ofeach row in the grid. The number of columns in the header is used to determine when anew row begins. The number of cell values must be equal to the number of rows times thenumber of columns.

Index

y-axis vertical, 712-D random fracture generator, 223-D random fracture generator, 18

Adaptive timestepping, see Timestepping

Axisymmetric coordinates, 39

Batch file processing, 6, 282Boundary conditions

tecplot output, 149face set, 144flow, 123--142flow

drain flux, 136fluid transfer, 132free drainage, 133hydromechanical stress, 139makeup water, 137river flux, 135specified evaporation, 134specified flux, 128specified head, 126surface loading, 138

interpolation, 147irrigation parameters, 132nodal flux head constraints, 130NODATA value, 149node set, 144pressure irrigation table, 132scaling factor, 148set creation

create face set, 125create face set from chosen faces,

125

create node set, 125create segment set, 125

subsurface flow, 123surface flow, 140time file table, 145time raster table, 144time value table, 144time-field data table from regional,

146transport, 149--162transport

dissolving source, 160specified concentration, 150specified mass flux, 151specified third-type concentration,

152thermal energy, 156zero-order source, 161

type, 125

Channel flowinput, 201

Choosing grid components, 45--69Choosing grid components

elements, 64faces, 55nodes, 46segments, 53zones, 168

Commentsin input files, 8, 13, 169inline, 7

Control volume finite-element methodin finite-difference approach, 72

296

INDEX 297

Cutoff walls, 207

Data visualization utility, 286Debug control file instructions

Compute underrelaxation factor, 277Concentration change target, 277Debug off, 274Flow maximum iterations, 277Flow solver convergence criteria, 277Flow solver detail, 277Force timestep, 277Head change target, 277Mass balance format, 276Mass change target, 277Mass error target, 277Maximum timestep, 277Maximum timestep multiplier, 277Minimum timestep multiplier, 277Newton absolute convergence criteria,

277Newton absolute maximum residual,

277Newton maximum iterations, 277Newton maximum residual increase,

277Newton maximum update for depth,

277Newton maximum update for head,

277Newton residual convergence criteria,

277Newton target, 277Nodal flow check, 276Nodal flow check tolerance, 277Pause at time, 274Pause flow convergence loop, 274Pause newton loop, 274Pause timestep, 274Saturation change target, 277Time format, 276Time progress, 276Transport solver convergence criteria,

277Transport solver detail, 277

Transport solver maximum iterations,277

Watch node list...end, 275Water depth change target, 277Write delval node info, 275Write evapotranspiration, 275Write flow matrices, 275Write fracture (dual node) flow, 275Write krw file, 276Write output files, 274Write overland flow, 275Write resval node info, 275Write seepage face output to .lst file,

275Write transport matrices, 275

Discrete fracturesinput

impermeable matrix, 187Import from FRACTRAN, 207saturated flow properties, 185transport properties, 237variably-saturated flow properties,

209Dissolving source, 160Drain flux, 136Dual continuum

inputsaturated flow properties, 191transport properties, 238variably-saturated flow properties,

211

Evapotranspirationinput

properties, 223Example instruction text, 6, 8Export

face and segment information, 248GMS format

2-D mesh, 2482-D rectangles as triangles, 2483-D mesh, 248fracture elements, 249well elements, 248

Tecplot format

INDEX 298

3-D mesh, 249et zones, 250Hydraulic conductivities, 249porosity, 250tile drain elements, 249tortuosity, 250well elements, 249

Finite difference solutioninput, 72

Fluid flux binary output, 251Fluid flux output, 250Fluid transfer, 132Free drainage, 133

Grid generation, 14--43Grid generation

2-D random fractures, 223-D layered, interactive, 33

Base elevation, 33New layer, 33Zone numbering, 33

3-D random fractures, 18adapt grid to fractures, 41blocks

interactive, 16uniform, 14variable, 15

flip grid around x or y, 41importing

algomesh 2d, 30FRACTRAN 2-D meshes, 31

prismsuniform, 15variable, 16

rectanglesinteractive, 30uniform, 29variable, 29

signalling end of input, 43tetrahedral elements, 38triangles

uniform, 30

Heat transfer, 90, 120Hydrograph output, 257

Hydromechanical stress, 139Hydromechanics

activating, 70

Immiscible source, 160Impermeable matrix, 187Inactive elements, 92Incompressible fluid, 12Initial conditions

flow, 94from 2D location-head information, 97from a previous flow solution, 97from a previous transport solution,

104from ground surface elevation, 96larger scale simulation results, 98porous medium initial head, 97surface flow, 101transport, 102

Input instructions2D mesh to gms, 248Adapt grid to fractures, 41AECL properties, 180Affects fluid properties, 118Air entry pressure, 215Allow internal faces, 55Alpha, 214Anisotropic tortuosity ratio, 234, 240Aperture, 186Assign zone zero, 164Atmosphere...End, 157Auto save on, 76Axisymmetric coordinates, 39Backward-in-time, 71Bank height, 206Base elevation...End, 33Begin 2D random fractures...End, 21Beta, 214Binary flux output nodes, 251Binary flux output nodes from chosen,

251Boundary condition...End, 124Bulk density, 235, 240Calcium species, 117Canopy evaporation interval, 231

INDEX 299

Canopy storage parameter, 224Carbonate species, 117Central weighting, 81Chloride species, 117Choose elements 3pt plane, 66Choose elements above gms surface,

68Choose elements above raster surface,

68Choose elements above raster surface,

iprop zero, 68Choose elements all, 65Choose elements am, 68Choose elements below gms surface,

68Choose elements below raster surface,

68Choose elements below raster surface,

iprop zero, 68Choose elements between gms

surfaces, 68Choose elements between raster

surfaces, 68Choose elements between raster

surfaces, iprop zero, 68Choose elements block, 66Choose elements block by layer, 67Choose elements by layer, 67Choose elements by zone, 65Choose elements from arcview ascii

thickness map, 69Choose elements horizontal circle, 69Choose elements list, 67Choose elements top, 67Choose elements x plane, 65Choose elements xyz list, 67Choose elements y plane, 65Choose elements z plane, 65Choose face by nodes, 62Choose faces 3pt disk, 56Choose faces 3pt inclined plane, 64Choose faces 3pt plane, 57Choose faces 3pt plane bounded, 57Choose faces all, 55Choose faces am, 60

Choose faces back, 59Choose faces block, 57Choose faces block by layer, 58Choose faces bottom, 59Choose faces front, 59Choose faces horizontal circle, 62Choose faces left, 59Choose faces right, 59Choose faces sheet, 58Choose faces stairway, 61Choose faces top, 58Choose faces top am, 60Choose faces top am common, 60Choose faces top am exclude, 60Choose faces top block, 58Choose faces top for chosen elements,

60Choose faces top from raster, 59Choose faces vertical from am nodes,

61Choose faces x plane, 56Choose faces y plane, 56Choose faces z plane, 56Choose fracture faces block, 62Choose horizontal faces on layer, 61Choose node, 47Choose node number, 47Choose nodes 2d-list sheet, 51Choose nodes 3pt plane, 48Choose nodes 3pt plane bounded, 48Choose nodes active/inactive

boundary, 51Choose nodes all, 47Choose nodes am, 50Choose nodes between zones, 53Choose nodes block, 48Choose nodes bottom, 49Choose nodes by zone, 52Choose nodes horizontal circle, 51Choose nodes lateral boundaries, 50Choose nodes list, 50Choose nodes polyline by sheet, 52Choose nodes polyline top sheet, 52Choose nodes sheet, 49Choose nodes tecplot geometry, 51

INDEX 300

Choose nodes top, 49Choose nodes top 2d-list, 52Choose nodes top am, 49Choose nodes top block, 49Choose nodes top boundary, 50Choose nodes x plane, 47Choose nodes xyz list, 50Choose nodes y plane, 47Choose nodes z plane, 47Choose segments all, 53Choose segments am node list, 55Choose segments line, 54Choose segments polyline, 54Choose segments polyline by sheet, 54Choose segments xy between sheets,

55Choose surface flow nodes, 50Choose zone number, 168Choose zones all, 168Clear chosen elements, 65Clear chosen faces, 55Clear chosen faces by nodes, 62Clear chosen inclined faces, 64Clear chosen nodes, 46Clear chosen segments, 53Clear chosen zones, 168Cloud cover, 157Compute fd cross terms, 72Compute loading efficiency, 175Compute statistical properties of

plume, 260Compute underrelaxation factor, 85Compute underrelaxation factor limit,

85Compute velocity field from head, 100Compute velocity field from head and

conc, 101Compute water volume by zone, 252Concentration control, 78Concentration control, multi-species,

78Control volume, 72Convert pm k to macropore k, 193Coupling conductivity, 197, 201Coupling dispersivity, 238, 241

Coupling hydraulic conductivity, 187Coupling length, 186, 197, 201, 222Courant number, 87Create face set, 125Create face set from chosen faces, 125Create node set, 125Create segment set, 125Critical depth, 140Cutoff Walls, 207Data check only, 72DDF Picard iteration control, 77Decay constant, 109Defined flow, 72Density of air, 91, 121, 158Detection threshold concentration, 89Distribution coefficient, 111Do heat transfer...End, 90, 121Do transport, 70Drag coefficient, 159Drop tolerance preconditioning, 73Drop tolerance threshold, 74Dry albedo, 241Dual decay constant, 113Dual distribution coefficient, 114Dual freezing by pm temperature, 245Dual freundlich isotherm, 114Dual nodes for channel flow, 204Dual nodes for fracture flow, 86Dual nodes for surface flow, 86Dual nodes for tiles, 201Dual nodes for wells, 197Dual nonlinear decay with saturation,

113Dual nonlinear decay with

temperature, 113Echo 1d loading conditions, 139Echo chosen faces, 63Echo coordinates, 247Echo et at point, 231Echo fracture incidences, 247Echo incidences, 247Echo off, 9Echo on, 9Echo to output, 250Echo transport boundary conditions,

INDEX 301

149Edf constant function, 231Edf cubic decay function, 231Edf quadratic decay function, 231Effective area tables...End, 211Effective area Wang-Narasimhan

functions, 211Effective diffusion coefficient by

species, 123Effective diffusion coefficient list, 123,

234Element K anisotropic, 176Element K isotropic, 175Elemental stress field from files, 140Elevation constant, 36Elevation from bilinear function in xy,

37Elevation from cosine function in xy,

38Elevation from file, 38Elevation from raster file, 36Elevation from regional model gb file,

100Elevation from sine function in xy, 38Elevation from tsurf file, 36Elevation from xz pairs, 38End, 14, 21, 43ET zones to tecplot, 250Evaluate capture zone, 71Evaporation depth, 230Evaporation limiting pressure head,

226Evaporation limiting saturations, 225Example instruction text, 6Example instruction text...End, 8Exponent, 215Exponential length distribution, 25Exponential zero order source, 92, 123Face set, 144Find zero age zones, 120Finite difference mode, 72First-order fluid exchange coefficient,

193First-order mass exchange, 240Flag observation nodes if exceed

detection threshold concentration,89

Flow solver convergence criteria, 80Flow solver detail, 80Flow solver maximum iterations, 79Flow time weighting, 79Fluid compressibility, 12Fluid pressure, 79Fluid surface tension, 12Flux, 128Flux limiter for transport, 88Flux nodal, 129Flux output nodes, 251, 258Flux output nodes from chosen, 251,

258Flux volume output nodes, 258Fractionation factor, 236Fractran properties, 208Fracture advective solute exchange

only, 89Fracture decay constant, 116Fracture information, 20Fracture length distribution x-axis, 20Fracture length distribution y-axis, 20Fracture length distribution z-axis, 20Fracture location distribution x-axis,

21Fracture location distribution y-axis,

20Fracture location distribution z-axis,

20Fracture retardation factor, 116Fracture zone porosity, 186Fractures to gms, 249Free drainage, 133Free-solution diffusion coefficient, 109Freshwater pressure head, 79Freundlich isotherm, 111Friction, 196, 200, 205Function surface elevation initial

head, 97Function x initial head, 96Function z initial head, 96Generate aperture distribution, 23Generate blocks interactive...End, 16

INDEX 302

Generate exponential lengthdistribution, 26

Generate individual fracture and readparameters from file, 187

Generate layers interactive...End, 32Generate log-normal length

distribution, 25Generate orientation distribution, 23Generate rectangles interactive, 29Generate tables from unsaturated

functions, 216Generate target times, 76Generate uniform blocks, 15Generate uniform prisms, 15Generate uniform rectangles, 29Generate uniform triangles, 30Generate variable blocks, 16Generate variable prisms, 16Generate variable rectangles, 29Geometric bulk thermal conductivity

relation, 237Get average K, 180Grade x, 17Grade y, 17Grade z, 17Gravitational acceleration, 11Grid information, 19Growth beginning time, 229Hagen Poiseuille, 196, 200Harvest time, 229Hazen Williams, 196, 200Hazen Williams coefficient, 197, 200Head, 126Head control, 77Head equals elevation, 126Head equals initial, 127Heat coupling length, 241High-K plane, 186Hydrogencarbonate species, 117Immiscible phase dissolution data,

161Immobile zone mass transfer

coefficient, 235Immobile zone porosity, 235Impermeable matrix, 187

Incoming longwave radiation, 158Incoming shortwave radiation, 157Infilled, 196, 200Initial concentration, 102Initial concentration for zones, 104Initial concentration from file, 103Initial concentration from output file,

102Initial concentration from xyc file, 102Initial head, 94Initial head depth to water table, 96Initial head from depth-saturation

table, 95Initial head from file, 95Initial head from output file, 95Initial head from porous medium, 97Initial head from regional output file,

98Initial head from regional output file

with depth scaling, 98Initial head from xyh file, 97Initial head raster, 96Initial head subsurface from surface

output file, 95Initial head surface elevation, 94Initial immobile concentration from

output file, 103Initial immobile zone concentration,

104Initial immobile zone concentration

from file, 104Initial interception storage, 224Initial root depth, 229Initial temperature profile, 92, 122Initial time, 75Initial timestep, 75Initial water depth, 101Initial water depth from file, 101Integrate production zone, 264Interface k, 193Interface relative permeability xy, 213Interface unsaturated brooks-corey

functions, 213Interface unsaturated tables, 212Interface unsaturated van genuchten

INDEX 303

functions, 213Interpolate, 147Interpolate mass flux, 152Interpolate permafrost, 184Irrigation on demand, 130Irrigation parameters, 131Isotope fractionation data...End, 235Iteration parameters flux limiter, 89Jacobian epsilon, 82K anisotropic, 173, 192K anisotropic by ratio, 173, 192K isotropic, 173, 192K reduction by impedance factor for

chosen elements, 183K tensor, 174K to tecplot, 250LAI tables...End, 226Latent heat of vapourization, 159Layer name, 34Level of fill, 73List surface flow nodes, 248Loading efficiency, 175Longitudinal dispersivity, 233, 238,

239, 241Lower limit, 81Magnesium species, 117Make element inactive, 93Make element inactive using shapefile,

93Make fractures from fgen, 188Make interpolated observation point,

253Make node observation point, 254Make observation point, 253, 260Make observation well, 254, 261Make observation well from xy, 254Make recharge spreading layer, 191Make zone inactive, 93Makeup water, 137Manning, 196, 200Map anisotropic K from raster, 177Map fractures from mofrac vtk file,

189Map fractures from tecplot file, 188Map initial head from raster, 96

Map isotropic K from raster, 176Map K from regional model list file,

99Map K from regional model list file

by layer, 100Map porosity from raster, 177Map tortuosity from raster, 178Map zone numbers from regional

model, 98Map zone numbers from regional

model by layer, 99Mass balance output fixed format,

247Mass balance output general format,

247Mass balance output scientific format,

247Mass change control, 78Mass error control, 78Maximum flow depth, 223Maximum root depth, 229Maximum timestep, 75Maximum timestep multiplier, 78Mean age, 70Mechanical heat dispersion, 91, 122Mesh to gms, 248Mesh to tecplot, 249Minimum elemental energy slope, 223Minimum layer thickness, 34Minimum layer thickness with fixed

top elevation, 34Minimum relative permeability, 215Minimum relaxation factor allowed,

85Minimum relaxation factor for

convergence, 83Minimum timestep, 75Minimum timestep multiplier, 78Name, 108New layer...End, 33New zone, 163Newton absolute convergence criteria,

82Newton absolute maximum residual,

83

INDEX 304

Newton information, 86Newton iteration control, 77Newton maximum iterations, 82Newton maximum residual increase,

84Newton maximum update for depth,

83Newton maximum update for head,

83Newton minimum iterations, 82Newton residual convergence criteria,

82No fluid mass balance, 79No freezing in dual domain, 245No matrix scaling, 74No nodal flow check, 84No solute mass balance, 262Nodal flow check tolerance, 84Nodal flux head constraints, 130Nodal flux reduction by pressure

head, 130Nodata file, 149Nodata raster, 149Nodata value, 149Node set, 144Nonlinear bulk thermal conductivity

relation, 237Nonlinear decay with saturation, 109Nonlinear decay with temperature,

110Number of random fractures, 22Obstruction storage height, 206, 222Offset base, 36Offset top, 35Output ET details, 252Output peclet number, 87Output random apertures, 26Output random fractures, 26Output random lengths, 26Output random orientations, 26Output saltwater head, 251Output times, 76Output travel time statistics, 263Overland advective solute exchange

only, 89

Overland decay constant, 116Overland retardation factor, 117Parents, 109Pause, 10Peclet number, 87Permafrost effective diffusion

coefficient, 185Permafrost formation from file, 184Permafrost k, 184Permafrost porosity, 184Picard convergence criteria, 90Plot concentration penetration depth,

259Plot maximum velocity, 260Poisson ratio, 175Pore connectivity, 215Pore water freezing and thawing

Background temperature, 243Freezing temperature, 244Integration convergence criteria,

244Integration maximum iterations,

244Interpolate surface temperature,

245Maximum freezing depth, 244Melting temperature, 244Memory length for convolution

integral, 245Pore water freezing-thawing...End,

242Surface temperature, 243Surface temperature from raster,

243Thermal diffusivity, 243

Porosity, 174, 192Porosity to tecplot, 250Potassium species, 117Potential evaporation using

transpiration, 231Potential Evapotranspiration, 134Pressure head input, 79Pressure irrigation table, 132Pressure of air, 160Pressure-effective area, 211

INDEX 305

Pressure-saturation, 220Primary variable switching, 81Project 2d grid, 43Project grid, 43Properties file, 169Proportional sublayering, 35Radius, 196, 199Rain, 129Random K field from FGEN, 181Random KD field from FGEN, 181Raster to element, 32Raster to nprop, 32Raster to scl, 31Rdf constant function, 226Rdf cubic decay function, 226Rdf quadratic decay function, 226Read 3D grid, 40Read 3D grid, ascii, 41Read algomesh 2d grid, 30Read chosen faces, 63Read elemental K from file, 176Read elemental porosity from file, 177Read elemental specific storage from

file, 178Read elemental tortuosity from file,

178Read fractran 2d grid, 31Read inactive elements from file, 94Read overland zones from raster, 165Read overland zones from raster,

dominant class, 165Read pm zones from voxet file, 165Read properties, 170Read rill storage from raster, 223Read zones from file, 164Read zones from raster for chosen

elements, 165Rectangles to triangles, 248Red black reduction, 73Reduce 2d grid, boundary file, 30Reference fluid density, 12Reference fluid viscosity, 12Refine 2d grid, 30Regional model, 98Relative concentration, 118

Relative humidity, 160Relative permeability xy, 208, 212Remove negative coefficients, 84Remove rectangles with blanking file,

31Remove rectangles with shapefile, 31Report exchange flux for chosen

nodes, 252Report exchange for olf zones, 252Reservoir, 141Residual saturation, 214Restart file for concentrations, 104Restart file for heads, 97Reverse rate, 236Rfgen driver, 18Rill storage height, 206, 222Rock-water mass ratio, 236Root depth, 226Root growth period, 229Root growth...End, 226Salt mass fraction, 117Saturated albedo, 241Saturated wells, 197Saturation control, 77Saturation vapour pressure, 160Saturation-relative k, 220Scaling factor, 147Set hydrograph nodes, 257Simple drain, 136Simple river, 135Sinusoidal incoming shortwave

radiation, 157Sinusoidal temperature of air, 158Sinusoidal wind speed, 159Skip off, 10Skip on, 10Skip rest, 10Slice flux contributing nodes from

chosen, 259Slice flux output nodes from chosen,

258Snapshot mean age, 70Snapshot mean life expectancy, 71Snowmelt, 142Snowmelt constants, 144

INDEX 306

Sodium species, 117Soil Frost K, 181Soil Frost K by ratio, 182Soil water balance, 252Soil-Water suction at surface, 160Solids compressibility, 175Solute, 108Solute Definition

Affects fluid properties, 118Dual nonlinear decay with

temperature, 114Name, 109Nonlinear decay with temperature,

111Relative concentration, 118Sodium species, 117Solute, 108

Solute temperature profileBackground temperature, 106Integration convergence tolerance,

107Integration maximum iterations,

107Integration memory length, 107Maximum depth, 106Number of points, 108Solute 1d temperature profile, 105Solute dual 1d temperature profile,

106Surface temperature, 106Thermal diffusivity, 106

Solute uptake by plant roots, 112Solver acceleration technique, 74Species attribution, 71Specific heat capacity of air, 91, 121Specific heat capacity of solid, 237Specific heat capacity of water, 91,

122Specific heat of air, 158Specific humidity of air, 159Specific storage, 174, 186, 192Specified concentration, 150Specified concentration from file, 150Specified concentration from initial

concentration, 103

Specified mass flux, 151Specified stress variation, 138Specified stress variation from file,

138Specified temperature flux, 156Specified third-type concentration,

152Specified third-type concentration

from face file, 155Specified third-type concentration

from file, 153Specified third-type flushing, 156Stop run if flux output nodes exceed

detection threshold concentration,89

Streambed conductivity, 206Streambed thickness, 206Sulphate species, 117Surface loading, 70Table maximum s-k slope, 216Table minimum pressure, 216Table smoothness factor, 216Target times, 76Tecplot output, 149Temperature of air, 158Temperature species, 117Temperature-dependent thermal

conductivity of solid, 236Tetrahedra, 38Thermal conductivity of air, 90, 121Thermal conductivity of solid, 236Thermal conductivity of water, 91,

121Tiles to tecplot, 249Tilt grid x, 41Tilt grid y, 41Time dependent K for chosen

elements, 182Time dependent variable K for

chosen elements, 182Time file table, 145Time output fixed format, 247Time output general format, 247Time output scientific format, 247Time raster table, 145

INDEX 307

Time raster xz table, 145Time raster yz table, 145Time value table, 144Time varying friction...End, 221Time varying K by impedance factor

via temperature raster, 183Time varying maximum timestep, 75Time varying surface friction by

temperature raster, 221Time-field data table from regional,

146Time-root depth table...End, 229Tortuosity, 234, 239Tortuosity to tecplot, 250Transient flow, 69Transpiration fitting parameters, 225Transpiration limiting pressure head,

225Transpiration limiting saturations,

225Transport solver convergence criteria,

87Transport solver detail, 88Transport solver maximum iterations,

88Transport time weighting, 86Transverse dispersivity, 234, 238, 239,

241Travel time CDF, 70Travel time PDF, 70Travel time PDF from CDF, 70Type, 125Type circle, 205Type general, 205Type rectangle, 205Type trapezoid, 205Underrelaxation factor, 85Uniform sublayering, 34Units: kilogram-metre-minute, 11Unproject 2d grid, 43Unsaturated, 70Unsaturated brooks-corey

functions...End, 213Unsaturated tables, 220Unsaturated van genuchten

functions...End, 213Upper limit, 81Upstream weighting factor, 80Upstream weighting of velocities, 88Use constant seed, 22Use domain type, 163Use Pitzer model, 104Verhulst-Pearl growth, 50% max

depth, 230Verhulst-Pearl growth, time-depth,

230Vertical fracture from top, 21Vertical slice flux by layer, 259Vertical transverse dispersivity, 234,

239Volume fraction dual medium, 193Water depth control, 77Wells to gms, 249Wells to tecplot, 249Wind speed, 159Write chosen faces, 63Write chosen faces and host element

numbers, 63Write chosen nodes, 53Write chosen nodes xyz, 53Write element K, 178Write element K at z, 179Write faces and segments, 248Write inactive elements to file, 93Write zones to file, 164X friction, 221XY fracture aperture distribution, 21XZ fracture aperture distribution, 21Y friction, 221Y vertical, 71YZ fracture aperture distribution, 21Z function initial concentration, 103Zero fluid compressibility, 12Zero order source, 92, 122, 161Zero order source saturation

threshold, 161Zero travel time, 120Zero-depth gradient, 141Zone by layer, 33Zone fractures how, 21

INDEX 308

Zoned decay constant, 109Zoned distribution coefficient, 111Zoned dual decay constant, 113Zoned dual distribution coefficient,

114Zoned dual freundlich isotherm, 115Zoned dual nonlinear decay with

saturation, 113Zoned fracture decay constant, 116Zoned fracture retardation factor, 116Zoned freundlich isotherm, 112Zoned nonlinear decay with

saturation, 110Zoned overland decay constant, 117Zoned overland retardation factor,

117Zones from arcview ascii grid, 167Zones from arcview for chosen

elements, 167

Makeup water, 137Mass flux output, 257Matrix solver

input, 72

Newton-Raphson methodinput, 81

Observation wells and points, 252, 260Output

3-D element incidences, 247at specified times, 76auto save restart files, 76chosen faces, 63element hydraulic conductivity, 179element hydraulic conductivity,

average, 179element zone numbers, 164flow

observation wells, 252fluid flux, 250fluid flux, binary file, 251fluid mass balance, 254fracture element incidences, 247hydrographs, 257mass flux, 257

mass flux entering a volume, 258nodal coordinates, 247observation points, 252, 260solute mass balance, 261suppressing mass balance output, 262surface flow nodes, 247transport

observation wells, 260transport boundary conditions, 149element hydraulic conductivity, 179

Output ET details, 252

Physical constantsdefaults, 10unit conversions, 11user specified, 11

Picard iterationinput, 90

Plot control file instructionsCompare heads 3d domain, 289Isolate node, 289No 3d compaction, 288No 3d concentrations, 288No 3d darcy velocities (qx, qy, qz),

288No 3d dual-permeability

concentrations, 290No 3d dual-permeability darcy

velocities (qx dual, qy dual, qzdual), 290

No 3d dual-permeability heads, 290No 3d dual-permeability linear

velocities (vx dual, vy dual, vzdual), 290

No 3d dual-permeability saturations,290

No 3d fracture apertures, 288No 3d heads, 288No 3d immobile zone concentrations,

288No 3d linear velocities (vx, vy, vz),

288No 3d saturations, 288No elemental hydraulic conductivity,

288

INDEX 309

No elemental hydraulic conductivitydual, 288

No elemental peclet numbers, 288No elemental porosity, 288No elemental specific storage, 288No elemental tortuosity, 288No et, 292No fracture apertures, 291No fracture concentrations, 291No fracture darcy velocities (vx, vy,

vz), 291No fracture heads, 291No fracture immobile zone

concentrations, 291No fracture linear velocities (vx, vy,

vz), 291No fracture/subsurface solute

exchange flux, 291No permafrost, 288No surface flow concentrations, 292No surface flow heads, 292No surface flow linear velocities (vx,

vy, vz), 292No surface log10(depth), 292No surface/subsurface exchange flux,

292No surface/subsurface solute

exchange, 292Paraview mode, 287Plot pm depth below ground surface,

290Tecplot mode, 287Truncate 3d domain, 288Truncate fracture domain, 291Truncate fracture time domain, 291Truncate surface flow domain, 292Truncate surface time domain, 292Truncate time domain, 289Write 3d domain file, 288Write dual-permeability results to 3d

domain file, 290Write fracture domain file, 291Write fracture elements to 3d domain

file, 291Write surface flow domain file, 292

Porous mediuminput

saturated flow properties, 172transport properties, 233variably-saturated flow properties,

208Potential evaporation using transpiration,

231Pre-processor instructions

Usage, 6Pressure head input/output, 79Primary variable substitution

input, 81

Radioactive decayinput, 108

Random distribution coefficient fields, 181Random fracture generation, see Grid

generationRandom hydraulic conductivity fields, 180Raster file format, 294--295Recharge spreading layer, 190Report exchange for olf zones, 252River flux, 135Root growth, 226Root growth

Growth beginning time, 229Harvest time, 229Initial root depth, 229Maximum root depth, 229Root growth period, 229Time-root depth table, 229Verhulst–Pearl growth, 50% max

depth, 230Verhulst–Pearl growth, time-depth,

229Run-time debug utility, 272Run-time timestep output, 278Runoff

inputtransport properties, 240

Soil water balance, 251Solute definition, 108Solver parameters

flow, 79

INDEX 310

transport, 87Subsurface domain

inputboundary conditions, 125flow initial conditions, 94saturated flow properties, 172transport properties, 233variably-saturated flow properties,

208Surface domain

inputboundary conditions, 140flow initial conditions, 101properties, 220

Surface loading, 138

Telescopic mesh refinementdefining a regional model, 98

Tetrahedral elements, 38Tile drains

input, 197Time stepping

adaptiveinput, 76

general input, 74Transient flow

activating, 69Transport

activating, 70input

auxiliary features, 123discrete fracture properties, 237dual continuum properties, 238heat transfer, 120

immiscible phase dissolution source,160

initial conditions, 102porous medium properties, 233solute definition, 108specified concentration, 150specified mass flux, 151specified third-type concentration,

152surface runoff properties, 240thermal energy, 156travel-time probability, 120zero-order source, 161

Unit conventions, 10

Variably-saturated flowactivating, 69defining functional constitutive

relationships, 213defining tabular constitutive

relationships, 219vertical y-axis, 71

water volume contained in different zones,252

Zero-order source, 161Zones

creating, 163creating using ArcView files, 166modifying properties, 168saving and retrieving element zone

numbers, 164selecting, 168

hgs simulations is a product of aquanty inc. · 2.hgs is run to solve the problem and generate...

Documents