Many variables at TRACMASS can be modified using the namelist without the need to recompile the program. Each project has a namelist_CASE.in in the project folder. When TRACMASS is compiled a copy of the namelist (namelist.in) can be found in the main TRACMASS directory.

This is a list of all the variables that can be changed in the namelist and their corresponding group. Not all of these variables must be defined in the namelist.

INIT_GRID_DESCRIPTION

Here you can set the paths and variable names to define the volume/mass fluxes.

  • griddir [integer, array]: the direction of the input data indexes referenced to the TRACMASS reference system. It’s a three element array; the first element corresponds to the zonal direction, the second one to the meridional direction and the third one to the vertical direction. Two possible values are possible (1) eastward/northward/upward or (-1) westward/southward/downward. The default values are [1,1,1].

  • zeroindx [logical]: the first index in the original dataset is given by zero instead of one. The default value is FALSE.

  • trunit [real]: constant to scale the TRACMASS transports.

  • l_onestep [logical]: read one time step per input file. The default value is FALSE.

  • physDataDir [character]: path to the input data directory in reference to the TRACMASS root directory 'Tracmass'.

    • Note:
    TRACMASS reads the data in reference to it's root directory 'Tracmass' if only the relative path is defined (in the begining of path '/' is not present). If '/' is in the begining of the path, TRACMASS understand it as an absolute path, thus, starting from the system's root directory.

  • physPrefixForm [character]: prefix of the input data file name.

  • dateFormat [character]: part of the input data name that will be corrected by the subroutine filledFileName. Availabal date formats are the following, with D-day, M-month, Y-year:

  • tGridName [character]: the suffix for T grid files.

  • uGridName [character]: the suffix for U grid files.

  • vGridName [character]: the suffix for V grid files.

  • wGridName [character]: the suffix for W grid files.

  • fileSuffix [character]: describes the file format of the input files such as ‘nc’ or ‘nc4’.

  • hs_name [character]: variable name for surface height/pressure, etc.

  • ueul_name [character]: variable name for zonal velocity.

  • veul_name [character]: variable name for meridional velocity.

  • usgs_name [character]: variable name for subgrid zonal velocity. The default value is ” “.

  • vsgs_name [character]: variable name for subgrid meridional velocity. The default value is ” “.

  • usub_name [character]: variable name for secondary subgrid zonal velocity. The default value is set to ” “.

  • vsub_name [character]: variable name for secondary subgrid meridional velocity. The default value is set to ” “.

  • w_name [character]: variable name for vertical velocity. The default value is set to ” “ and will be overriden if the simulation is set to 2D.

There are various options of setting up the grid data, but here is a simple example to ilustrate the basis of how TRACMASS creates a path to a file to read it in. In this example, grid files are located in folder '/projects/NEMO/setup_data/'. Here, the relative path is used with the assumption . Next, the input file format is defined with physPrefixForm, dateformat, fileSuffix and one of the grid names - tGridName, uGridName, vGridName. Any of these can be left empty depending on the file format; however, in this case the tracer values, and zonal and meridional velocity fields are all in seperate files and let's assume that date is 20251014 (YYYYMMDD) accordingly:

  • NEMO-data-20251014-T.nc in which we have hs_name='ssh'
  • NEMO-data-20251014-U.nc in which we have ueul_name='uo'
  • NEMO-data-20251014-V.nc in which we have veul_name='vo'
Assuming that the input data are daily averaged, TRACMASS automatically reformats the dateformat values so that the next day file is correctly read into the software. This data can me daily, monthly, yearly, or any variation of those. 

 &INIT_GRID_DESCRIPTION
       ! Describe filenames
       physDataDir = 'projects/NEMO/setup_data/',
       physPrefixForm = 'NEMO-data-',
       dateformat = 'YYYYMMDD',

       ! Name of Tgrid, Ugrid, Vgrid (can be left empty as well)
       tGridName = '-T',
       uGridName = '-U',
       vGridName = '-V',

       ! suffix of files, e.g. ".nc"
       fileSuffix     = '.nc',

       ! Describe variable name
       hs_name = 'ssh'         ! Sea surface height
       ueul_name = 'uo',       ! name of resolved zonal velocity
       veul_name = 'vo',       ! ---- " -------   meridional
       usgs_name = '',         ! name of unresolved zonal velocity
       vsgs_name = '',         ! ---- " ---------   meridional
/

INIT_GRID_SIZE

Here you can set the paths to the files that contain the mesh grid as well as defined the size or the domain or the type of boundary conditions. The file formatting process is nearly identical to INIT_GRID_DESCRIPTION.

  • imt [integer]: number of global i points.

  • jmt [integer]: number of global j points.

  • km [integer]: number of global k points.

  • iperio [integer]: cyclic zonal boundary conditions. Two possible values: (0) no cyclic zonal boundary condition or (1) cyclic zonal boundary conditions is on. The default values is 0.

  • jperio [integer]: cyclic meridional boundary conditions. Two possible values: (0) no cyclic meridional boundary condition or (1) cyclic meridional condition is on. The default value is 0.

  • topoDataDir [character]: path to the directory that contains mesh or topography data. Relative path to the Tracmass root directory or system's absolute path can be used, for more information refer to the note in INIT_GRID_DESCRIPTION.

  • hgridFile [character]: name of the file that contains variables linked to horizontal grid data.

  • dy_name [character]: variable name for dy in T points.

  • dyu_name [character]: variable name for dy in U points.

  • dx_name [character]: variable name for dx in T points.

  • dxv_name [character]: variable name for dx in V points.

  • zgridFile [character]: name of the file that contains variables linked to vertical grid data.

  • dzt_name [character]: variable name for dz in T points.

  • dzu_name [character]: variable name for dz in U points.

  • dzv_name [character]: variable name for dz in V points.

  • dep_name [character]: variable name for total depth in physical units.

  • bathyFile [character]: name of the file that contains variables linked to bathymetry/topography.

  • kmt_name [character]: variable name for bathymetry in model levles, not physical units.

INIT_GRID_SUBDOMAIN

Here you can activate and define a subdomain in TRACMASS (more info can be found here).

  • l_subdom [logical]: activate a subdomain which will be used for calculations, excluding the rest of the data. The rest of the indexes, such as, domain size, seeding locations and kill zones are in reference to this subdomain, not the original one. Default value is FALSE.

  • imindom [integer]: index that represents the western boundary of the subdomain.

  • imaxdom [integer]: index that represents the eastern boundary of the subdomain.

  • jmindom [integer]: index that represents the southern boundary of the subdomain.

  • jmaxdom [integer]: index that represents the northern boundary of the subdomain.

INIT_GRID_TIME

Here you can set the time step and unit at which the input data is stored, as well as define the number of subcycles use in TRACMASS.

  • ngcm_step [integer]: number of time steps between two time levels. Typically set to be equal to the velocity field data time step.

  • ngcm_unit [integer]: unit of the time step (ngcm_step): (1) seconds, (2) minutes, (3) hours, (4) days, (5) months, and (6) years.

  • iter [integer]: number of subcycles between two time levels (ngcm_step).

Here is an example of setting up the model to have hour as the time unit (ngcm_unit), that has 2 units of the time step ngcm_step. This sets the model to have 2 hour global time step. The variable iter determines how many subcycles or sub-timesteps the model will take between two global time steps (ngcm_step). In this case, iter=12, indicating 12 time steps. This would translate to 10 min subcycles (ngcm_step/iter = 2h/12 = 10 min). This is how it would look in the namelist.in file: 

 &INIT_GRID_TIME
    ngcm_step      = 6, 
    ngcm_unit      = 3, 
    iter           = 12,
/

INIT_START_DATE

Here you can define the starting date of the simulation.

  • startSec [integer]: starting second.

  • startMin [integer]: starting minute.

  • startHour [integer]: starting hour.

  • startDay [integer]: starting day.

  • startMonth [integer]: starting month.

  • startYear [integer]: starting year.

  • noleap [logical]: if FALSE a calendar with leap years is used. Default value is TRUE.

  • mon30day [logical]: if TRUE a calendar with 360 days is used (30 days per month). Default value is FALSE.

INIT_RUN_TIME

Here you can define the total number of time steps that TRACMASS will be run and the frequency of data saving. A loop between two dates can be set here as well (more info can be found here).

  • loopYears [logical]: make a loop over two dates to run. Default value is FALSE.

  • loopStartYear [integer]: starting year of the loop.

  • loopEndYear [integer]: last year of the loop.

  • log_level [integer]: level of verbose output in terminal while running model. Minimal output with basic information (0), more descriptive setup (0<log_level<3), descriptive setup and every time step additional information of ongoing processes (3<=log_level<5), descriptive setup with detailed information at each time step (5<=log_level). For typical use, log_level=0 recommended, for debugging - other values.

  • intrun [integer]: number of total global time steps (ngcm_step) to run.

INIT_WRITE_TRAJ

Here you can define all the parameters and paths linked to the output data (more info can be found here).

  • write_frec [integer]: output writing frequency: (1) write at time intervals of gcm datasets (each ngcm_step), (2) write at each time iteration (each subcylce iteration iter), (3) write each spatial grid-crossing, (4) write at all time steps, and (5) write only start and end positions.

  • write_form [integer]: output writing format: (0) two decimals, (1) five decimals. Default values is zero.

  • outDataDir [character]: path to the directory where the output files are stored. If field left empty or not defined, output files are saved in the root TRACMASS directory.

  • outDataFile [character]: prefix of the output file. Default value is 'TRACMASS'

  • timeformat [integer]: format of the time array: (0) seconds from the starting date, (1) time fraction, or (2) date and time format (YYYY, MM, DD, HH).

  • l_compress [logical]: Copresses the output files if they are larger than 2GiB in seperate zip folders. At the end of the run, they are merged into one zip folder. Defualt value is FALSE.

INIT_SEEDING

Here you can define all the parameters to seed trajectories in TRACMASS (more info can be found here).

  • nff [integer]: time arrow of TRACMASS: (1) run trajectories forward in time and (-1) backward in time.

  • isec [integer]: seeding section (1) zonal wall in eastern direction, (2) meridional wall in northern direction, and (3) vertical wall in upward direction.

  • idir [integer]: direction of initial fluxes; (1) only positive fluxes are seeded, and (-1) only negative fluxes are seeded.

  • nqua [integer]: defines how many particles are initiliased per grid cell (nqua=1) constant number set by partQuant, (nqua=2) all trajectories reflect the same transport set by partQuant.

  • partQuant [integer]: number of trajectories per grid cell (if nqua=1) or the mass/volume transport per trajectory (if nqua=2).

  • loneparticle [integer]: if set to 1, runs a lonely trajectory. The default value is set to zero (run all trajectories). Typically used for debugging.

  • SeedType [integer]: defines the seeding type (1) using a seeding box defined by ist,jst,kst, or (2) using indexes from a file.

  • ist1 and ist2 [integer]: define the first and last zonal index of the seeding box (seedType=1)

  • jst1 and jst2 [integer]: define the first and last meridional index of the seeding box (seedType=1)

  • kst1 and kst2 [integer]: define the first and last vertical index of the seeding box (seedType=1)

  • seeddir [character]: path to the directory where the seeding file is stored (seedType=2).

  • seedfile [character]: name of the seeding file (seedType=2).

  • maskfile [character]: name of the masking file (seedType=1).

  • seedTime [integer]: defines the time seeding type (1) using a time range, or (2) using indexes from a file.

  • tst1 and tst2 [integer]: defines the first and last time steps to seed trajectories (seedTime=1).

  • timeFile [character]: name of the time seeding file (seedTime=2).

INIT_TRACERS

Here you can activate tracers, define their names and properties, as well as set some modifications (more info can be found here).

  • l_tracers [logical]: activate tracers. Default value is FALSE.

  • l_swtraj [logical]: activate salt/water trajectories. Default value is FALSE.

  • tracertrajscale [real]: scale factor applied on the tracer which is used to compute salt/water trajectories. Default value is one. If l_swtraj is set to FALSE, then tracertrajscale is set to 1.

  • tracername [character, array(max 10)]: name of the tracers, maximum 10 tracers.

  • tracershift [real, array(max 10)]: add a shift value to the tracer array. Default values is zero.

  • tracerscale [real, array(max 10)]: multiple the tracer value by a scale factor. Default values is one.

  • tracerunit [character, array(max 10)]: tracer units.

  • tracervarname [character, array(max 10)]: variable name of the tracer if it is read in from a file.

  • traceraction [character, array(max 10)]: action associated to the variable: either ‘read’ and data is read froma file or ‘compute’ in which case TRACMASS carries out tracer calcultions while running simulation.

  • tracerdimension [character, array(max 10)]: defines the number of dimensions of the tracer, ‘2D’ or ‘3D’.

  • tracermin [real, array(max 10)]: minimum value of the tracer used to define the tracer coordinate space when stream functions are computed.

  • tracermax [real, array(max 10)]: maximum value of the tracer used to define the tracer coordinate space when stream functions are computed.

Important to note that only up to 10 tracers can be declared. An example of setting up 3 different tracers is presented in the next code sample. All of the tracers are set up with the same index across the different variables, such that, if a potential temperature is declared the 5th tracer for variable tracername, then for all other variables (tracershift, tracerunit, traceraction, etc.) will also be the 5th in thir according arrays. For example, seawater salinity S is declared as the 2nd tracer in tracername array, thus, it will need to be 2nd variable in all the rest of the arrays. Accordingly, salinity unit is defined as PSU, with a variable name so, which is 'read' in from an external file and has a '3D' array dimensions. Finally, if streamfunctions are being calculated, it is possible to set the min and max values for which the streamfunctions will be calculated, in this example, the salinity range has been set to min=32 and max=38. 

 &INIT_TRACERS
     ! Enables tracer calculations
     l_tracers = .TRUE.

     ! Tracer name (description)
     tracername = 'To','S', 'sigma0'
     ! Tracer unit (description)
     tracerunit = 'degC','PSU', 'kg/m^3'

     ! Name of the variable in the netcdf (if it's read)
     tracervarname = 'thetao','so', 

     ! Action (read or compute)
     traceraction = 'read','read','compute'

     ! Dimension of the tracer
     tracerdimension = 2D, 3D, 2D,

     ! Minimum and maximum value of the binning
     tracermin = -3, 32, 1,
     tracermax = 33, 38, 40,
/

Alongside adding manually some tracer definitions, TRACMASS provides a couple of frequently used tracer definitions. More information can be found here.

INIT_TRACERS_SEEDING

Here you can define the maximum and mimimum tracer values when particles are seeded (an example can be found here).

  • tracer0min [real, array(max 10)]: minimum value of the tracer to be seeded. The default values is -9999. Can be left undeclared.

  • tracer0max [real, array(max 10)]: maximum value of the tracer to be seeded. The default values is 9999. Can be left undeclared.

INIT_KILLZONES

Here you can define the maximum time limit, as well as define the regions where trajectories are terminated (some examples are shown here and here). For a detail description on how the kill zones work check the projets folder section.

  • timax [real]: time limit before trajectories are terminated, calculated in days.

  • l_nosurface [logical]: prevent trajectories from reaching the last vertical level (sea surface/ land surface). If set to .TRUE., once a trajectory reaches sea surface/ land surface, trajectory is put back in the middle of the cell in depth direction. Default value is .FALSE..

  • exitType [integer]: selects the type of killing zones (1) defined by a regular box, (2) defined by a tracer value, (3) a combined tracer-geographical zone, and (4) hard coded killing zone.

  • ienw and iene [integer, array(max 10)]: define the western and eastern index of the killing zone (if exitType=1).

  • jens and jenn [integer, array(max 10)]: define the southern and northern index of the killing zone (if exitType=1).

  • tracerchoice [integer, array(max 10)]: defines the tracers that are used to define the killing zone (if exitType=2 or exitType=3). The index is given by the order of the tracer in tracername.

  • tracere [real, array(max 10)]: value of the tracer that defines the killing zone with tracerchoice (if exitType=2 or exitType=3).

  • maxormin [integer, array]: sets the value of tracere to a (1) maximum or (-1) minimum value.

Here is shown an example of how to set up kill zones with exitType=1, which is a regular box. Similarly as with tracer set up, a maximum of 10 killzone boxes can be set with this option. Here we have set up 2 boxes, first acting as a line and the second as a rectangular box. The first box has the dimensions from 200-th to 300-th index in the west-east direction and is set to 150-th index in the north-south direction. Looking form a bird eye view that would be a horizontal line across the grid. The second killzone box is truly a box with size from 50-th to 250-th index in west-east direction and from 350-th to 450-th index in the north-south direction. Once the box line is crossed, the trajectory is terminated; it does not matter from which side the trajectory crosses. 

 INIT_KILLZONES
     ! Maximum time for which trajectories will run
     timax = 75000 ! time limit for traj [days]

     ! Set up an exitType as a box of kill zones
     exitType = 1
     
     !       1st box   2nd box
     ! west indices of killzones
     ienw =  200,      50  
     ! east indices of killzones
     iene =  300,      250	    
     ! south indices of killzones
     jens =  150,      350
     ! north indices of killzones
     jenn =  150,      450
/

INIT_POSTPROCESS

Here you can activate the stream function and/or the tracer divergence calculation (some examples are shown here and here). For a detail description on how the stream functions are computed check the mod_stream.F90) section. For information about the divergence calculation check mod_divergence.F90) section instead.

  • l_psi [logical]: activate stream function calculation.

  • l_offline [logical]: compute the stream functions offline. Default value is TRUE.

  • dirpsi [integer, array(max 21)]: direction of integration of streamfunctions: (1) intigration is in the positive direction, (-1) integration in the negative direction. Default value set to 1.

  • xyflux [integer]: compute barotropic fluxes using uflux (1) or vflux (2). Default value is 1.

  • l_divergence [logical]: activate the calculation tracer divergence.

  • divconst [real, array(max 10)]: constants applied to the tracer divergence. Default value set to 1.

INIT_ACTIVE

Here you can activate the Lagrangian diffusion scheme (for more information check here).

  • l_diffusion [logical]: activates the addition of a random displacement to trajectories. Default values is FALSE.

  • ah [real]: horizontal diffusion constant. Default value set to 0.

  • av [real]: vertical diffusion constant. Default value set to 0.