PTrack

Off-Line Lagrangian Particle Tracking

About

The particle tracking model this program implements (PTrack) was originally developed as a module embedded in the Unstructured Grid Finite Volume Community Ocean Model (FVCOM), first developed by Dr. Changsheng Chen et al. at the University of Massachusetts - Dartmouth. The current iteration of the particle tracking code found here is an almost complete rewrite of this module, designed to run independently of FVCOM. Presently FVCOM is being developed and maintained by the UMASSD Marine Ecosystem Dynamics Modelling Laboratory (MEDML), and more information may be found on their website: http://fvcom.smast.umassd.edu/

Running the model

PTrack requires the creation of three different configuration and data files.

• Model configuration file (text)
• Particle seed file (NetCDF)
• Tidal forcing and model domain file (NetCDF)

The tidal forcing file contains the flow-field data to drives the movement of the particles being simulated, as well as the data needed to reconstruct the physical domain (mesh, bathymetry, etc.), and is produced as the primary output of FVCOM. The structure and content of the text files will be elaborated on in the following sections. After compiling the input, the model may be run from the command-line using the start-up script:

start_tracking.sh run.dat

Where run.dat is the model configuration file.

Configuration file

Parameter	Units	Description
DTI	seconds	Simulation time step
DTOUT	seconds	Output interval
F_DEPTH	boolean	Hold particle depth constant
P_REL_B	boolean	Particle positions relative to sea floor, not sea surface
OUT_SIGMA	boolean	Output particle z position as sigma depth instead of meters
GRIDFN	file path	NetCDF grid and flow-field file location
OUTFN	file path	Output file location
STARTSEED	file path	Particle initial position (seed) file location
P_RND_WALK	boolean	Apply random walk behaviour to the active particles
K_XY	m^2/s	Horizontal particle diffusivity (used when P_RND_WALK is T)
K_Z	m^2/s	Vertical particle diffusivity (used when P_RND_WALK is T)
P_2D_MODEL	boolean	Run the model in 2D with a vertically averaged flow field
P_2D_VSURF	boolean	Use the surface velocity field for a 2D simulation

Grid and Flow-field file

The NetCDF flow-field used to drive the particle tracking simulation is produced by FVCOM. While the grid portion of the flow-field may contain either Cartesian or Spherical coordinates, the particle tracking program requires Cartesian coordinates. If only Spherical coordinates are present the fixproj program may be used to apply a cartographic projection to the coordinates, in order to generate the necessary Cartesian coordinates. fixproj is automatically run by the start_tracking.sh script.

Normally this file will be automatically generated by FVCOM, and the user will not need to worry about its structure. The variables used by the particle tracking program are listed in the following table.

Variable	Type	Dimensions	Units	Description
time	float	time	MJD	Days since 1858-11-17 00:00:00
zeta	float	time, node	meters	Water surface elevation (upward positive)
u	float	time, siglay, nele	m/s	Eastward water velocity
v	float	time, siglay, nele	m/s	Northward water velocity
ww	float	time, siglay, nele	m/s	Upward water velocity
x	float	node	meters	Node x coordinate
y	float	node	meters	Node y coordinate
xc	float	nele	meters	Element x coordinate
yc	float	nele	meters	Element y coordinate
h	float	node	meters	Sea floor depth (downward positive)
nv	int	three, nele	none	Nodes surrounding each element
nbe	int	three, nele	none	Elements surrounding each element
ntve	int	node	none	Number of elements surrounding each node
nbve	int	maxelem, node	none	Elements surrounding each node
siglev	float	siglev, node	none	Sigma levels (boundary between layers)
siglay	float	siglay, node	none	Centre of the sigma layer
a1u	float	four, nele	none	Shape coefficient array and control volume metrics
a2u	float	four, nele	none	Shape coefficient array and control volume metrics
aw0	float	three, nele	none	Shape coefficient array and control volume metrics
awx	float	three, nele	none	Shape coefficient array and control volume metrics
awy	float	three, nele	none	Shape coefficient array and control volume metrics

To ensure all of the required variables are present in the file, the following options should be enabled in the casename_run.nml configuration file for the FVCOM run.

• Configuration section: NML_NETCDF
• NC_GRID_METRICS = T
• NC_VELOCITY = T
• NC_VERTICAL_VEL = T

fixproj

fixproj is designed to take spherical coordinates from a NetCDF file (lon,lat), transform the coordinates with a PROJ.4 cartographic projection reference, and save the results (x,y). By default fixproj will attempt to read the projection reference from the NetCDF file's global CoordinateProjection attribute, but if a reference is not found a new one will be generated to optimally fit the bounds of the data.

Command options

• -p proj
  • Provide a geographic projection reference string to be used.
• -i
  • Perform an inverse projection.
• -v longitude_var latitude_var x_var y_var
  • Provide alternative names for the coordinate variables.
• -g
  • Force the generation of a new projection reference.
• -s
  • Suppresses the write-back of the used projection reference.

Usage

fixproj [-p projection] [-i] [-v lon lat x y] [-g] [-s] file_to_process.nc

Particle seed file

The particle seed file contains the initial positions of all particles to be released in the simulation, in addition to the release timing. This file is stored in NetCDF format, and the variables used are listed in the following table.

Variable	Type	Dimensions	Units	Description
number	int	number	none	Arbitrary identifier
x	float	number	meters	Domain x coordinate
y	float	number	meters	Domain y coordinate
z	float	number	meters	Downward positive particle depth
release	float	number	MJD	Time to release particle into the simulation
end	float	number	MJD	Time to remove particle from the simulation

genseed

genseed generates a NetCDF particle seed file from a text-based .dat file, allowing for some flexibility with the format of the input data. If a projection reference is not provided, it is assumed that the particle coordinates are already Cartesian. Note: the projection reference used for the seed file must match the reference used for the NetCDF flow-field file, otherwise the simulation results will be meaningless.

Command options

• -p proj
  • Use the provided geographic projection reference string (PROJ.4) to transform the seed file coordinates.
• -o outfile
  • Specify an output file. The name of the input file, except with a .nc file extension, will be used if a name is not provided.
• -t
  • Dates in the input file will be formatted as dd/mm/yyyy hh:mm:ss
• -f projfile
  • Same as -p, but read the projection reference from the provided NetCDF file's global CoordinateProjection attribute.

Usage

genseed [-o outfile.nc] [-t] [-p proj] [-f projfile.nc] particle_release.dat

File format

Each line of the file defines a different hypothetical seed particle, with the parameters separated by one or more spaces. The order of the parameters, along with their meaning, is given in the following table:

Column	Name	Type	Units	Description
1	ID	int	none	Arbitrary identifier
2	X	float	meters or degrees_east	Domain x coordinate
3	Y	float	meters or degrees_north	Domain y coordinate
4	Z	float	meters	Downward positive particle depth
5	Release Time	float	MJD or yyyy-mm-dd hh:mm:ss	Time to release particle into the simulation
6	Track End Time	float	MJD or yyyy-mm-dd hh:mm:ss	Time to remove particle from the simulation

Simulation output

The simulation output file contains all of the results from the simulation, and is also a NetCDF file. The variables this file contains are listed in the following table.

Variable	Type	Dimensions	Units	Description
time	float	time	MJD	Time the particle position was recorded
number	int	number	none	Arbitrary identifier
x	float	time, number	meters	Domain x coordinate
y	float	time, number	meters	Domain y coordinate
z	float	time, number	meters	Downward positive particle depth

Development

Primary functions and subroutines

The following subroutines form the top-level elements of the PTrack program, organized by their primary function.

Model initialization

The initialization functions read the model setup data from the various input files, and uses that data to create and fill the various data structures used by the program. The most important of these data structures are the mod_tracking_data module, which contains the data arrays holding particle state information, and the mod_flow_field module. Which holds domain information, such as the mesh data, and flow field state data.

• init_model
• init_flow_field
• init_tracking

Simulation loop

The core of the tracking simulation is the main program loop, which iterates over time by constant increments of DTI seconds; each full iteration of the loop progressing the model by one time step.

• run_tracking

Particle model

These subroutines are called on every iteration of the model from the simulation loop, and implement the behaviours and motions of the particles.

• traject
• random_walk

File I/O

The subroutines that retrieve forcing data and save model results on each iteration of the simulation loop.

• get_flow_at
• write_track

Program files

• PTrack.f90
  • program particle_traj
• mod_tracking.f90
  • module mod_tracking
  • subroutine init_tracking
  • subroutine run_tracking
  • subroutine run_2d_tracking
• mod_tracking_data.f90
  • module mod_tracking_data
  • subroutine read_seed
  • subroutine write_track
• mod_flow_field.f90
  • module mod_flow_field
  • subroutine init_flow_field
  • subroutine ncd_read_grid
  • subroutine get_flow_at
  • subroutine read_flow
  • function timeIndex
  • function check_field_time
• mod_host.f90
  • subroutine fhe
  • subroutine fhe_robust
  • function isintriangle
• mod_inp.f90
  • module mod_inp
  • subroutine get_val
  • function scan_file
  • function to_upper
  • subroutine pscanmsg
• mod_io.f90
  • module mod_io
  • subroutine nc_open_file
  • subroutine nc_close_file
  • subroutine nc_new_outfile
  • subroutine nc_dim
  • subroutine nc_read_int_var
  • subroutine nc_read_int_var2
  • subroutine nc_read_real_var
  • subroutine nc_read_real_var2
  • subroutine nc_read_real_var3
  • subroutine nc_1d_read
  • subroutine nc_2d_read
  • subroutine nc_3d_read
  • subroutine nc_1d_write
  • subroutine nc_2d_write
  • subroutine handle_ncerror
• mod_config.f90
  • module mod_config
  • subroutine init_model
• mod_prec.f90
  • module mod_prec
• interp_procs.f90
  • subroutine traject
  • subroutine traject_2d
  • subroutine random_walk
  • subroutine interp_v
  • subroutine interp_2d_v
  • subroutine interp_elh
  • subroutine gauss_random