Guide for New Users
We’re happy to provide all new users of HydroGeoSphere with a variety of training materials to help you understand how HydroGeoSphere works and how you can apply it to your own projects. If you’re just starting out with HydroGeoSphere we recommend the following:
Attend a free half-day training session (sessions scheduled once per month). Visit the event calendar for info:
Complete the ‘Intro to HydroGeoSphere’ Tutorial - a comprehensive interactive tutorial that covers the full HGS workflow in great detail.
Review the ‘HydroGeoSphere Basics’ presentation - a series of slides which provide a brief overview of the HydroGeoSphere workflow
Download the ‘Introductory Modules’ - a series of increasingly complex box models which can be reviewed to understand the structure of *.grok files
Check our YouTube channel for more detailed instructional videos focused on different aspects of the HydroGeoSphere workflow
Join the HydroGeoSphere User Community for additional support - tutorials, featured commands, seek help from hundreds of user from around the world
Step 1: Installation & Activation
HydroGeoSphere (HGS) runs on 64 bit versions of the Windows and Linux operating systems. Visit our Download page to get the most recent release of HGS and run the installer. Once the software is installed you’ll need to activate a license in order to run your simulations. To activate, email the hostid.txt file that is generated in the installation directory (C:\Program_Files\HydroGeoSphere on Windows) to support@aquanty.com. In return you will receive the license file hgs.lic, which you should put into your installation directory.
If you haven’t purchased but would like to trial the software click the button below to request a temporary license:
![The HGS Installation Folder - [C:\Program_Files\HydroGeoSphere]](https://images.squarespace-cdn.com/content/v1/604a720da3d5371bee6b737d/1617022703447-Y679HCJ6PNKPRBBUO4S9/install+folder.PNG)
The HGS Installation Folder - [C:\Program_Files\HydroGeoSphere]
Note for Windows Users
The installer will attempt to add the installation directory (C:\Program_Files\HydroGeoSphere) to the user’s PATH environment variable. Should it fail to do so, e.g., if it does not have write access, then you will need to update the PATH variable manually. Otherwise, it will be necessary to copy all executable and DLL files into each simulation folder. We recommend that you always run the installer with administrator privileges if possible.
Note for Linux Users
When you log into your Linux system, you will need to set the environment variable HGSDIR to where HGS was installed. To do so, you can edit your shell script file (~/.bash_profile if you are using bash). For example, you can add the following two lines to set HGSDIR and to add that directory to PATH:
export HGSDIR=/home/username/HGS
export PATH=$PATH:$HGSDIR
You will also need to modify the LD_LIBRARY_PATH variable so that external dependencies of HGS can be found by your system at run-time:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HGSDIR/lib
Step 2: Configure a *.GROK File
The first step for all HydroGeoSphere simulations is to run GROK.EXE, the HGS preprocessor program. GROK reads and translates all of the input files into the model runtime code. All of the input commands are placed into the *.grok file. These commands are described in the HGS reference manual, which you can find in your doc directory. As a first model, we will consider the Abdul test case, which is located in the verification\abdul directory under the installation directory.
Open the abdul.grok file with your favorite text editor (e.g. notepad, sublime text, notepad++, vim). This input file contains all of the commands to create the Abdul test case. An image of the *.grok file is shown to the left.
Step 3: Run GROK.exe
Run GROK.EXE by opening a command line in the abdul directory and running the GROK.EXE executable. To open the command line in Windows simply type ‘cmd’ into the address bar in Windows Explorer. The simply type ‘grok.exe’, hit enter and GROK.EXE will begin running. A series of new files will populate the project folder (these are the input files for HydroGeoSphere).
To check the output from GROK, open the abdulo.eco file. This is the GROK listing file; results of the HydroGeoSphere data generation procedures are written to this file so if there are any problems reported by the pre-processor you should check this file first to determine their nature and how you might fix them.
A successful GROK run will say ---- Normal exit ---- at the bottom of the abdulo.eco and in the command line.
Step 4: Run HydroGeoSphere
Run HydroGeoSphere by running the PHGS.EXE executable from the command line. This simulation may take several minutes to complete. Once the simulation has completed you will have several output files such as abdulo.head_pm.0009.
The model project folder and command line after running GROK.
Trouble Shooting
Copy the hgs.lic license file to the installation directory.
Copy and paste the DLL files into the working directory.
Step 5 Run HSPLOT.exe & Visualize Your Results
Run HSPLOT by running the HSPLOT.EXE executable from the command line.
HSPLOT will produce two output files:
abdulo.olf.dat (the overland flow output file)
abdulo.pm.dat (the porous medium output file)
Open tecplot, and drag and drop the abdulo.olf.dat file. This is the output for the overland flow portion of the simulation. Change the output to LogDepth to show the depth of overland flow.
Open tecplot, and drag and drop the abdulo.pm.dat file. This is the output for the porous medium flow portion of the simulation. Change the output to Sat to show the soil saturation.
General Comments
Work through the verification problems included in the installation to gain an understanding of the basic model and process setup.
Start with an existing grok file that is similar to your needs. The verification folder is a great place to start.
The reference manual is searchable and includes an index. Search it to look up command functions.
Copy the executable files (grok.exe, phgs.exe, and hsplot.exe) and the DLL files from the installation folder into your simulation folder. This allows for version auditing if you revisit simulation results at a future date.
For large models directory structure is important. Large input files (climate, geology) common to multiple simulations can be centrally located.
Debug.control file is very useful for examining current model state at an arbitrary solution time, or for saving output before prematurely terminating a simulation. See the comment below on the use of the exclamation point to control commands in the debugger.
Numerical models don’t like zeros! Use a small number instead of 0 (i.e., 1e-10).
Think carefully about your simulation controls (e.g., max timestep, head control, convergence criteria, etc.) as overly restrictive values can result in unnecessarily slow runtimes (sometimes orders of magnitude slower).
Grok Commands all users should know
! – the exclamation point allows users to insert comments in the grok file. Liberal use of comments is great for documentation and can make it easier for other users to review and understand model setup. Use comments to temporarily deactivate commands rather than deleting them.
Interpolate – Used with time series in boundary conditions. Smooths out the shock between stress periods and can significantly improve simulation time.
Impermeable matrix – Shuts off subsurface flow when setting up and testing the overland flow domain.
Skip on/off/rest – causes grok to skip over portions of the grok file without having to delete those portions. Useful for trouble shooting bad runs.
Mesh to tecplot – Outputs the 3D mesh during execution of grok.exe. Useful for inspecting model setup prior to simulation.
Auto save on – Outputs a snapshot of heads and concentrations at regular wall clock intervals. Useful way to intermittently save simulation results. Particularly useful for long simulations where a computer failure is possible. Ensures that not too much simulation time is lost while not incurring significant data storage.
Debugging
*.eco - this file is generated during execution of grok.exe and is a more verbose version of what is displayed on the screen when grok is running. Reviewing this file can be very informative should you suspect a setup issue, or if grok fails.
*.lst – this file is generate during phgs.exe execution. This is a more verbose version of the screen output and provides additional insight into simulation performance and water balance.
Visualization (with Tecplot)
Running preplot.exe (found in the Tecplot installation) after running hsplot.exe significantly reduces Tecplot load time for large models by converting the hsplot ASCII output to binary.
Blanking is a great way to view properties or results for different material zones.
*.plot.control – controls hsplot.exe. Useful for decreasing or increasing the amount of information formatted for visualization. Can also be used to create files for other visualization tools such as Paraview.
Parallelization
HGS parallelization can be used to significantly improve run times.
Test the model in serial mode to make sure that everything is setup and running properly before switching to parallel mode.
Use an equal and even number of CPUs and domain partitions (e.g., 2,4,6,8…).
Parallel efficiency degrades at a certain point (more CPUs isn’t always better for small models). Optimum parallel efficiency is often around 100,000 nodes per CPU.
Visit the following link for more information: https://www.aquanty.com/blog/2016/2/18/hgs-parallelization-best-practices