Tutorial M06
| USEFUL LINKS | ||
| Wiki Links | Help | Downloads |
| TUFLOW FV Wiki Main Page | Products Support/Contact | TUFLOW FV Downloads |
| TUFLOW FV Tutorials | Requesting a Licence | Tutorial Module Data |
| TUFLOW Classic/HPC Wiki | TUFLOW FV Glossary | Manuals |
Tutorial Description
The TUFLOW Particle Tracking (PT) Module allows the 2D or 3D simulation of discrete Lagrangian particles as they are transported by the flow field (or other drivers such as wind or waves). Particle behavior such as settling, buoyancy, decay, sedimentation and re-suspension can all be simulated. The tracking of discrete particles can be used to output particle fate and age, which is useful for purposes of animal migration, search and rescue, environmental contaminants and oil spill modelling.
The PT Module is invoked through the TUFLOW FV hydrodynamic engine which controls the overall simulation and supplies the hydrodynamic forcing to the PT Module.
The tutorial will cover a number of aspects of the PT Module:
Tutorial Module Data Download
The tutorial data from which to work from, as well as a set of completed model files should be downloaded from the TUFLOW Website.
Tutorial Pre-Requisites
For the purposes of the Particle Tracking Module tutorial, we'll be using the hydrodynamic model created in Tutorial Module 5 (Estuary Application) and supplementing with additional information to represent the particles.
Setting up a Point Source of a Group of Particles
Creating a .FVPTM file
The first step in the TUFLOW FV PT Module is to generate an .fvptm file which defines the commands to define particle characteristics and processes. This .fvptm file is then referenced via the TUFLOW FV control file (.fvc).
Use your preferred text editor to create a new file with extension .fvptm. Name the file PT_000 and save in the runs folder.
Add the following commands to define a group of particles representing microplastics which enter our model via a combined sewer overflow within our estuarine reach and can flow out of the model at the downstream tidal boundary.
<<!PT Module to assess fate of Combined Sewer Overflow Outflow
! Use nodestring definition from HD model to allow particles to leave model domain.
Open Boundary Nodestring == 2 !Downstream tidal boundary
!Time Commands
!_________________________________________________________________________________________________________________________________
Lagrangian Timestep == 60.!seconds
Eulerian Timestep == 60. !seconds
!Global Commands
!_________________________________________________________________________________________________________________________________
Nscalar == 1
!Particle Group Commands
!_________________________________________________________________________________________________________________________________
Group == microplastics
Initial Scalar Mass == 1000
Settling Model == none
Horizontal Dispersion Model == constant
Horizontal Dispersion Parameters == 1.0
Vertical Dispersion Model == HD model
Vertical Dispersion Parameters == 1.0
Erosion Model == none
Deposition Model == none
End Group
!_________________________________________________________________________________________________________________________________
!CSO
Seed Particles == point, 159.09971, -31.39463
Particle Groups == microplastics
Timeseries File == ..\bc_dbase\CSO.csv
Timeseries Header == Date,microplastics
End Seed
!_________________________________________________________________________________________________________________________________
!Output Settings
Output Dir == ..\results\
Output == ptm_netcdf
Output Groups == microplastics
Output Interval == 1800.
Output Parameters == uvw, depth, water_depth, uvw_water
End Output
With the Nscalar command the scalar mass constituents are defined. These can be thought of as separate mass ‘containers’ that reside on a particle.
With the Group settings we are specifying the characteristics of the particles. In this exercise the particles defined won't settle, deposit on the bed or be subject to erosion. We will use a constant horizontal dispersion model and use the hydrodynamic model to define the vertical dispersion.
With the Seed Particles settings we are specifying that the particles are added to the model at a point inflow at co-ordinate 159.09971, -31.39463. The particles will be added to the model based on a mass flux time series defined in an CSO.csv file which we define in a later step.
With the Output Settings settings, we're specifying the location and format of the outputted results as well as the output interval and type for our group of particles. These are Lagrangian outputs specific to the individual particles. Eulerian outputs, for example the concentration of particles within the water column, are specified in the TUFLOW FV Control File (.fvc)
Once the above commands have been added, save and close the PT_000.fvptm file.
Mass Flux Time Series File
Part of the commands added in the .fvptm, are to define the how many and where to seed (release) particles for the microplastics. In this instance, the particles to be tracked are added at a point within the model domain at 159.1269, -31.41123. There is also a reference to a csv file in the bc_dbase folder which is the mass flux time series file. This defines the temporal variation of the particle input into the model with the units in grams/second. This works in conjunction with the initial scalar mass value we defined in the PT Module control file to determine the number of particles added to the model.
The number of particles per second is equal to:-
Time Series Mass (g/s)/Initial Scalar Mass (g)
Create a csv file called CSO.csv within the bc_dbase folder. Add column headers ‘Date’ and ‘Microplastics’ and populate with the following values:
| Date | Microplastics |
|---|---|
| 01/05/2011 00:00:00 | 20 |
| 01/05/2011 01:00:00 | 20 |
| 01/05/2011 01:00:01 | 0 |
Your CSV file should look like the below. This will introduce particles to our model at the beginning of the simulation for a period of 1 hour.
The time series mass flux value is 20g/s. The initial scalar mass defined in our particle group settings is 1000g. Therefore the number of particles released per second is:-
20/1000=0.02 particles per second. Over the 1 hour release period, this equates to 72 particles being released in total.
Save and close the CSO.csv file.
Update the TUFLOW FV Control File
With the changes to the model, we now need to update our TUFLOW FV control file (.fvc) to read in the additional data which define our PT Module.
Copy the existing HYD_002.fvc file and rename to PT_000.fvc. Add the following reference to the PT_000.fvc file in order to reference are TUFLOW FV PT Module control file.
!Particle Tracking Module Input !_________________________________________________________________________________________________________________________________ Particle Tracking Control File == PT_000.fvptm
Also within the output commands add the PTM_1 results parameter to the netcdf output parameters.
Output == netcdf
Output Parameters == h, v, d, PTM_1
Output Interval == 3600
End Output
Save and close the PT_000.fvc file
Run the Simulation
Update the batch file to allow the PT_000.fvc simulation to be run. Run the simulation by running the batch file.
Reviewing Results in QGIS
There are two types of results which are available to review. The first is the Eulerian results which provide information about the 2D and 3D characteristics of the bulk flow and particles. There are also Lagrangian results which provide characteristics for the individual particles.
Reviewing Eulerian Results in QGIS
In the previous examples we assessed 3D results using MATLAB and Python libraries. Some of these tools are now available within the QGIS TUFLOW Viewer Plugin allowing a user interface to review TUFLOW FV 3D results. See the following Viewing 3D TUFLOW FV Results in QGIS page for instructions on how to review TUFLOW FV 3D results within QGIS.
Reviewing Lagrangian Results in QGIS
So far we have assessed Eulerian results in terms of the mass concentration of particles within the cells. The results of the PT Module are also available as Lagrangian outputs, that is the location and characteristics of the individual particles. In order to view the particle results in QGIS, QGIS 3.14 or later needs to be installed as some of the features are new and may not be in earlier versions. Follow the steps here to install QGIS 3.14 with the required library to allow visualisation of the particles.
Using the TUFLOW Viewer plugin, select File->Load Results – Particles. Animate through the results and you should see the presence of particles within the model output. Results are best viewed in conjunction with the map output, usually with depth and velocity vectors displayed.
Right click on the PT_000_ptm.nc file which appears within the Layers panel with QGIS and go to Open attributes. You’ll see that there are 72 particles within the output once the simulation has got to 01/05/2011 01:00:00 (at 01/05/2011 00:30:00 there are 36 particles) which matches what we would expect from our mass flux time series and initial scalar mass value.
Within the layer attributes table are the 3D velocity values for the particle (uvw), the water (uvw_water), the depth to the particle and the water depth. Other output parameters are available (see the STM_PTM_User_Manual_2020).
The individual parameters can also be seen using the info tool, 
Currently the particles are themed using a single icon and colour type. However, it is possible to theme based on particle characteristics.
Right click on the PT_000_ptm.nc and enter the Styles menu. Using the options here we can theme on particle age since release (in hours), the depth of the particle within the water depth, particle group ID, mass and particle state.
Choose the 'stat' theme and animate the results. This will show the status of the particle as whether they are active in the water column, are active on dry land or within the bed.
Choose the 'depth' theme which shows the depth of the particle. The darker the particle theme, the deeper the particle within the water column.
At this stage, we’ve added a point source of particles to are model representing an input of plastics which are neutrally buoyant and aren’t subject to deposition and erosion. In the next exercise, we will allow the particles to interact with the bed sediment.
Adding a Polygon Input of Particles with Bed Interaction
So far the particles that we've added have been neutrally buoyant, they don't sink and they don't interact with the estuary bed (sediment). Within the particle transport model, it is possible to allow the particles to interact with the bed and be subject to deposition and erosion. This can be useful for the representation of sediments for example determining the fate of contaminated sediments or similar.
Copy and paste the existing PT_000.fvptm as PT_001.fvptm. Add the following section to the PT Module control file beneath our current definition of the microplastics particle group.
Group == sediment
D50 == 0.000002
Particle Density == 2650
Initial Scalar Mass == 1
Settling Model == constant
Settling Parameters == 0.0002 !(m/s)
Horizontal Dispersion Model == constant
Horizontal Dispersion Parameters == 1.0
Vertical Dispersion Model == HD model
Vertical Dispersion Parameters == 1.0
Erosion Model == Mehta
Erosion Parameters == 0.1,0.2,1.0
Deposition Model == Krone
Deposition Parameters == 0.25
End Group
In this instance we have defined a particle group called sediment which has a characteristic sediment size of 0.000002m. To add erosion, it's necessary to apply a settling model, erosion model and a deposition model. In this instance our settling model will be set to a constant particle settling rate of 0.0002 m/s, the erosion will be modelled using the Mehta erosion model and the deposition by the Krone deposition model. For details, the reader is referred to the Sediment Transport and Particle Tracking Module User Manual
In the previous examples we have provided point inputs of particles using a mass flux time series file. We will now define a polygon with a group mass of our contaminated sediment to an area within our model domain distributed throughout the water column.
Add a material block to define the default material block which defines the different bed characteristics within our model domain. For the purpose of this model, we will assume that the bed material is uniform with the bed material having a dry density of 1631 kg/m3.
!This is required due to adding deposition and settling
Material == 0 !Default material. Can add additional material blocks for spatial distribution.
Layer == 1
Dry Density == 1631.,1631.
End layer
End Material
Add the following section to the PT Module control file beneath the current definition of the particle point release location.
!Contaminated Sediment
Seed Particles == polygon
Particle Groups == sediment
Polygon File == ..\bc_dbase\sediment_polygon.csv
Vertical Coordinate Type == depth
Vertical Distribution File == ..\bc_dbase\sediment_vertical_distribution.csv
Group Mass == 1000
End Seed
Within the 'Global Commands' section add the following lines to specify the bed roughness model and parameters to control bed shear stress as well as limiting erosion and deposition when flow depths are low:
!Sediment Transport COMMANDS (required if a particle group interacts with bed) Bed Roughness Model == ks Bed Roughness Parameters == 0.01,0.01 !ksc, ksw !Depth Limit Commands Erosion Depth Limits == 0.01,0.05 Deposition Depth Limits == 0.01,0.05
Add sediment to the output groups within the ptm_netcdf output. Also add state_age to the list of output parameters.
Output == netcdf Output Groups == microplastics, sediment Output Interval == 1800 Output Parameters == uvw, depth, water_depth, uvw_water, state_age End Output
Polygon input
In the previous model we applied a time-varying point source. In this example, we will release all particles at the beginning of the simulation to cells with our specified polygon. Firstly we will define the polygon to which the particles will enter the model and secondly we will define their vertical distribution within the water column.
In the bc_dbase folder, create a sediment_polygon.csv file. Add two columns called X,Y and populate with the following values.
| X | Y |
|---|---|
| 159.124 | -31.413 |
| 159.127 | -31.413 |
| 159.127 | -31.410 |
| 159.124 | -31.410 |
This defines the vertices of the polygon using X, Y co-ordinates to where we will apply the particles.
Save and close the sediment_polygon.csv file.
In the same folder, create a Sediment_vertical_distribution.csv file. We will use this to define the distribution of our particles within the water column. The data takes the form of a depth vs weight table. Here depth is in meters from the water surface (also possible to use height, elevation and sigma level) and weight defines the relative distribution of the particles in the vertical profile.
| Depth | Weight |
|---|---|
| 0 | 0 |
| 1.4 | 0 |
| 1.5 | 1 |
| 2 | 1 |
| 2.1 | 0 |
| 9999 | 0 |
This defines the distribution of the particles within the water column. In this instance are particles will be applied to the water column at a depth between 1.4m and 2.1m from the water surface.
Save and close the file.
Update the TUFLOW FV Control File
Copy and paste PT_000.fvc as PT_001.fvc. Update the reference to the updated PT Module control file to PT_001.fvptm In the output section, add PTM_2 and PTM_BED_2 in the netcdf output parameters.
Output == netcdf Output Parameters == h,v,d, PTM_1, PTM_2, PTM_BED_2 Output Interval == 3600 End Output
This will allow us to see the concentration of the contaminated sediment both within the water depth and the bed within the map output.
Save and close the file. Update the reference to the updated TUFLOW FV control file, PT_001.fvc within the batch file, comment out the previous run command and run the PT_001.fvc simulation.
Review the Results in QGIS
Open the map output and particle netcdf files within QGIS using the TUFLOW Viewer plugin tool. Set the Eulerian map output theme to include flow depth and the velocity vectors. Right click on the PT_001_ptm.nc within the layers panel and in ‘Styles’ select the ‘stat’ attribute.
The polygon input of particles should be visible at the beginning of the simulation.
In this run we now have two sets or particles, our buoyant microplastics from the first exercise and our decontaminated sediment that we’ve added within the second exercise. The contaminated sediments are free to deposit and erode throughout the simulation. By animating the results you will see that the particles added appear in suspension within the water column at the beginning of the event but start to deposit onto the ‘Bed’ Sediment.
After a while, the majority of the particles have deposited upon the bed although some particles have been transported and deposited downstream.
Around 22:00 on 1/05/2011, the particles that were on the bed are picked up and suspended into the water column due to erosion.
Assess the map output Particle Group 2 Concentration. This will show concentrations at the beginning of the simulation. You can use the curtain plot tool to assess the distribution of the concentration through a cross-section. This shows the highest concentrations in the layers with a depth of between 1.5m and 2m.
Plot the map output - particle group 2 bed concentration. This shows increasing concentration within the bed on the outer banks of the channel close to where the contaminated sediment was added to the simulation.
Particles with Motility Behaviour
In the first two examples, we have introduced particles which have advected based on the hydrodynamic forcings present within the model. Particularly when investigating animal migration or similar biological responses, particles might require motility characteristics to represent upstream migration, migration towards the moon or migration away from highly saline water. This can be added with the motility functionality.
Add a Particle with Motility Characteristics
Make a copy of the PT_001.fvptm file and call it PT_002.fvptm. Open the file and within the particle group commands, add the following information.
Group == salmon
Particle Density == 15.
Initial Scalar Mass == 5
Settling Model == none
Motility Model == Speed, Target
Motility Parameters == 0.6,159.1256,-31.4411
Motility Start Time == 1
End Motility
End Group
This will add a third set of particles to our model which will be released at the downstream end of the model. In this case we'll be releasing a single particle to represent a migratory salmon. Motility parameters have been provided which allow the particles to migrate towards a point at the upstream end of the model (159.1256, -31.4411) at a speed of 0.5m/s. The motility behaviour starts 1 hour into the model simulation.
Within the seed particles section add the following commands to add the salmon particles to the downstream part of the model near the tidal boundary at 159.073, -31.359.
!Salmon
Seed Particles == point, 159.073, -31.359
Particle Groups == salmon
Group Mass == 5
End Seed
Add the salmon particles to the output groups in the Output Settings.
Output == ptm_netcdf Output Groups == microplastics, salmon, sediment
Save and close the PT_002.fvptm file.
Update the TUFLOW FV Control File
Copy and paste PT_001.fvc as PT_002.fvc. Open PT_002.fvc and update the reference to the updated PT Module control file to PT_002.fvptm. In the output section, add PTM_3 in the netcdf output parameters.
Output == netcdf
Output Parameters == h,v,d, PTM_1, PTM_2, PTM_BED_2, PTM_3
Output Interval == 900
End Output
Save and close the file. Update the reference to the updated TUFLOW FV control file, PT_002.fvc within the batch file, comment out the previous run command and run the PT_002.fvc simulation.
Once complete, open the results in QGIS as per the previous exercises and note how the particle starts at the downstream end of the model and migrates upstream against the flow current. Further analysis could be undertaken to assess the likelihood of consuming microplastics or being exposed to contaminated sediment.
Salmon particle at 1 hour 10 minutes
Salmon Particle at 6 hours 25 minutes
Running TUFLOW FV Simulations on a Graphical Processing Unit (GPU) (Optional)
TUFLOW FV can utilise GPU technology to distribute the hydraulic and sediment transport calculations across multiple processors within a CUDA-enabled NVidia GPU card. This has significant benefits in terms of runtimes with simulations up to 40 times quicker. If you have access to a CUDA-enabled NVidia GPU card then this section provides details of how to run your simulations on it. Note that the GPU card is only used for the Hydrodynamic calculations. The Lagrangian particle tracking calculations still take place on the CPU. In most cases the Langrangian timestep is much coarser than the hydrodynamic timestep so this is not a major factor in the overall runtime.
Copy and paste PT_002.fvc as PT_002_GPU.fvc. Open PT_002_GPU.fvc and add the following line under the line Tutorial Model == On
Hardware == GPU
Save and close the PT_002_GPU.fvc.
Open the batch file to run the TUFLOW FV Simulations. Update the reference to the updated TUFLOW FV control file, PT_002_GPU.fvc within the batch file and comment out the previous run command. Change the number of threads the simulation is to be run on to 1 by changing the following line in the batch file.
set OMP_NUM_THREADS=1
Save and close the batch file and double click to run. If you have an appropriate CUDA-enabled card and the NVidia drivers are up to date, then the simulation should continue. Once the simulation is complete, further confirmation of the use of the GPU card is provided in the TUFLOW FV log file.
Compare the run times from the GPU run to the run that was run without GPU technology on CPU cores.
Summary
This tutorial has introduced the TUFLOW FV Particle Tracking Module's functionality including how to set up models and review outputs (both Eulerian and Lagrangian) within the QGIS TUFLOW Viewer plugin. Further functionality allows the input of moving point sources as well as applying particle motility to allow particles to move of their own accord without any hydrodynamic (or wind) forcing. This is useful where particle tracking is used to simulate animal migration.
Click here to return to the TUFLOW FV Wiki homepage.