Contents

Preface

Copyright

This document refers to MOHID Studio, proprietary computer software which is protected by copyright. All rights are reserved. Copying or other reproduction of this document or related programs is prohibited without prior written consent of Action Modulers, Consultores de Segurança (Action Modulers).

MOHID Water Modelling System is proprietary software of the Instituto Superior Técnico from University of Lisbon.

Warranty

The warranty given by Action Modulers is limited as specified in your Software License Agreement. Please note that numerical modeling software programs are very complex systems and may not be free of errors, so you are advised to validate your work. Action Modulers shall not be responsible for any damage arising out of the use of this document, MOHID Studio, MOHID Water Modelling System or any related program or document.

Further Information

For further information about MOHID Studio please contact:

Action Modulers, Consultores de Segurança Lda.

Rua Cidade de Frehel, Bloco B, Nº 12 A

2640-469 Mafra, Portugal

Tel.: +351 261 813 660

Fax: +351 261 813 666

E-mail: geral@actionmodulers.com

Web: http://www.actionmodulers.com

Quick Start Tutorial for MOHID Water

This "Quick Start Tutorial for MOHID Water" is intended to help first-time users creating their first projects, following a sample project, an implementation in the Tagus Estuary, near Lisbon, Portugal.

It is suggested that the user follows the tutorial, which progresses with increasing complexity, trying to replicate the provided sample project. After finished exploring all simulations with the samples, it is suggested that the user revisits the tutorial applying the model examples to his study site.

The tutorial starts with the sample project for the user to get used to the MOHID Studio environment, project and simulation structure and to start exploring results without any previous knowledge about using MOHID Water.

After the first play-around the user is invited to independently create a simple project with 2D hydrodynamics forced with tide, generating the bathymetry and tide files, prepare the input files, run the model and explore results as previously.

The tutorial then starts to increment complexity providing a step-by-step to implement a full 3D simulation with river discharges and meteorology, sediment transport, point sources (using also Lagrangian approach) and ending in nutrient transport and transformation (full water quality simulation), resulting in one of the most complete simulation (all processes connected) that can be run with MOHID Water.

Since keywords and blocks of keywords need to be defined in the input files, for the user convenience, the user is guided to copy data files from the sample project.

This is intended to be a step-by-step tutorial to implement in a straightforward way a MOHID Water project from simpler to complex simulations. Detailed description is not given for processes, keywords, model functioning, etc. For that intent the user should explore MOHID sources:

Action Modulers website – http://www.actionmodulers.com

MOHID website – http://www.mohid.com/

MOHID wiki – http://wiki.mohid.com/wiki

MOHID forum – http://www.mohid.com/forum/

MOHID code repository – http://mohid.codeplex.com/

Exploring a sample project

The tutorial starts by providing a sample project so that the user gets familiarized to the MOHID Studio structure and is able to get the sample simulation running and produce model results. This way the tutorial allows the user to straightaway obtain some model results with little effort and then in the following chapters the intermediate steps are explained (creating the project and simulations).

It is assumed that the user has already installed MOHID Studio (following MOHID Studio Install Guide) and is aware and understands the functioning of the different windows, environments and buttons (following MOHID Studio User Guide).

This manual applies to MOHID Studio version 1.2.7.

Step 1 – Opening the predefined project

Download the TagusSample.zip (link below) from Action Modulers Web Page to your local disk (e.g. to D:\MOHIDStudioProjects).

http://www.actionmodulers.pt/Biblioteca/Uploads/Downloads/Walkthroughs/TagusSample.zip

Create a folder in your hard disk for the project (e.g. D:\MOHIDStudioProjects\TagusSample and leave it empty).

Open MOHID Studio where it should appear the "Workspace Manager" window asking to create a new workspace or open a saved one (Figure 22.1). Select "Start with an empty Workspace" and name it for instance "Tagus Sample".

MOHID Studio - MOHID Water Quick Start Guide v1 02.png
Figure 2 2.1: MOHID Studio Workspace Manager.

Select "Project" ribbon and in "Solution" group, press "Manage" and the "Solution Management" window appears (Figure 22.2) showing the list of solution available. If using MOHID Studio for the first time the list will be empty.

MOHID Studio - MOHID Water Quick Start Guide v1 03.png
Figure 2 2.2: MOHID Studio Solution Management.

On the same "Solution Management" window press "Import" and the "Import MOHID Solutions" window appears (Figure 22.2) and in "Project File Name" browse for the .zip file downloaded earlier (e.g. in D:\MOHIDStudioProjects) and in "Destination Directory" choose the directory where the project will be placed (e.g. D:\MOHIDStudioProjects\TagusSample). The destination directory needs to be empty.

Press "Import" and wait till the end of the process and accept the successful message.

MOHID Studio - MOHID Water Quick Start Guide v1 04.png
Figure 2 2.3: MOHID Studio Import Solution.

NOTE: If a solution with the same name of the solution to import already exists, the newly imported solution is automatically renamed (example: Tagus Sample_1) .

The solution was imported and now needs to be opened. Select "Project" ribbon and in "Solution" group, press "Open" and the "Solution Management" window appears now with the "Tagus Sample" available. Select it and press "OK".

This will open the "Tagus Sample" solution in "Explorer" tab. Press on the triangle just left to the solution icon to show the domain tree (it will show "Tagus Sample" domain). Press on the triangle just left to the domain icon to show the domain folder structure and simulations available. There are 5 simulations available just the same as the main simulations of this tutorial. In the next steps, the user may copy the necessary files and doesn’t need to create them from scratch.

Step 2 – Recognizing the project structure and study area

With the solution opened and domain tree, domain folders and simulations tree visible, the user should be see the same structure as presented in Figure 22.4.

MOHID Studio - MOHID Water Quick Start Guide v1 05.png
Figure 2 2.4: MOHID Studio Explorer Window with MOHID Water Sample.

If having some doubts about the MOHID Studio windows and structure please refer to the MOHID Studio User Guide.

When selecting each simulation, the "Modules" section on the right pane is filled with "Data Files" (text files with options and info needed to run each simulation) and no files exist in "HDF Files" or "Time Series Files". The latter correspond to model results (maps and time series, respectively) and do not exist because the simulation hasn’t run yet.

Before running any simulation, check the study area by pressing in the folder General Data\Digital Terrain (see Figure 22.4), selecting the file "TagusBathymetry.dat", and right-clicking it and pressing "Add to Map…" and then pressing "OK". Select the "Map" tab and check the Tagus Estuary bathymetry. This file contains data about the computational grid and the bathymetry value for each grid cell. To plot a background map as reference go to "Map" ribbon and on "Background" group press "Web Tiles". Accept the change in coordinates and select for instance Google Maps or Bing Aerial and press "OK" and it should result similar to Figure 22.5.

To show the bathymetry scale, right-click the bathymetry layer and press "Properties"; check "Legend" box, write down the legend text in "Text" box and press "OK". Unhide the legend by pressing "Legend" in the bottom- right corner of "Map" window.

MOHID Studio - MOHID Water Quick Start Guide v1 06.png
Figure 2 2.5: MOHID Studio Map Window with project sample bathymetry.

Step 3 – Running the simulation

To run the model select the simulation to run (let’s start in "Sim #1"), go to "Project" ribbon and in "Execute Models" group, press "Run Now". A window will appear to check if the user wants to run the selected simulation ("Sim #1"), press "OK".

The box window called "Model Controller" below the domains and simulations is filled showing the progress bar of the simulation (Figure 22.6). To check more details on the simulation status press "Output" button to be able to see what is the current simulation time, the current computer time and the expected computer time when the simulation will end (the content of this log is continuously updated). The "Kill" button on the same box window exists to abort the simulation at any time.

MOHID Studio - MOHID Water Quick Start Guide v1 07.png
Figure 2 2.6: MOHID Studio Model Controller.

When model run finishes (gets to 100% in progress bar or crashed), a window appears, warning that the model has finished and if the user would like to see the log file (the same as obtained in "Output" in Model Controller but now the final file) - Figure 22.7.

MOHID Studio - MOHID Water Quick Start Guide v1 08.png
Figure 2 2.7: MOHID Studio Model Finished.

It is always suggested to watch the log to make sure that the simulation ended successfully (browse till the end of the file - Figure 22.8). If the user does not want to see the log file or closes the log file than is sent back to MOHID Studio and ready to explore results. The log file can be accessed at any time right-clicking each simulation and selecting "View Last Log…".

MOHID Studio - MOHID Water Quick Start Guide v1 09.png
Figure 2 2.8: MOHID Studio Log File reporting that simulation ended with success.

Step 4 – Exploring the Results

During and after the simulation ends, the output files are created. When selecting the simulation that just finished running ("Sim #1"), the "Modules" section on the right pane is filled with "HDF Files" and "Time Series Files". HDF files contain model results for the entire computational grid at different time instants of the simulation, similar to several instantaneous snapshots of the study area that can be plotted has maps and animated in time. Time series files contain results for predefined computational grid points with high output frequency. Latter in this document it will be explained how to define the output locations. On both type of files the user may choose the output frequency (also explained later).

Double-clicking on each HDF or time series, shows a dialog to select the properties to plot. More information on how to visualize and customize HDF results can be found in chapter 4.6 of "MOHID Studio User Guide" and in chapter 5 for the time series results.

To view the time series results for current velocity modulus in one point, in the "Time Series Files" section, double-click to open the file "Channel.srh" (located in Tagus channel in front of Lisbon), and select the property "velocity modulus" and "OK" to plot (Figure 22.9). This is the velocity modulus variation in time in the Tagus Estuary channel. To see the location of this point and other points that have been selected to perform time series outputs, in "Map" ribbon, and "Vector Data" group press "XML" and open TimeSeriesLocation.xml in folder "General Data\TimeSeries" of the sample project, select as the projection "Geographic" and press "OK". The time series points will be displayed on "Map" tab. To know the name of each point, select the points’ layer and query it. Please refer to MOHID Studio User Guide chapter 4 on how to query layers.

View the map results for velocity modulus for the entire domain by opening, in "HDF Files" section, the file "Hydrodynamic_1.hdf5" and select "velocity modulus" in "Feature" field and press "OK". Go to "Map" tab and press play on "Date & Time". This is the map of velocity modulus for the entire domain (Figure 22.10) with a map for each output time.

MOHID Studio - MOHID Water Quick Start Guide v1 10.png
Figure 2 2.9: MOHID Studio time series of velocity modulus for one day in Tagus Channel for Sim # 1 in MOHID Water Samples
MOHID Studio - MOHID Water Quick Start Guide v1 11.png
Figure 2 2.10: MOHID Studio HDF of velocity modulus for Sim #1 in MOHID Water Samples.

To know more on how to customize the time series window (axis titles, series names and colors, etc.) and map images (color scale, horizontal scale, etc.) follow MOHID Studio User Guide chapter 4 and 5.

Creating your own project – Simulating 2D Hydrodynamics forced with tide

This section will show how to start a new project using a simple example of a 2D tide propagation in the Tagus Estuary (the same used in MOHID Water samples). The description can nevertheless be used to implement the model in any study site. One good exercise for a first time user is to try to repeat the sample project following the instructions.

Step 1 – Creating a new MOHID Water Solution and Domain

Create a new Solution going to "Project" ribbon and in group "Solution" pressing "New". It will be prompted to name the solution in "Name of the Solution". Write down for instance "Tagus Sample Redone" without the quotes if redoing the sample project.

Create a new domain going to "Project" ribbon and in group "Domain" pressing "New". The following window will appear (Figure 22.11).

MOHID Studio - MOHID Water Quick Start Guide v1 12.png
Figure 2 2.11: MOHID Studio create new domain.

The information provided in the "Creating a new domain" window characterizes your domain. The following restrictions must be fulfilled:

  • the domain name must be unique;
  • the root directory must be empty.

In "Domain Name" use your location name or for instance "Tagus 200m" in the case of redoing the Tagus sample case since we will create an application where the cell size will be around 200m in the estuary (explained after). Since the domain is linked to a horizontal computational grid (bathymetry) this naming convention is quite handy when handling different resolution grids for the same location.

Browse for a "Root Directory" that is empty and that is located in your computer hard drive (tip: create in your computer a folder per computational grid).

The path to the bathymetry ("Digital Terrain Model") will not be specified for now since it hasn’t been created yet.

Press OK to finish the domain creation.

More information on how to manage solutions and domains can be found in "MOHID Studio User Guide" in chapter 3.

Step 2 – Generate the Bathymetry

In this section it is shown how to generate the bathymetry file. This file defines the horizontal domain (computational grid and bathymetry values for each grid cell) and is the basic and most essential information need to run the simulation ("Sim #1" 2D Tide).

To create a bathymetry file, the following is needed:

  • A horizontal grid. This will be the computational grid for the model and the grid for all the gridded information inputted to the model (spatially distributed).
  • Digital terrain elevation data in point format (XYZ)
  • A polygon containing the areas where the model will not calculate any solution (e.g. land points).

First load a background layer (Bing Aerial or Google Maps) in "Map" ribbon, "Background" group and press "Web Tiles". This layer will help you to identify the study site.

In the case of redoing Tagus sample, zoom in into the study site in Portugal, Lisbon - Figure 22.12.

MOHID Studio - MOHID Water Quick Start Guide v1 13.png
Figure 2 2.12: Lisbon and Tagus estuary area using Bing Aerial as background image.

Horizontal Grid

The Tagus sample was built with a grid of variable resolution to make it more suited to describe in more detail the area of the Tagus channel and save cells. To build this kind of grids it is more suited to use a MOHID tool called Generate Grid[1] even though it can be built also in MOHID Studio (the user has to provide all the x and y distances). To simplify the procedure (variable spacing grids is for advanced options), the exercise will be done with a constant spatial spacing grid.

To process the same area as the Tagus sample grid, open the sample grid for guidance going to "Map" ribbon and in "ASCII" group press "Grid" and open the file "TagusBathymetryGrid.grd" from the folder "General Data\Digital Terrain" of the sample project. See the Tagus sample grid.

To create a constant horizontal grid (all cells with same resolution) go to "Tools" ribbon and in "Grids" group, press "Constant". The "Construct Constant Space Grid" window appears.

  • In section "2. Preview" check "Auto Update" so that all the changes that are done are immediately visible. Leave unchecked if the process is very slow; in that case you will need to press "Refresh" to visualize your changes.
  • In section "1. Grid Parameters" the user may define:
  • An origin (lower left corner coordinate of the grid) by filling "Origin X" and "Origin Y" with geographic coordinates, or, simply pressing "Pick" it may select in the map the origin point. For the Tagus sample case select an origin near the lower left of the provided grid (TagusBathymetryGrid.grd).
  • The number of columns and rows or the number of cells in x and y direction. In the Tagus sample case (variable spaced grid) 145 and 120 were used, respectively, but for the constant grid around 280 and 200 will be needed, respectively[2].
  • Dx and dy or the cell size (in degrees). In the Tagus sample case, a variable resolution was used but in this case use 0.004º in both (around 400mx400m cells).
  • The origin of the grid may be changed at any time. So if your grid is not in the correct position feel free to move it around (press "Pick" and select another origin) and check the result.
  • In section "3. Save Grid" you may save the file if everything is OK, choosing the folder and file name (save it in General Data\Digital Terrain of the new project (and not on sample project). If do not want to save the grid just close the tool.

For the Tagus sample case, the grid should be similar to the one in Figure 22.13.


MOHID Studio - MOHID Water Quick Start Guide v1 14.png
Figure 2 2.13: MOHID Studio constant grid tool for the Tagus sample.

For the Tagus sample case, compare the grid generated with the one used in Tagus Estuary (TagusBathymetryGrid.grd). They are very different in resolution yet the cell size in the Tagus channel is similar.

Digital Elevation Data

Digital elevation of the bottom of the sea usually is not a public resource or if it is has coarse resolution. MOHID Studio has also a conversion tool to process ETOPO[3] 1 arc minute (around 1km in Tagus) elevation data that includes bathymetric data but this resolution is not suitable for the selected horizontal grid resolution.

As so, or the user is intending to simulate a wide area with coarse resolution and may use ETOPO bathymetry or needs to get elevation data for its own study site[4].

For the Tagus case this data is provided in the sample project. Go to "Map" ribbon, "ASCII" group and press in "XYZ Points" and open the file "Tagus_bath_points.xyz" and "PortugueseCoast_bath_points.xyz" in folder General Data\Digital Terrain of the sample project and select "Geographic" coordinates and press "OK". To compare both origins of data it is better if the scales match by right-clicking them and pressing "Properties" and on "Style" section, press "Edit" and change the maximum and minimum to be the same.

No compute areas

This option is used to exclude areas that are land and where the model should not spend time computing. If there are no such areas (open ocean simulation) than this step may be skipped.

The land areas can be obtained from coastlines or draw directly in the map. For the Tagus sample a coastline is provided.

To create a coastline by drawing over the map, go to "Tools" ribbon and in "Geometry Layers" group, press "Polygons". The "Construct Named Polygons" window appears (see Figure 22.14) and in section "1. Define Polygons on Map" press "Draw" and start picking points that define the land boundary and MOHID Studio generates automatically the polygon formed by the points; double-click at the last point to finish the polygon. If want to remove the generated polygon use the "Remove" button in section "2. Defined Polygons". In section "3. Save Polygons" press "Save" and select the folder and filename to save the polygon (save it in General Data\Digital Terrain of the new project and not on the sample project).

MOHID Studio - MOHID Water Quick Start Guide v1 15.png
Figure 2 2.14: MOHID Studio Polygon Tool to select no compute points in Tagus estuary grid (just one polygon for the example, all the land area would need to be comprised in one polygon or several polygons.

For the Tagus sample case, an existent coastline file is used since the land areas are very complex. As so, go to "Map" ribbon, and in "ASCII" group press "Polygon" and open the file "CoastLine.xy" in folder General Data\Digital Terrain from the Tagus sample project and select "Geographic" coordinates and press "OK" (Figure 22.15).

MOHID Studio - MOHID Water Quick Start Guide v1 16.png
Figure 2 2.15: Tagus estuary grid and the line coast that selects land areas not to compute.

Generating the Bathymetry

Finally the generation of the Bathymetry uses all the above steps products: the grid, the elevation points and the no compute areas. The elevation information in points will be interpolated to the grid cells, except in the cells that are inside the no compute polygon.

Go to "Tools" ribbon and in "Grid Data Tools" group press "From Points" (create grid data from points) and "Create Grid Data" window appears (Figure 22.16). In section "1. Select Grid" select the grid that was generated above. In section "2. Non Compute Areas" check the polygon drawn or coastal line; remind that several polygons can be selected. In section "3. Base Information" check "Tagus_bath_points" and "PortugueseCoast_bath_points"; remind that several point sources can be selected.

In section "4. Options" select the method to compute the elevation for each grid cell from point’s collection. When having several points inside each cell (grid is coarser than elevation data) select "Average" and the cell value will be the average of the points inside the grid cell. If the grid has finer resolution than data (some cells do not have any raw information inside), an interpolation algorithm must be used. The user can select select "Triangulation" or "IWD" (inverse weighted distance). In the case of redoing the Tagus sample choose "Triangulation" since in the Tagus coast bathymetric data is sparser than cell resolution.

In section "5. Generate Grid Data" select the folder and filename for the DTM (save it in General Data\Digital Terrain of the new project and not on the sample project). Press the "Process" button to generate the bathymetry and after a while the process ends and produces the bathymetry file.

MOHID Studio - MOHID Water Quick Start Guide v1 17.png
Figure 2 2.16: MOHID Studio Grid Data from points Tool to create a bathymetry.

For the Tagus case, compare the bathymetry generated with the one used in Tagus estuary (TagusBathymetry.dat) in folder General Data\Digital Terrain of the sample project.

Step 3 – Generate Tide

One of the main drivers for water circulation in coastal areas is tide and in the first simulation that is the only forcing agent.

FES (finite element solution) tide model is the most common source of tidal components being available for the entire world which the most recent model version is FES2012 and previous version is FS2004. MOHID Studio incorporates a tool to obtain tidal component from FES2004 and in the future will have it updated for the most recent version.

Please note that for MOHID Studio version 1.2.7 the Tidal Tool is installed external as external plugin. Please follow the link below to install this plugin.

http://www.actionmodulers.pt/default.aspx?canal=95

For the Tagus sample only a tidal gauge will be used (extracted from FES2004) since the objective is to explain the main processes and the user may skip this step. However, the user should do their implementations always using the tool which steps are described next.

Before start using the Tidal Tool, the user should load the bathymetry for instance if not already loaded (previous step).

Go to "Tools" ribbon and press "Tidal Tool" and the Tidal Tool window will appear (see Figure 22 2.17). This tool is divided under 3 sections: 1 – Define points on map; 2- Selected grid points; 3 – Config tide.

MOHID Studio - MOHID Water Quick Start Guide v1 18.png
Figure 2 2 2.17: Tidal Tool window

The first step to use this tool, is to define the points on Map. Click on the "Draw" button (the button will turn orange) and then click on the map to draw the points (see Figure 22 2.18). The points should be drawn on the boundaries of the working layer in zig-zag, like the ones shown on the example on the Figure 22 2.19.

Each time the mouse is pressed a new blue marker will appear on the map and a new line is added to the table (see Figure 22 2.18). Each line represents a single point, with the coordinates of each point and name (by default the point number is incremented: Point_1, Point_2, and so on). The decimal places for the X and Y coordinate values can be changed on panel 1 (by default the decimal places are 4).

MOHID Studio - MOHID Water Quick Start Guide v1 19.png
Figure 2 2 2.18: Tidal Tool plugin – Drawing points (start.
MOHID Studio - MOHID Water Quick Start Guide v1 20.png
Figure 2 2 2.19: Tidal Tool plugin – Draw points (end.

The user can remove a single point, by selecting a single line and pressing the "Remove" button. The "Clear List" button will erase all points from the table.

The panel 3 is for the tide configurations (see Figure 22 2.20). First select the path to the "tide.nc" file[5]. Select the time reference value (Time Ref) and the reference level value (Ref Level). Select also the path and name for the output file. The path and name for XYZ file is optional. If the filename is empty, the XYZ file will not be saved.

The reference level is the mean sea level (measured from the origin of the bathymetry upwards) obtained from tidal gauges in the area (in Tagus the mean sea level is 2.08m above bathymetric zero). The FES tide solution is in Greenwich Meridian Time (GMT) so need to adapt to your area using time reference (e.g. Spain is 1 (+1) and will be negative trough the west).

MOHID Studio - MOHID Water Quick Start Guide v1 21.png
Figure 2 2 2.20: Tidal Tool – Configurations.

To generate the tide file (the output file) just press the button "Process".

Step 4 – Create a new simulation

The latter steps (create the bathymetry and tide) are the most basic steps to implement a coastal project. So now the first simulation can be created, a 2D model with tide, redoing the "Sim #1" from Tagus sample.

On "Explorer" tab, select the Domain name and go to "Project" ribbon and in "Simulation" group press "New". Name your simulation (e.g. Sim #1 2D Tide), and Press "OK" when finished to have the new simulation ready - Figure 22.21 .

MOHID Studio - MOHID Water Quick Start Guide v1 22.png
Figure 2 2.21: MOHID Studio New Simulation.

Step 4 – Define the simulation

Selecting the just created simulation shows that the simulation has several input files listed in the "Modules" section and in "Data Files". These files should have all the options needed to run the model including the tide forcing, the main options to run, etc.

All this info is hard to construct from scratch every time a new project is implemented so it is recommended to adapt the settings from an already existing project.

Since there is no other simulation to copy from, to do a copy of the settings you need to add to your solution another domain. Select your solution and go to "Project" ribbon and in "Domain" group press "Open". Choose from the list the "Tagus Sample" or other project if you have one that you want to copy from. The selected project will appear under the same solution.

To copy the simulation files, select the simulation to copy from (if the domain just added is Tagus sample select the "Sim #1 2D Tide") and go to "Project" ribbon and in "Simulation" group, press "Copy". The copy window appears and lets you choose which files from the origin simulation to copy and select the destination simulation (Figure 22.22).

MOHID Studio - MOHID Water Quick Start Guide v1 23.png
Figure 2 2.22: MOHID Studio copy simulations between domains.

Leave the origin unchanged but select the destination simulation (inside your new domain select the correct simulation). Press "Copy" and after "OK". This will copy all the settings from the origin simulation to the destination. Now some verifications need to occur to ensure that you fill in the data you created (see next steps).

After you are done copying you can remove the added domain from the solution, selecting it and going to "Project" ribbon, "Domain" group and pressing "Remove". This action does not delete the domain from the disk, it just removes the domain from the solution that is virtual. In the case of redoing Tagus sample its files will be needed in the next simulations, so leave it for now.

Step 4.1 – Define Bathymetry for the project

The bathymetry is a property of the domain and remains the same for all simulations so it’s defined in the domain options. Edit the domain properties by selecting it, right-clicking and selecting "Properties". In The "Digital Terrain Model" browse for the bathymetry file created in the previous steps - Figure 22.23 (this image is for Tagus sample but is similar to any project).

MOHID Studio - MOHID Water Quick Start Guide v1 24.png
Figure 2 2.23: MOHID Studio Domain Properties where bathymetry is defined.
Step 4.2 – Define simulation start and end in Model file

The simulation start, end and time step related info is inputted in file Model_X.dat where is X is the simulation number. This file is on "Explorer" tab, under "Modules" and in "Data Files" section.

The start and end dates are identified with keywords "START" and "END" and the format is year, month, day, hour, minute and second integer numbers separated by spaces.

The keyword DT defines the model time step.

The keyword "GMTREFERENCE" is the same as the time reference in tide. If running the model in a place other than in GTM + 0 than need to edit accordingly (positive to east and negative to west).

All these keywords can be edited but if redoing the simulation from Tagus leave it as is.

Step 4.3 – Define gauges tidal components in Tide file

The information on the tidal components with info separated by gauges is inputted in file Tide_X.dat where is X is the simulation number. This file is on "Explorer" tab, under "Modules" and in "Data Files" section.

The tide file can be taken directly from tide tool (just copy the output of the tide tool to this file).

If redoing the Tagus sample, only one gauge is used and can be left as is.

Step 4.4 – Define vertical discretization in Geometry file

The definition of vertical layers is inputted in file Geometry_X.dat where is X is the simulation number. This file is on "Explorer" tab, under "Modules" and in "Data Files" section.

If redoing the Tagus sample or any 2D simulation only one domain and one layer exists (keyword LAYERS is 1) and since it is a type SIGMA the thickness (keyword LAYERTHICKNESS) is defined in percentage of depth and value is 1 (100%). Leave this file unchanged for the Tagus case.

Step 4.4 – Define hydrodynamic options in Hydrodynamic file

The hydrodynamic options to run (which forcing to consider) is inputted in file Turbulence_X.dat where is X is the simulation number. This file is on "Explorer" tab, under "Modules" and in "Data Files" section.

Since this simulation is for considering only tide than the keyword TIDE is connected (1) and water discharges or wind will not be accounted for computing velocity.

Step 4.5 – Define turbulence parameters in Turbulence file

The horizontal and vertical viscosity is inputted in file Turbulence_X.dat where is X is the simulation number. This file is on "Explorer" tab, under "Modules" and in "Data Files" section.

The viscosity represents the mixture or diffusion associated to processes not taken into account in cell average velocity (called turbulence) and so it depends on the mesh used and units are m2/s and represent a turbulent velocity (m/s) multiplied by mixture length (m). For a 2D simulation the vertical viscosity is not used (no vertical movement) and to estimate the horizontal viscosity use a turbulent velocity (usually a percentage of average velocity) and multiply by the cell size. In the Tagus case a representative average velocity is 0.5 m/s and if the turbulent velocity is around 10% of the average then it is around 0.05 m/s. For this case of using a grid with around 400m cell then the estimated viscosity will be 20 m2/s (0.05 m/s * 400 m).

For other study cases estimate the horizontal viscosity accordingly. The objective here is to have an order of magnitude since small variations do not influence greatly results.

Step 4.6 – Other Files

Other files as Atmosphere_X.dat, InterfaceWaterAir_X.dat and WaterProperties_X.dat are empty because are not used in this simulation. These files are on "Explorer" tab, under "Modules" and in "Data Files" section.

File InterfaceSedimentWater_X.dat takes into account the bottom of the domain and a rugosity is defined to compute shear.

These files do not need to be changed.

Step 4.7 – Define Output

The last thing to take into account before running the simulation is where to place time series output and its frequency and what should be the HDF maps frequency. This info is transversal to almost all the data files (all that have output) and to create times series follow the instructions in MOHID Studio User Guide in chapter 6.6. Hint: Save the time series file in General Data\TimeSeries (create it).

In the case of redoing the simulation from Tagus since the grid is not exactly the original the process needs to be redone using the same stations.

  • Open the location of the stations in "Map" ribbon and in "Vector Data" group press "XML" and open the file "TimeSeriesLocation.xml" from the folder General Data\TimeSeries in the Tagus sample project and define "Geographic" coordinates.
  • If you want to maintain the same time series names (some will be used after) do a query on the station (see MOHID Studio User Guide chapter 4 on how to query) and write down the names.
  • Go to "Tools" ribbon and in "Time Series" group press "Grid Locations". Follow the instruction from MOHID Studio User Guide and pick points at the same locations as the Tagus sample and name them the same. Save the file in the folder General Data\TimeSeries on the new project (create it). Name it, for example, TimeSeriesLocation.dat.

The path to the file just created (e.g. TimeSeriesLocation.dat) needs to be updated in each data file that has output with a keyword TIME_SERIE_LOCATION. It this example will be used only in Hydrodynamic_X.dat and check that the path is correct.

The time series frequency is defined inside the created file (e.g. TimeSeriesLocation.dat) with the keyword DT_OUTPUT_TIME (in seconds).

The HDF frequency of output is given in the Modules data files that have output by the keyword OUTPUT_TIME (in seconds). In this case only in Hydrodynamic_X.dat.

Always verify if the frequency of output is correct given the simulation period. Usually time series are not very time consuming and do not generate huge result files but for HDF outputs, if the frequency is too high, it may make the model run slower and generate huge files that are difficult to manage.

Step 5 – Run the simulation and explore results

Everything now is prepared to run the simulation. Verify one last time that all the paths defined inside the data files exist and that the DTM was defined in the domain. Follow the same instructions as in the previous simulation to run and to explore the results.

If the simulation does not end successfully and the output window says that isolated horizontal grid cells occurred and a new bathymetry was created (usually appended "_v01" to the file name) then replace the bathymetry of the project with the new one and rerun the model.

The results of this simulation should be very similar to the Tagus sample simulation #1 (Figure 22.24) despite the grid is not the same.

MOHID Studio - MOHID Water Quick Start Guide v1 25.png
Figure 2 2.24: Tagus 2D velocity modulus in redone simulation.

Retouching the Bathymetry

This is an advanced processing option that will not be needed in the sample case. However, in coarse horizontal grids or coarse data, high changes in bathymetry values may occur (usually in intertidal areas) that can create numerical instabilities. When this happens a message like "Instability in Thomas Algorithm" can appear in the model output window (or log). In this case check where the velocity fields are inconsistently high (open the HDF with velocity modulus that will show results up to model became unstable) and check if there are inconsistencies in the bathymetry in the surrounding grid cells.

Inspect the bathymetry changing the color scale to define all the small channels in intertidal areas and verify that big changes in depth do not occur that can make the model unstable. For some cases, you can use an auxiliary MOHID tool called FilterBathymetry[6] that can smooth the bathymetry and can be useful to automatically solve some of these problems.

Creating your own project – Simulating 3D hydrodynamics forced with tide, river discharge and meteorology

This simulation, in relation to the latter, adds more vertical layers, introduces river discharges, and adds meteorology and water properties (temperature and salinity).

It will be referred to the MOHID Studio User Guide more often since this simulation is more advanced and it is assumed that the user is now comfortable in exploring MOHID Studio. If not that comfortable, please try to apply the model to other places than the Tagus on your own, using the last simulation description.

Step 1 – Get Meteorology and River Discharges

To run the complete hydrodynamics simulation you need to define river input and meteorology forcing. Meteorology and river input can be given in time series or HDF format (but constant values can also be imposed). For the Tagus sample, meteorology data is supplied in time series format and river input is constant (short simulations).

Step 1.1 - Get data into MOHID Time Series format

The meteorological data needed by the model comprises air temperature, solar radiation, wind velocity and direction and relative humidity, thus these files must be created before the model execution.

Follow instructions in MOHID Studio User Guide in chapter 10.1 to understand MOHID format for time series[7].

If redoing the Tagus case copy the atmosphere file (AtmophereData.dat) from the folder General Data\Boundary Conditions in the sample project to your project in the same location.

After the time series files are created they can be referred in the Atmosphere_X.dat (see below).

Step 1.2 – Define discharges locations

Since this simulation does not have the same computational grid as the sample, the discharges location needs to be changed. There will be two discharges with reference to the two main rivers (Tagus on north and Sorraia east) presented in Figure 22.25 (in "Map" ribbon and in "Vector Data" group, press "XML" and open file RiverDischarges.xml in folder General Data\Boundary Conditions of the sample case). Notice that the Sorraia discharge appears to be inside the estuary because the computational grid at the Sorraia entrance is not so well defined.

MOHID Studio - MOHID Water Quick Start Guide v1 26.png
Figure 2 2.25: Location of the discharges in the new grid.

In order to define in which grid cell the river discharge will be placed, open the bathymetry ("Map" ribbon and in "ASCII" group press "Grid Data" and open the file from folder General Data\Digital Terrain from your project). Then query the file and select the cells where the discharge should be done (using RiverDischarges locations). Get the "I" and "J" and write down the info that will be used later.

Step 1.3 – Define flow and property discharged

After the location, define the flow discharged and properties discharged (constant or time series) from data or any other assumption. The water properties present in the discharge must be present in the list of accepted water properties names MOHID[8]. If redoing the Tagus sample a constant flow will be used and the discharge of temperature and salinity will be based on average known values.

Step 2 – Create a new simulation (copy a previous)

As said before, new simulations should be copied from others so that the settings are predefined. In this case create a new simulation as before and in the process add Module Discharges and Module GOTM (Figure 22.26).

MOHID Studio - MOHID Water Quick Start Guide v1 27.png
Figure 2 2.26: MOHID Studio add new simulation. In this case added Discharges and GOTM.

Copy the files from the previous simulation to this one so some of the info is already filled.

Step 3 - Define the simulation

Comparing with the last simulation, the main differences are that there will be a more realistic atmospheric forcing (using measured data) and the river discharges will be considered.

Step 3.1 – Define Atmosphere file and InterfaceWaterAir

Copy only the atmosphere data file from the Tagus sample from Sim #2 since it is similar to the one needed because it has all the atmospheric properties blocks with data being read from time series files.

Modify the time series file paths for precipitation, solar radiation, air temperature, relative humidity and wind velocity to the ones that were prepared. In the case of redoing Tagus sample this is not necessary since the files were already copied to the same location.

To change from defining a property as having a constant value to being read from a time series file is straightforward in MOHID using the keyword FILE_IN_TIME. When setting the property values as constant, the keyword value should be NONE and the value is read in keyword DEFAULTVALUE and keyword REMAIN_CONSTANT should be 1. In case of reading from a time series file, the keyword FILE_IN_TIME value should be TIMESERIE and keywords FILENAME and DATA_COLUMN need to be defined (the path to the file and the data column inside the file, respectively).

Copy only the InterfaceWaterAir data file from the Tagus sample from Sim #2 since it is similar to the needed because it has all the atmospheric fluxes needed. This properties do not need to be defined (but can be) and in this case the model will compute them (e.g. the heat fluxes trough the surface water).

Step 3.2 – Define Discharges file with discharged flow and properties

Copy only the Discharges data file from the Tagus sample in Sim #2 to this simulation. This example has 2 discharges with temperature and salinity (Tagus and Sorraia).

Update the number of discharges you want to make and change cell discharges locations (keywords I_CELL and J_CELL) accordingly. Update also discharges names (keyword NAME).

In case of redoing the Tagus case you need to update the I_CELL and J_CELL with the info collected because the grid in the samples is different from the newly generated grid.

Update discharge flow values. If using constant flow define it in keyword DEFAULT_FLOW_VALUE in each discharge and remove keyword DATA_BASE_FILE. If using variable flows values (read from a times series file) use the latter keyword to point to the corresponding file in MOHID time series format and FLOW_COLUMN to select which column the flow values are. In case of redoing the Tagus sample this is not needed.

Adapt the properties blocks and properties discharge concentrations according to your data.

Step 3.3 – Define vertical discretization in Geometry file

Copy only the Geometry data file from the Tagus sample in Sim #2 to this simulation.

In order to define a 3D computational domain simply define more than one layer (keyword LAYERS) and in order to set the thickness of each vertical layer, use keyword LAYERTHICKNESS. Since a SIGMA type coordinate is being used, the thickness is defined as percentage of water column height and a value of 1 (100%) has to be obtained when summing all the layers thicknesses.

The 3D domain presented in the Tagus sample is only for exemplification and is very simple with reduced number of layers (only 3) that usually is not enough for describing vertical gradients in coastal areas or estuaries. For coastal cases it is suggested to use two domains one CARTESIAN near the bottom and one SIGMA near the changing surface and the number of layers depend on the depth and the precision needed to simulate for instance stratification[9].

If redoing the Tagus sample leave this file unchanged.

Step 3.4 – Define Hydrodynamic file

Copy only the Hydrodynamic data file from the Tagus sample in Sim #2 to this simulation.

As seen with the new options of introducing discharges and atmosphere the velocities will be forced with this new processes and so in the Hydrodynamic_X.dat has the keywords WIND and WATER_DISCHARGES connected.

Step 3.5 – Define Turbulence and GOTM files

Copy only the Turbulence data file from the Tagus sample in Sim #2 to this simulation.

In the case of a 3D model the vertical turbulence should not be constant but computed so a new model is called to compute it as seen in the copied file (turbulence_equation whether other methods may be used). This model is GOTM[10] that is code developed outside MOHID and that was included in the package. This model has a data file (GOTM.dat) that should be not changed.

Copy only the GOTM data file from the Tagus sample in Sim #2 to this simulation and just leave it, it includes parameters for the turbulence computation.

Step 3.5 – Define Water Properties file

Copy only the Water Properties data file from the Tagus sample in Sim #2 to this simulation.

The water properties file defines which properties are to be considered and if they will be transported (keyword ADVECTION_DIFFUSION has value 1) or if they will have discharges associated (keyword DISCHARGES has value 1).

If redoing the Tagus sample leave the file unchanged. The properties in this case instead of being initialized as constant everywhere are initialized by boxes (keyword INITIALIZATION_METHOD value is not CONSTANT but BOXES) meaning that the cells belonging to each box will have different values. This was done since the simulations are very short to make the initial conditions closer to reality where in the upper estuary lower salinity and higher temperature exists. Because of this initialization and since the grid of the redone project is different from the sample, need to regenerate the boxes in the new grid:

  • Copy the folder General Data\Boxes in the sample project to the new project. Open the polygon with boxes geometry in "Map" ribbon and in "Vector Data" group press "XML" and open the file Boxes_reduced.xml in folder General Data\Boxes of the new project tab.
  • Open the tool to generate boxes from polygon in "Tools" ribbon and in "Grid Data Tools" group press "Create Boxes" and the "Create Boxes" window appears (Figure 22.27).
  • In the section "1. Select Grid Data" select the bathymetry; in section "2. Select Polygons" select the Boxes_reduced and on section "4. Generate Boxes File" browse where to place the file (place the file in folder General Data\Boxes of the new project and name it Boxes.dat so that no change is needed in the WaterProperties.dat) and press "Process".
MOHID Studio - MOHID Water Quick Start Guide v1 28.png
Figure 2 2.27: MOHID Studio Create Boxes.

If doing another project, disconnect the boxes initialization (revert INITIALIZATION_METHOD to CONSTANT) or create your own boxes (follow the above steps where the polygon files defining boxes have to be created).

Step 4 – Run the simulation and explore results

Everything now is prepared to run the simulation. Verify one last time that all the paths defined inside the data files exist, that output frequency (time series and HDF) in each file is correct for the simulation period and that the bathymetry was defined in the domain. Follow the same instructions as in the previous simulation to run and to explore the results. New results are available as Water Properties HDF or time series (.srw).

Figure 22.28 presents the temperature map in one instant result of opening the WaterProperties.hdf5 and selecting property "temperature" to plot.

MOHID Studio - MOHID Water Quick Start Guide v1 29.png
Figure 2 2.28: Tagus temperature at surface for 3D simulation with tide, river discharge and atmospheric forcing.

If the model crashes with errors about floating invalid in Module Functions and Module WaterProperties as in Figure 22.29, than probably exist cells that are isolated where discharges are occurring or the intertidal channels are poorly defined and need to have a smoother bathymetry. Follow the steps indicated in the previous simulation to fix the bathymetry.

MOHID Studio - MOHID Water Quick Start Guide v1 30.png
Figure 2 2.29: Log message with model crashed when computing density in Module Functions. Below "PC" refers to code line (line numbers may vary depending on executable version).

Creating your own project - Simulating sediment transport

To simulate sediment transport the property cohesive sediment needs to exist in the Module InterfaceSedimentWater (bottom mass) and in Module WaterProperties (water column concentration) and the parameters associated (critical shear for stress, critical shear for deposition, erosion rate) need to be defined.

Step 1 – Create a new simulation (copy a previous)

As said before new simulations should be copied from others so that the settings are predefined. In this case create a new simulation as before, adding the Module Discharges, Module GOTM, Module FreeVerticalMovement and copy the files from the previous simulation to this one so some of the info is already filled.

Step 2 - Define the simulation

The difference from the last simulation is that cohesive sediment property has to be added in Module InterfaceSedimentWater and to WaterProperties and the vertical velocity computation adding FreeVerticalMovement. And it was also added the cohesive sediment property in the river discharges.

Step 2.1 – Add cohesive sediment property and parameters in InterfaceSedimentWater file

Copy only the InterfaceSedimentWater data file from the Tagus sample in Sim #3 to this simulation. Verify that the difference was the property block with cohesive sediment that was added. This block defines the initial cohesive sediment concentration everywhere in the bottom in kg/m2 (if any in the beginning) in keyword DEFAULTVALUE (because keyword INITIALIZATION_METHOD value is set to CONSTANT). It is also defined the critical shear stress for erosion, over which erosion occurs in block "begin_critical_shear_erosion", the critical shear stress for deposition, below which deposition occurs in block "begin_critical_shear_deposition", erodibility in block "begin_erosion_rate". All these parameters should be calibrated for the place in question.

Step 2.2 – Define cohesive sediment property vertical velocity in FreeVerticalMovement file

Copy only the FreeVerticalMovement data file from the Tagus sample in Sim #3 to this simulation. Verify that that the fall velocity is defined in keyword WS_VALUE. All these parameters should be calibrated for the place in question.

Step 2.3 – Add cohesive sediment property in Discharges file

Copy only the Discharges data file from the Tagus sample in Sim #3 to this simulation. Verify that that the property cohesive sediment was added to the river discharges to be discharged as well as temperature and salinity.

If redoing the Tagus case need to change the location of the river discharges (I_CELL and J_CELL) to the new grid as done in the previous simulation because the new grid is different from the Tagus sample.

Step 2.4 – Add cohesive sediment property in Water Properties file

Copy only the WaterProperties data file from the Tagus sample in Sim #3 to this simulation. Verify that property cohesive sediment was added and initialized the same way as the others since the sediment concentration is usually higher in the upper estuary. Also the keyword DISCHARGES was connected to allow the concentration to be updated by discharges in discharge file (if any discharged the property).

Step 3 – Run the simulation and explore results

Everything now is prepared to run the simulation. Verify one last time that all the paths defined inside the data files exist, that output frequency (time series and HDF) in each file is correct for the simulation period and that the bathymetry file (digital terrain model) was defined in the domain. Follow the same instructions as in the previous simulation to run and to explore the results. New results of cohesive sediment are available in WaterProperties HDF or in time series (.srw).

Figure 22.30 presents the cohesive sediment map in one instant result of opening the WaterProperties.hdf5 and selecting property "cohesive sediment" to plot.

MOHID Studio - MOHID Water Quick Start Guide v1 31.png
Figure 2 2.30: Tagus cohesive sediment at surface for 3D simulation with tide, river discharge and atmospheric forcing.

Creating your own project - Simulating point discharges

Simulating waste water treatment plants point discharges (WWTP) is very similar to simulating river discharges where the new points can be added to the Discharge file as well as the correspondent flow and concentrations values. The novelty here is that point sources discharges can also be simulated using the Lagrangian approach. This approach instead of using a computational grid to compute contaminant concentrations uses the concept of Lagrangian tracers, which consists of simulating small independent portions of water and its constituents, which move due to the current velocities computed on the Eulerian grid. This approach is particularly relevant when simulating processes where high concentration gradients exist, which is the case for WWTP discharges in terms of fecal contamination. In this case, a first order decay of fecal contamination is also computed (based on temperature, salinity and radiation).

The particle source and fate is defined in the Module Lagrangian that needs to be connected and edited.

Step 1 – Define the point discharges

Step 1.1 – Define discharges locations

There are two options to define the location: i) by its coordinates or ii) by the grid cell. If the coordinates are known write down them to be used later and skip to the next step.

If the coordinates are not known the user may use the grid coordinates. To do that, open the bathymetry file ("Map" ribbon and in "ASCII" group press "Grid Data" and open the file from folder General Data\Digital Terrain). Then query the bathymetry and select the cells where the discharge is located. Get the "I" and "J" and write down the info that will be used later.

If redoing the Tagus case, get the cells where the discharges are located in "Map" ribbon and in "Vector Data" group, press "XML" and open file WWTPDischarges.xml in folder General Data\Boundary Conditions of the sample case. The south discharge is Alcantara and the north one Beirolas. Query the bathymetry and write down the cell for the discharge.

Remind that the location for Lagrangian discharge coordinate first is J and then I and have to reduce one index in the J and I (see Tagus sample and the difference between location in Discharge data file and in Lagrangian data file).

MOHID Studio - MOHID Water Quick Start Guide v1 32.png
Figure 2 2.31: Location of the WWTP discharges in the Tagus sample.
Step 1.2 – Define flow and property

After defining the discharge location, setup the discharge flow and water properties concentrations (constant or read from time series). The discharged water properties name must be present in the list of accepted names in MOHID[11]. In the case of Tagus sample, arbitrary constant values were used.

Step 2 – Create a new simulation (copy a previous)

As said before, new simulations should be copied from others so that the settings are predefined. In this case create a new simulation as before and add Module Discharges, Module GOTM, Module FreeVerticalMovement and Module Lagrangian,

Copy the files from the previous simulation to this one, so some of the info is already filled.

Step 3 - Define the simulation

Step 3.1 – Define Discharges file with discharged flow and properties

Copy only the Discharges data file from the Tagus sample in Sim #4 to this simulation. This example has 2 new discharges with temperature, salinity, ammonia, inorganic phosphorus and cohesive sediment.

Update the number of discharges you want to make and change cell discharges locations (keywords I_CELL and J_CELL) accordingly. Update also discharges names (keyword NAME).

In case of redoing the Tagus case you need to update the I_CELL and J_CELL with the info collected because the grid in the samples is different from the newly generated grid.

Update discharge flow values. If using constant flow define it in keyword DEFAULT_FLOW_VALUE in each discharge and remove keyword DATA_BASE_FILE. If using variable flows values (read from a times series file) use the latter keyword to point to the corresponding file in MOHID time series format and FLOW_COLUMN to select which column the flow values are. In case of redoing the Tagus sample this is not needed.

Adapt the properties blocks and properties discharge concentrations according to your data.

If redoing the Tagus sample you also need to change the location of the river discharges (I_CELL and J_CELL) to the new grid as done in the previous simulation, because the new grid is different from the Tagus sample.

Step 3.2 – Define in WaterProperties file discharged properties

Copy only the WaterProperties data file from the Tagus sample in Sim #4 to this simulation. Verify that the ammonia and inorganic phosphorus properties were added and have keyword DISCHARGES set to 1 (so that the discharge of property is considered). If any property had the DISCHARGES set to 0 and the property is discharged than only flow (dilution) would affect the property concentration and the discharge concentration would be the same as being zero for that property. These new properties are initialized as constant (keyword INITIALIZATION_METHOD is set to CONSTANT).

Step 3.3 – Define the Lagrangian discharge

Copy only the Lagrangian data file and the Model data file from the Tagus sample in Sim #4 to this simulation.

Check that keyword LAGRANGIAN is set to 1 in Model input data file, so that the Lagrangian module is activated.

The Lagrangian data file defines the location of the sources by two options to define the location: i) by its coordinates with keyword POSITION_COORDINATES or ii) by the grid cell with keyword POSITION_CELLS. Fill here the location of the discharge collected in the previous step. Remind that for the POSITION_CELLS case, position is given by J I (and not I and J as usual) and that in each coordinate needs to subtract one cell in I and in J.

The Lagrangian data file also defines the type of source in spatial (keyword EMISSION_SPATIAL) and temporal scales (keyword EMISSION_TEMPORAL) and flow associated (keyword FLOW)[12].

For each point source the discharged water properties are also defined.

Step 4 – Run the simulation and explore results

Everything now is prepared to run the simulation. Verify one last time that all the paths defined inside the data files exist, that output frequency (time series and HDF) in each file is correct for the simulation period and that the bathymetry was defined in the domain. Follow the same instructions as in the previous simulation to run and to explore the results. New results are available as Lagrangian HDF that cannot be opened with double clicking but right-clicking and selecting "Add Lagrangian".

Figure 22.32 presents the fecal coliform property in Lagrangian particles map in one instant result of opening the Lagrangian.hdf5 and selecting property "fecal coliform" to plot.

MOHID Studio - MOHID Water Quick Start Guide v1 33.png
Figure 2 2.32: Tagus fecal coliform for 3D simulation with tide, river discharge atmospheric forcing and WWTP discharge (arbitrary discharge, just for exemplification).

Creating your own project - Simulating nutrient transport and transformation (nutrient cycles)

This simulation represents one the most complete simulation with nutrient cycle using the most of the Modules in MOHID Water.

The simulation of nutrient transport was already presented in the previous simulation. The novelty here is the nutrient cycling in the water through the use of Module WaterQuality (algal activity including assimilation, respiration, mortality and grazing and bacterial activity including mineralization, nitrification, denitrification, etc.) and sediment biogeochemical processes using Module Benthos[13].

Step 1 – Create a new simulation (copy a previous)

As said before new simulations should be copied from others so that the settings are predefined. In this case, create a new simulation as before and add Module Discharges, Module GOTM, Module FreeVerticalMovement, Module Lagrangian, Module WaterQuality and Module Benthos.

Copy the files from the previous simulation to this one so some of the info is already filled.

Step 2 - Define the simulation

Step 2.1 - Add to Water Properties file the properties needed to run the water quality models

Copy only the WaterProperties data file from the Tagus sample in Sim #5 to this simulation. Verify that a lot of properties were added (the properties needed to run Water Quality) and the most part has the keyword WATER_QUALITY set to 1 so that the water quality model may change the concentration due to algal and bacterial activity.

Step 2.2 - Add WaterQuality file with defined rates

Copy only the WaterQuality data file from the Tagus sample in Sim #5 to this simulation. In this file you can find the main options to compute and the biogeochemical processes rates and parameters. All these parameters should be calibrated for your case study.

Step 2.3 - Add to InterfaceSedimentWater file the properties needed to run the quality models

Copy only the InterfaceSedimentWater data file from the Tagus sample in Sim #5 to this simulation. Verify that a lot of properties were added (the particulated properties needed to run WaterQuality and the dissolved ones needed to run Benthos) and some have the keyword BENTHOS set to 1 and WATER_FLUXES to 1 so that the water quality model may be influenced by processes occurring on the deposited sediments.

Step 2.4 - Add Benthos file with defined rates

Copy only the Benthos data file from the Tagus sample in Sim #5 to this simulation. In this file are the main options to compute (which species to compute) and the maximum rates (without limitations) for each process. All these parameters should be calibrated for your case study.

Step 2.6 – Define Other Files

Copy only the InterfaceWaterAir data file and Discharges data file and FreeVerticalMovement from the Tagus sample in Sim #5 to this simulation. In the InterfaceWaterAir input file, the oxygen flux was added, so that reaeration processes are computed, and that in the Discharges input file all the water properties included in the water quality processes are now defined. In the FreeVerticalMovement file, the particulate properties added to the WaterProperties file were also defined here, along with the corresponding settling velocity.

If redoing the Tagus sample you also need to change the location of the river discharges and WWTP discharges (I_CELL and J_CELL) to the new grid as done in the previous simulation because the new grid is different from the Tagus sample.

Step 3 – Run the simulation and explore results

Everything now is prepared to run the simulation. Verify one last time that all the file paths defined inside the data files exist, that output frequency (time series and HDF) in each file is correct for the simulation period and that the bathymetry was defined in the domain properties. Follow the same instructions as in the previous simulation to run and to explore the results. New properties exist in the water properties HDF and in time series (.srw).

Figure 22.33 presents the phytoplankton property in water properties map in one instant result of opening the WaterProperties.hdf5 and selecting property "phytoplankton" to plot.

MOHID Studio - MOHID Water Quick Start Guide v1 34.png
Figure 2 2.33: Tagus phytoplankton for 3D simulation with tide, river discharge atmospheric forcing and WWTP discharge and water quality processes.

Final Remarks

This quick start-guide to implement MOHID Water intends to help first time users to quickly get the model running but may also be a starting point for every new implementation. The implementation of MOHID Water in these terms, with increasing complexity and processes added in cumulative way, gives user the sensibility to the major factors affecting circulation and water quality for each implementation site.

Any difficulties or need for more developed information should be addressed in the MOHID channels mentioned at the start of this document.

We appreciate all feed-back that you may give us on the implementation of MOHID Water projects with MOHID Studio so that this guide can improve with time.


  1. Download the tool from www.mohid.com and follow instructions here: http://wiki.mohid.com/wiki/index.php?title=GenerateGrid
  2. This is the advantage of the variable resolution grids to save cell number, focusing higher resolution on the interest area.
  3. In "File Conversion" ribbon, "DTM datasets" an "ETOPO"
  4. To convert your data into MOHID points format (XYZ), explore MOHID Studio User Guide, chapter 10 to understand the format.
  5. The file should be downloaded here: ftp://ftp.legos.obs-mip.fr/pub/soa/maree/tide_model/global_solution/fes2004/tide/tide.fes2004.nc
  6. The filter bathymetry tool can be downloaded in www.mohid.com and instructions in http://wiki.mohid.com/wiki/index.php?title=FilterBathymetry
  7. Hint: if you have the time series data in a spreadsheet to get the time column in days just subtract every date to the reference date.
  8. See a list of recognized properties in MOHID in http://wiki.mohid.com/wiki/index.php?title=Properties_names.
  9. For more information visit http://wiki.mohid.com/wiki/index.php?title=Module_Geometry
  10. For more information visit http://wiki.mohid.com/wiki/index.php?title=Module_GOTM
  11. See a list of recognized properties in MOHID in http://wiki.mohid.com/wiki/index.php?title=Properties_names.
  12. For more info visit http://wiki.mohid.com/wiki/index.php?title=Module_Lagrangian
  13. To learn more about these processes visit http://wiki.mohid.com/wiki/index.php?title=Module_WaterQuality for Water Quality http://wiki.mohid.com/wiki/index.php?title=Module_Benthos for Benthos.