Parameters of note are YEARLAG, MONTHLAG, DAYLAG and HOURLAG which determine when the particle tracking should begin. In spite of YEARLAG being defined in this control file, the source code currently has hardcoded values for the year, so you will need to edit offlag.f90 around lines 45 and 46 to use the correct year for your model run.

LAGINI is the file containing the initial particle positions.

GEOAREA is the equivalent of casename in the FVCOM manual. Your .dat file must be called GEOAREA_run.dat (i.e. casename_run.dat).

Set the INPDIR and OUTDIR values to reflect the input and output directories you have from your FVCOM model run. Output files must be in a directory for each year. The naming of the model output files must be casename_####.nc where #### is a number starting from 0001.

The METRICS parameter controls the file name for the grid metrics. This netCDF file contains the grid metrics which are necesssary for advecting the particles. This can be a time consuming operation if the grid is complicated, so saving those outputs for successive runs can be a significant time saving.

The way it works is if the file does not exist in the input directory, the grid metrics are calculated and saved to a netCDF file named tst_metrics.nc in the example above (change METRICS to change the prefix). Once the file has been generated on first run, successive runs can use it if it is moved into the input directory (INPDIR/YEARLAG).

FVCOM model output files

The offline code requires model output which contains the following variables:

Variable name

Long name

Dimensions

Units

x

nodal x-coordinate

node

metres

y

nodal y-coordinate

node

metres

nv

nodes surrounding element

three, nele

–

h

Bathymetry

node

metres

siglev

Sigma Levels

siglev, node

–

a1u

a1u

three, nele

–

a2u

a2u

three, nele

–

aw0

aw0

three, nele

–

awx

awx

three, nele

–

awy

awy

three, nele

–

time

time

time

days since 1858-11-17 00:00:00

zeta

Water Surface Elevation

time, node

metres

u

Eastward Water Velocity

time, siglay, nele

ms-1

v

Northward Water Velocity

time, siglay, nele

ms-1

omega

Vertical Sigma Coordinate Velocity

time, siglev, node

s-1

km

Turbulent Eddy Viscosity For Momentum

time, siglev, node

m2 s-1

Note: there is no support for spherical coordinates, so you will have to either run your original model in cartesian, or enable FLAG_6 = -DPROJ when compiling FVCOM (and subsequently set the PROJECTION_REFERENCE in your casename_run.nml file).

Note: your FVCOM model output must be in day-long chunks. The particle tracking will only read the first 24 hours of any results file it's given. A script to chop up monthly model output files into day long individual files can be found here.

Offline input particle definition files

The offline code requires only a single file to define the release sites for the particles. An example is given below:

3
1 510876 6555485 5.0
2 500064 6563972 0.0
3 530350 6561007 10.0

The first line defines the number of particles to track (this is read in with a DO loop in offlag.f90, so if you have a long list of positions but only wish to use the first few, set the header number to the number you wish to read in, leaving the remaining points defined in the list; the code will ignore them).

The definition of each point is ID XPOS YPOS DEPTH with depth being positive down. Set the name of this file to match the LAGINI value in the casename_run.dat file.