This chapter examines how trajectory seeding (initialization) is done in TRACMASS. Two types of seeding are possible: from boxes defined in the namelist file or from seeding files. It is recommended to first try out seeding from the namelist file, to get an idea of how it works, before starting with the seeding files.

In this example, we will be considering a case where only a single trajectory is initialized from each grid cell (nqua=1 and partquant=1), and only the trajectories with positive flux (idir=1), forward in time (nff=1), and on the meridional (isec=2) grid cell face.

Seeding from namelist boxes

In this example, the namelist has set up the seeding location as three boxes. The provided namelist sample is self-explanatory. 

&INIT_SEEDING
     ! (1)  forward in time
     ! (-1) backward in time
     nff            = 1,
     
     ! (1) zonal cell's wall     
     ! (2) meridional cell's wall
     ! (3) vertical cell's wall
     isec           = 2,

     ! (1)  start when flux > 0
     ! (-1) start when flux < 0 
     idir           = 1,

     ! number of trajectories can be set by
     ! (1) constant number of particles in all seeding cells
     !     set by partQuant (particles / gridcell)
     ! (2) Each particle reflects mass transport at seeding.
     !     set by partQuant (m3/s or kg/s per particle)
     ! (3) Each particle reflects air/water mass/volume at seeding.
     !     set by partQuant in m3 or kg per particle
     nqua           = 1,
      
     ! (if nqua=1) particles/gridcell
     ! (if nqua=2) m3s-1/particle
     ! (if nqua=3) m3/particle
     partquant      = 1,

     ! (1) seed using ist,jst,kst (below)
     ! (2) seed using file with start positions
     seedtype       = 1,


     ! seed in box in range i = [ist1,ist2]
     !                      j = [jst1,jst2]
     !                      k = [kst1,kst2]

     !                box1,  box2,  box3
     ist1           = 285,   200,   400, 
     ist2           = 325,   250,   500,
     
     jst1           = 270,   150,   1,
     jst2           = 330,   170,   100,  
     
     kst1           = 1,     1,     10,
     kst2           = 1,     100,   20,  

     ! (1) seed only for specific times
     ! (2) seed using file with start positions
     seedtime       =  1, 

     ! (if seedtime=1) seed only between tst1 and tst2
     tst1           = 1,
     tst2           = 1,
/

Seeding from a file

An option to keep files organized is to keep the files relating to a simulation in the project folder. In this case, the project is called global_model which contains a folder called seed_dir that holds two files:

  • seed_condition.txt - contains the position, cell wall, and direction of the seeding trajectory
  • seed_time.txt - contains the time when trajectory seeding takes place
The setup of the namelist can be found in the code sample below.

Note:
The .txt extension has been tested and works for the model as a seeding input file. Other formats, such as .csv, .nc, etc., might work as well. 
&INIT_SEEDING
     ...
     ...
     
     ! (1) seed using ist,jst,kst (below)
     ! (2) seed using file with start positions
     seedtype       = 2,

     ! (if seedtype=2) directory of seed files
     seeddir        = 'projects/global_model/seed_dir/',
     
     ! (if seedtype=2) name of seed START CONDITION file
     seedfile       = 'seed_condition.txt',

     ! (1) seed only for specific times
     ! (2) seed using file with start positions
     seedtime       =  1, 

     ! (if seedtime = 2) name of seed TIME file
     timefile       = 'seed_time.txt',
/

Seeding from a file

The seeding file seed_condition.txt sets up the seeding condition with three parts:

  • 1st, 2nd, 3rd column - grid cell location in the form of a model index in the x, y, and z directions
  • 4th column - which grid wall is used for seeding (isec)
  • 5th column - flux direction (idir)
For more information on the isec and idir parameters refer to the namelist documentation here. An example of how the seeding file is formatted is in the code snippet below.

! x_ind, y_ind, z_ind, isec, idir
  200,   250,   10,    1,    1,    ! First seeding condition
  200,   250,   10,    2,    1,    ! Second --//--
  200,   250,   10,    3,    1,    ! Third  --//--
   10,    12,    1,    1,    1,    ! Fourth --//--
   10,    12,    1,    1,   -1,    ! Fifth  --//--

File for seeding times

For the seeding time file seed_time.txt, there is only one column, which determines in which global iterations (intrun) seeding should take place. The time steps must be organized in a column, similarly to the seeding condition input file.

Number of Trajectories

This subchapter provides a closer look at initializing different numbers of trajectories. In general, there are three types:

  • nqua=1: Constant number of particles in all seeding cells
  • nqua=2: Proportional to the mass/volume transport at seeding
  • nqua=3: Proportional to mass/volume in the seeding cell

nqua=1

As the description states, with this method, a constant number of particles are seeded at every defined grid cell face. In this example, we seed 10 trajectories and we present a namelist snippet containing only the variables that are needed for this setup. 

&INIT_SEEDING
     ...
     ...
     ...

     ! number of trajectories can be set by
     ! (1) constant number of particles in all seeding cells
     !     set by partQuant (particles / gridcell)
     ! (2) Each particle reflects mass transport at seeding.
     !     set by partQuant (m3/s or kg/s per particle)
     ! (3) Each particle reflects air/water mass/volume at seeding.
     !     set by partQuant in m3 or kg per particle
     nqua           = 1,

     ! (if nqua=1) particles/gridcell
     ! (if nqua=2) m3s-1/particle
     ! (if nqua=3) m3/particle
     partquant      = 10,

     ...
     ...
     ...
/

nqua=2

In this case, the number of particles in a grid cell is defined with the volume/mass transport through the face and the volume/mass that is defined to represent a single trajectory. For example, if total volume transport is 10 m³/s and partQuant=5, we get subvol/partQuant=2 trajectory seeding locations in that grid cell. 

&INIT_SEEDING
     ...
     ...
     nqua           = 2,
     partquant      = 6,
     ...
     ...
/

nqua=3

For the nqua=3 case, the cell volume/mass is used for calculating the number of seeding points, by using a constant partQuant value for each trajectory seeding point. In this example, we set partQuant=0.1, which states that each trajectory will represent 0.1 m³ of volume of the starting grid cell. If we have a grid cell with a volume of 1 m³, then 10 trajectories will be seeded in the grid cell. 

&INIT_SEEDING
     ...
     ...
     nqua           = 3,
     partquant      = 0.1,
     ...
     ...
/