- 1 Tutorial Description
- 2 Setting up a Point Source of a Group of Particles
- 3 Reviewing Results in QGIS
- 4 Adding a Polygon Input of Particles and interacting with the bed
The TUFLOW Particle Tracking Module (PTM) allows the 2D or 3D simulation of discrete Lagrangian particles as they are transported by the flow field (or other drivers such as wind). 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 PTM is invoked through the TUFLOW FV hydrodynamic engine which controls the overall simulation and supplies the hydrodynamic forcing to the particle transport module.
The tutorial will cover a number of aspects of the particle tracking model:
For the purposes of the particle tracking 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 particle tracking 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 notepad++ to create a new file with extension .fvptm. Name the file PT_000.
- Add the following commands to define a group of particles representing microplastics which enter our model via a combined sewer overflow within our eastuarine reach and can flow out of the model at the downstream tidal boundary.
!PTM to asses 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 !_________________________________________________________________________________________________________________________________ langrangian 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, was to define the seed 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 PTM 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 ‘Plastics’ and populate with the following values:
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 particle tracking 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 particle tracking module control file.
!Particle Tracking 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 particle tracking are also available as Lagrangian outputs, that is the location and characteristics of the individual 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).
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 and interacting with the bed
- Copy and paste the existing PT_000.fvptm as PT_001.fvptm.
- Add the following section to the PTM 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 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 the following section to the PTM control file beneath the current definition of the particle point release location.
!Contaminated Sediment seed particles== polygon particle groups== sediment polygon file== ..\bc_dbase\wwtp_poly.csv Vertical coordinate type== depth Vertical distribution file== ..bc_dbase\vert_distr.csv group mass== 1000 end seed
- 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_ageend output