#acl ClamsUserGroup:read,write,delete,revert All:read

== The package traj ==
The package ''traj'' allows to determine the trajectories of an ensemble of air parcels. Using assimilated winds and temperatures derived from meteorological data (currently UKMO or ECMWF), both forward and backward can be calculated. The numerical integration is based on the 4th order Runge-Kutta schema.

Information about input/output data, the data structures and program structure: 
[[attachment:CLaMS_Traj.pdf]]


=== Configuration file ===
The options for the execution of ''traj'' can be set in the configuration file '''traj.inp''':

{{{
1)  example1/pos_EXP_97032512.nc  ! Name of initial positions file
2)  /usr/nfs/data/data_on_just/met_data/ecmwf/era_interim/nc/hybrid/yymm   ! Input directory
3)  ecmwf                         ! Prefix of wind files
4)  outdir                        ! Output directory
5)  abc               ! Prefix for output file
6)  24                ! 1/2/3/4/6/8/12/24 -> Data every n hours
7)  y                 ! y/n - Backward/Forward trajectories
8)  y                 ! y/n - 3d(with theta_dot)/2d(without theta_dot) run
9)  ZETA_DOT          ! short name of variable containing THETA/ZETA-DOT information
10) 1                 ! eq. starts (a=0) diff. starts: a=1/2 same end/length
11) 12 23 03 1997     ! Endtime(hh dd mm yy) for a=0/1, lenght (hrs) for a=2
12) 1800              ! First timestep in seconds
13) 300               ! Second timestep in seconds
14) 0 1 0             ! Writing frequency (minutes hours days)
15) N.Thomas          ! user name
16) 3                 ! number of output parameters
17) TEMP              ! output parameters (one short name per line)
    PRESS            
    PV
}}}
Remarks:

 1. Name of initial positions file (if it is not in current directory the path must be specified)
 1. Directory with wind files <<BR>> If ''yymm'' or ''yyyy/mm'' is specified, it will be replaced by the current year and month.
 1. Prefix of wind files: <<BR>>  The filenames of the wind files must correspond to the format ''prefix_yymmddhh.nc''. ''prefix'' must be specified in this line. 
 1. Output directory
 1. Prefix for output file consisting of three characters: <<BR>> The output filename corresponds to the format ''traj_xxx_3d_yymmddhh_yymmddhh.nc''. The characters ''xxx'' must be specified in this line.
 1. Interval between wind files in hours
 1. Specification, if forward or backward trajectories should be calculated: <<BR>>  y = backward trajectories <<BR>> n = forward trajectories
 1. 2d or 3d run <<BR>> y = 3d run (with theta_dot) <<BR>> n = 2d run (without theta_dot)
 1. Short name of variable containing THETA-DOT information
 1. If the trajectories start at different times, in this line is specified if they should all end at the same time or if they should have the same length: <<BR>> 1 = same end time for all trajectories <<BR>> 2 = same length for all trajectories <<BR>> If all trajectories start at the same time, this specification is ignored.
 1. If all trajectories start at the same time or if the trajectories start at different times but should end at the same time, the end time must be specified (hour, day, month, year). If the trajectories start at different times and should have the same length, the lenght of trajectories must be specified (in hours).
 1. Timestep for calculation in seconds
 1. This specification is only considered if the trajectories start at different times. The timestep is used in the period between the first starting and the last starting trajectory.
 1. Writing frequency in the format ''mm hh dd'', e. g. if ''0 0 1'' is specified, the data will be written out every 24 hours.
 1. User name
 1. Number of output parameters
 1. List of output parameters


=== Initial positions of air parcels ===
This file includes the starting positions of the trajectories (longitudes, latitudes and levels) and  the corresponding starting times.  To create it the package [[pos]] can be used. It has to be a file in NetCDF data format with the following variables:

 * ''TIME_INIT'': time in Julian Seconds
 * ''LAT'': latitudes in deg N, valid range [-90,90]
 * ''LON'': longitudes in deg E, valid range [0,360]
 * ''THETA''|''ZETA'': potential temperature in K or <<BR>> ''PRESS'': pressure in hPa  

If the vertical coordinate ZETA is used, there must be a global attribute ''exp_VERTCOOR_name'' which is set to "zeta".

[[/InitExample | Example for init file ]]

=== Meteorological data ===
The data files with meteorological data used by the trajectory program must contain the coordinate variables:

 * ''time'': (one) time in julian seconds
 * ''lat'': latitudes in deg N, valid range [90,-90] (in decreasing order)
 * ''lon'': longitudes in deg E, valid range [0,360]
 * ''theta''|''zeta'': potential temperature in K (in ascending order) or <<BR>>  ''press'': pressure levels in hPa (in descending order) or <<BR>> ''hybrid'': model levels

LAT and LON must build a regular grid.

Besides the files must include at least the four-dimensional data sets for the variables:

 * ''U'': westerly wind
 * ''V'': southerly wind
 * for 3d runs: ''THETA_DOT''|''ZETA_DOT'': vertical velocity in K/day or <<BR>>  ''OMEGA'': vertical velocity in Pa/sec <<BR>> The name of this variable is specified in line 9 of ''traj.inp''.
 * for wind files on model levels: vertical coordinate used in initial positions file (THETA|ZETA|PRESS)
 * output parameters (listed in line 17)

The filenames must correspond to the format:

 . ''prefix''_`yymmddhh`.''nc''<<BR>> ''prefix'' : specified in line 3  <<BR>> `yymmddhh` : valid time <<BR>> e. g.: ''ecmwf_99022812.nc''

[[/WindfileExample | Example for isentropic file]]

[[/WindfileExampleHybrid | Example for wind file on model levels ]]

=== Output file ===
The output file is created in NetCDF data format and is named:

 . traj_xxx_3d_yymmddhh_yymmddhh.nc

The characters `xxx` are read from the configuration file (line 5) and the two times are the start and end time of trajectory calculation.

The dimensions in the trajectory output file are:

 * ''time'': number of written timesteps
 * ''NPARTS'': number of start positions/trajectories

The file contains the following variables:

 * ''time''(time): output times in julian seconds
 * ''DATE_TIME''(time,7): readable time (year, month, day, hour, minute, second, millisecond)
 * ''LAT''(time,NPARTS): latitudes in deg N
 * ''LON''(time,NPARTS): longitudes in deg E
 * ''THETA''|''ZETA''(time,NPARTS): potential temperature in K or <<BR>> ''PRESS'': pressure in hPa

It also contains the variables specified in the configuration file (line 17). Possible output variables are ''TEMP, U, V, PV, SZA'' and for isentropic files also ''PRESS''.

Further variables can be added to the trajectory output file using the program [[traj_add]].

If there are different starting times for the trajectories the data set also contains variables with the prefix ''start_'' (''start_time, start_LAT, start_LON'' etc.). These are arrays with the dimension ''NPARTS'' containing the values at the starting times of the trajectories.

If the trajectories end at different times, the values at the end times will be written on variables with the prefix ''end_'' (''end_time, end_LAT'' etc.).

[[/OutputExample | Example for trajectory output file]]