5    DSM2 Particle Tracking Model Development

5.1    Introduction

This chapter provides an update to further develop the DSM2 Particle Tracking Model. It covers the background of the model including the history, overview of the model and the basic underlying principals. The chapter describes the development and incorporation of particle behavior into the model and the Graphical User Interface to define these behaviors.

5.2    Background

5.2.1   History

In June 1992 the Department of Water Resources (DWR) hired Gilbert Bogle of Water Engineering and Modeling to develop a nonproprietary particle tracking module that DWR could adapt output and geometry of its DSM1 model. The original module provided by Dr. Bogle was a quasi two-dimensional model, which simulated longitudinal dispersion by utilizing a vertical velocity profile, vertical mixing, and a dispersion coefficient (which was a function of velocity, depth, and width of the channel). Because of the tidal nature of the water system and the channel grid, some complications occurred when implementing the module. After some scrutiny, the model was developed to be a quasi three-dimensional model.

The Particle Tracking Model was originally written in FORTRAN. Because of the model, the code was partially rewritten in C++ and Java to take advantage of using an object-oriented approach. The code was modified to handle the new output from the DSM2 model. The input system was rewritten in FORTRAN to use and to be consistent with the DSM2 input system.

5.2.2    Overview of Model

The Particle Tracking Model (DSM2-PTM) simulates the transport and fate of individual notional "particles" traveling throughout the Sacramento - San Joaquin Delta. The model uses velocity, flow and stage output from a one-dimensional hydrodynamic model (DSM2-HYDRO). Time intervals for these hydrodynamic values can vary but are on the order of 15 minutes or 1 hour. Time varying input into the hydrodynamic model includes inflows at various rivers, exports, agricultural return and diversions, stage at Martinez, and gate operations. Fixed input includes static channel, reservoir and gate properties, and other runtime parameters.

The Delta’s geometry is modeled as a network of channel segments and open water areas connected together by junctions. The PTM uses the same fixed input files that describe the geometry for DSM2-HYDRO. The particles move throughout the network under the influence of flows and random mixing effects.

The location of a particle at any time step within a channel is given by the channel segment number, the distance from the downstream end of the channel segment (x), the distance from the centerline of the channel (y), and the distance above the channel bottom (z).

5.3    Particle Movement

Three-dimensional movement of neutrally buoyant particles within channels is accomplished by longitudinal, transverse, and vertical movement.

5.3.1    Longitudinal Movement

The longitudinal distance traveled by a particle is equal to a combination of two velocity profiles multiplied by the time step. The two profiles are described in transverse and vertical directions.

5.3.1.2    Transverse Velocity Profile

The transverse profile simulates the effects of channel shear that occurs along the sides of a channel. The result is varying velocities across the width of the channel. The average cross-sectional velocity during a time step (Figure 5-1), which is supplied by DSM2-HYDRO, is adjusted by multiplying it by a factor which is dependent on the particle's transverse location in the channel. This results in a transverse velocity profile where the particles located closer to the shore move slower than those located near the centerline in the channel, as shown in Figure 5-2. The model uses a quartic function or fourth order polynomial to represent the velocity profile. The velocity profile is represented by the equation:

Eq. 5.1 Eq. 5.1

where:

Aq
, Bq, Cq = Coefficients,
y = Distance across the channel from –0.5 to 0.5, and
w = Width of the channel.

Figure 5-1: Average velocity over the transverse.
Figure 5-1: Average velocity over the transverse.

Figure 5-2: Applied quartic function to the average velocity in the tranverse.
Figure 5-2: Applied quartic function to the average velocity in the transverse.

5.3.1.2    Vertical Velocity Profile

The average cross sectional velocity (Figure 5-3) is adjusted by multiplying it by a factor that is dependent on the particle's vertical location in the channel. This results in a vertical velocity profile where the particles located closer to the bottom of the channel move slower than particles located near the surface. The model uses the Von Karman logarithmic profile to create the velocity profile as shown in Figure 5-4.

Figure 5-3: Average velocity over the vertical.
Figure 5-3: Average velocity over the vertical.

Figure 5-4: Applied Von Karman log function to the average velocity in the vertical.
Figure 5-4: Applied Von Karman log function to the average velocity in the vertical.

5.3.2    Transverse Movement

Particles move horizontally across the channel because of mixing. A gaussian random factor, a transverse mixing coefficient, and the length of the time step are used in the calculation of the distance a particle will move during a time step. The mixing coefficient is a function of the water depth and the velocity in the channel. High velocities and deeper water result in greater mixing.

The transverse mixing is in the process of being re-vamped to include a more detailed calculation of the transverse mixing coefficient. The gradient of this coefficient will be included in the calculation to more accurately simulate dispersion. The gradient will introduce displacement resulting from the variation in velocity within the channel.

5.3.3    Vertical Movement

Particles also move vertically in the channel due to mixing. A gaussian random factor, a vertical mixing coefficient, and the length of the time step are used in the calculation of the distance a particle will move during a time step. The mixing coefficient is a function of the water depth and the velocity in the channel. As with transverse mixing, when there are high velocities and deeper water the mixing is greater.

The vertical mixing is in the process of being re-vamped to include a more detailed calculation of the vertical mixing coefficient. Again, the gradient of this coefficient will be added in to more accurately simulate dispersion.

5.4    Capabilities

  • Particles can be inserted at any node location within the Delta.
  • History of each particle's movement is available.  In the model, the path each particle takes through the Delta is recorded.  Output for determining the particle's movement includes:
    • Animation. Particles are shown moving through the Delta Channels.  The effects of tides, inflows, barriers, and diversions on particles are seen at hourly time steps;
    • Number of particles passing locations.  The number of particles that pass specified locations are counted at each time step; and
    • Number of particles within a specified group of channels and reservoirs.

  • Each particle has a unique identity, and characteristics can change over time.  Since each particle is individually tracked, characteristics can be assigned to the particle.  Examples of characteristics are additional velocities that represent behavior (self-induced velocities) or the state of the particle such as age.
  • Particles travel at different velocities at different locations within the cross section.  The PTM takes the average one dimensional channel velocity from DSM2-HYDRO and creates a quasi three-dimensional velocity field. So, if particles are heavy and tend to sink toward the bottom, they will move slower than if they were neutrally buoyant.  As a result, travel time through the channels is longer.

5.5    Behaviors

Until recently, PTM simulations primarily have been made using neutrally buoyant particles. Working with biologists within the IEP Estuary Ecological and Resident Fish Studies Project Work Teams, some behaviors have been incorporated into the model. Some studies have been made where settling velocities and mortality rates have been included. These studies have concentrated on Stripped Bass eggs and larvae. The introduction of behaviors to the PTM will allow for the simulation of other things. Additional behaviors have been added to restrict a particle’s movement within a given volume. This restriction can be induced by the time of day or flow direction (in progress).

5.5.1    Life Stage or Phase

The idea of a life stage or phase is important to simulating with behavior. A life stage represents a particle’s behavior at a given time. Figure 5-5 shows an example of the life stages of an imaginary species of fish. The figure shows three defined life stages. Each stage is given a name and a group of properties that make up the behavior. The first stage shown represents the behavior associated with an "Egg." The second stage shown represents the behavior associated with the "Larvae." The third stage shown represents the behavior associated with the "Juvenile." The life stage would be a definable period in the life of a particle, whether the particle relates to fish or a non-conservative dye.

Figure 5-5: Diagram of particle Life Stages.
Figure 5-5: Diagram of particle Life Stages.

5.5.2    Development Time

A life stage is given a development time that defines the lifetime of a particular life stage. The development time tells the PTM how long to simulate a particle with a given behavior. Going back to the life stages of the imaginary fish (Figure 5-5), the development time of an "Egg" is defined to be five days. So for five days a particle will have the behavior of an "Egg." After five days the particle takes on the behavior associated with a "Larvae." Then 12 days later, 17 days total, the particle takes on the behavior of a "Juvenile."

When "particles" age, their behavior may change. For example, eggs may have a defined density and may float or sink and die. When the eggs turn into larvae they may not have a defined density, but they may swim a specific way.

5.5.3   Fall Velocity

A fall velocity can be added to a particle. This adds an additional downward (+) or upward (-) velocity component to a particle.  This can be useful such as in simulating Stripped Bass eggs, where eggs are deposited at the top of the water column.  The eggs have a slightly higher density and tend to fall at a predictable rate.

5.5.4   Mortality Rate

A mortality rate is the probability that a particle will die within a given time period.  Mortality rate is determined using the exponential distribution:

Eq. 5.2 Eq. 5.2

where:

P(X) = Probability of death per time period,
l  = Exponential distribution coefficient, and
t = Percent time.

Given a probability of death per time period, l  is calculated by setting t = 1:

Eq. 5.3 Eq. 5.3

Particles for each life stage are assigned a uniform random number between 0 and 1.  Particle death then occurs if it’s random number is less than the current cutoff number.  The cutoff number is calculated by:

Eq. 5.4 Eq. 5.4

where:

cutOffNum = Probability of death per time period,
l = Exponential distribution coefficient, and
age = Age of particle for current life stage.

Suppose there is a group of three particles, each assigned a mortality or probability of death of 25 percent per day. Knowing this information calculation of l occurs by:



Now that l has been calculated, a uniform random number is assigned to each particle:

Part1 = 0.308,
Part2 = 0.972, and
Part3 = 0.029.

Now as time is incremented, each particle is checked to determine if they die.  For this example the time increments will be 0.5 day.  The first increment results in the following cutOffNum(s):



A cutOffNum of 0.134 results in the death of particle Part3. Part3 has a number of 0.029, which is less than that of the cutOffNum.  Repeating this procedure at the given time step of 0.5 days, it is found that Part1 dies after 1.5 days and Part2 dies after 12.5 days.

5.5.5    Vertical Positioning

Vertical positioning allows for defining a restriction on the particle vertical movement in the channel. Typically a particle is allowed to roam 100 percent of the channel depth.  Figure 5-6 shows particles distributed throughout the water column.  These particles can potentially be subjected to any portion of the velocity profile. With vertical positioning the particles are restricted within a defined range.  As shown in Figure 5-7, the particles are restricted to the lower portion of the channel.  The range can be restricted to any part of the channel.  The range can even be defined for a given time.  With the restriction, the particles are subjected to the lower portion of the velocity profile.

Figure 5-6: Normal particle unrestricted distribution.
Figure 5-6: Normal particle unrestricted distribution.

Figure 5-7: Particles restricted to lower portion of channel.
Figure 5-7: Particles restricted to lower portion of channel.

5.6    Behaviors in Progress

There are a few other types of behaviors requested by the IEP Resident Fish Studies Project Work Team, which are in the process of implementation.  The behaviors include transverse positioning, flow positioning and the incorporation of response to water quality.

5.6.1    Transverse Positioning

Transverse positioning is similar to the vertical positioning.  However, with transverse positioning the range of restriction would be in the transverse or across the width.  So particles can be forced to stay near the banks or near the center of channels.  This could be useful if it is known that food exists at the sides of channels.  A transverse positioning component can be included so particles can move toward the shore at certain times in the day.  For example, particles may swim toward the shore for food.

5.6.2    Flow Positioning

Flow positioning would include a type of vertical and transverse positioning.  The driving force for decisions would be the direction of the flow.  Vertical and transverse positioning could be assigned for a given flow direction, whether seaward or landward.  An example would be a particle moving up in the water column to ride the flood or ebbing tide and then move down in the water column to reduce its velocity and movement in the opposite direction.

Along with positioning, particles may include an additional velocity depending on the flow direction.  Particles may have an additional longitudinal velocity component.  Particles may swim with or against the flow.

5.6.3    Quality

The incorporation of the DSM2-QUAL output into the PTM will allow particles to react to many different water quality constituents, including (but not limited to) temperature, dissolved oxygen, pesticides, and food abundance. This development will allow a particle’s growth rate and mortality to be a function of water quality.  Particles could also swim toward certain water quality or food abundance.

5.7    Graphical User Interface

The Graphical User Interface (GUI) is currently available for editing particle behaviors.  The following is a description of this behavior GUI.

5.7.1    Main Frame

When the GUI is first initialized, the user gets a frame like shown in Figure 5-8.  New life stages can be added by using the text field and adding the name.  Saved behaviors can also be loaded from this window.  Figure 5-9 shows this window with life stages added.  To illustrate the use of this tool, an "Egg" behavior and "Larvae" behavior will be used.

Figure 5-8: Initialized behavior GUI.
Figure 5-8: Initialized behavior GUI.

Figure 5-9: GUI with life stages entered.
Figure 5-9: GUI with life stages entered.

5.7.2    Physical definitions

After either adding or loading and editing a life stage, a new window with a group of tabbed panes is displayed.  Figure 5-10 shows the physical properties tab for the "Larvae (Life Stage 2)" where the physical properties of the life stages are defined.  The development time is defined here as 10 days long.  There is no fall velocity with this life stage so it is left undefined and assumes a value of zero.  The mortality rate or probability of death is set to 10 deaths per day.

Figure 5-10: Physical properties tab.
Figure 5-10: Physical properties tab.

5.7.3    Channel Positioning

The positioning tab allows the user to define areas in the channels that the particles must stay within.  Figure 5-11 shows the positioning defined for "Larvae (Life Stage 2)."  There is currently a limit of four vertical and horizontal channel positions for each life stage.  The first column defines the limit of the lower percent channel depth.  The second column defines the limit of the upper percent channel depth.  The third and fourth columns define the start and ending times for the particular positioning.

In the example shown in Figure 5-11, the particles during this life stage are forced to the upper 10 percent of the channel depth (from a lower limit of 90 percent depth to an upper limit of 100 percent depth) for the time between 6 a.m. and 6 p.m.  The particles are then forced to the bottom 10 percent of the channel depth for the time between 6 p.m. and 6 a.m.

All times do not need to be defined.  For any undefined time during the day, the model defaults to fully mixed.

Figure 5-11: Channel position tab.
Figure 5-11: Channel position tab.

Returning to the main GUI and saving this information there creates a file.  The format of the file utilizes the eXtensible Markup Language (XML), so it can easily be edited by hand.  This file is then specified in the general DSM2 input file structure.

5.7.4    Future Graphical User Interface

A full PTM interface is in development.  This will allow for the setup and execution of model simulations through a graphical interface.  The interface will display results of studies along with providing particle animations.

5.8    Additional PTM Enhancements

Some other PTM enhancements include some scalar flags, and the channel group output.

5.8.1    Channel Groups

Channel groups allow for the grouping of channels and reservoirs.  The model keeps track of and outputs the number of particles in the defined groups.  This type of output is useful in looking at the distribution of particles at a given time. Definition of these groups is done through a text-input file using the keyword GROUP.  The fields for the groups are object, number, and group.  The object field defines a channel with "chan" or reservoir with "res."  The number defines the object number (the channel or reservoir number).  The group field defines the group in which this object should be included.

The following example shows how to define a group.  For this example channel 275 and reservoir 5 have been associated with group number 2.

      GROUP
      OBJECT        NUMBER   GROUP
      # big break
      chan          275      2
      res           5        2
      END

5.8.2    Scalar Flags

A few new scalar flags have been added to increase the flexibility in the PTM output and the transverse velocity behavior.  As with typical DSM2 scalar logical flag behavior, a true value corresponds to the value indicated in the variable name.

ptm_flux_percent - Logical flag allows flux output as a percent or actual values.
ptm_flux_cumulative - Logical flag allows flux output as cumulative or instantaneous values.
ptm_group_percent - Logical flag allows group output as a percent or actual values.
ptm_no_animated - Integer flag specifies the number of particles to track for purposes of animation.
ptm_trans_a_coef - Floating point flag specifies the"a" coefficient in the quartic function used to describe the transverse velocity profile.
ptm_trans_b_coef - Floating point flag specifies the "b" coefficient in the quartic function used to describe the transverse velocity profile.
ptm_trans_c_coef - Floating point flag specifies the "c" coefficient in the quartic function used to describe the transverse velocity profile.

Author: Aaron Miller
Back to Delta Modeling Section 2000 Annual Report Table of Contents

Last revised: 2000-10-23

About Us Hydrology & Operations Section Delta Modeling Section Computer Assistance Section
Home Page Available Studies Computer Models Reports Home Page Available Studies Computer Models Reports

Disclaimer, Comments or Questions
Webmaster email to htdelmod@water.ca.gov