Subversion Repositories lagranto.um

Rev

Rev 3 | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 3 Rev 4
1 
.TH lagranto
 1 
.TH lagranto
2 
.SH NAME
2 
.SH NAME
3 
.B lagranto -
3 
.B lagranto -
4 
master script for a trajectory calculation, including definition of the starting positions, tracing of meteorological fields and selection of trajectories
 4 
master script for a trajectory calculation, including definition of the starting positions, tracing of meteorological fields and selection of trajectories
5 
.SH SYNOPSIS
 5 
.SH SYNOPSIS
6 
.B lagranto
6 
.B lagranto
7 
.I caseid[.label]
7 
.I caseid[.label]
8 
.I startdate
8 
.I startdate
9 
.I enddate
9 
.I enddate
10 
.I startf
10 
.I startf
11 
.I select
11 
.I select
12 
.I [ optional flags ]
 12 
.I [ optional flags ]
13 
.SH DESCRIPTION
13 
.SH DESCRIPTION
14 
Calculate trajectories for the time period
14 
Calculate trajectories for the time period
15 
.I startdate
 15 
.I startdate
16 
to
16 
to
17 
.I enddate
 17 
.I enddate
18 
for the starting positions given in
18 
for the starting positions given in
19 
.I
 19 
.I
20 
startf,
 20 
startf,
21 
either as position file or as criteria for starting positions. Furthermore, some selection criteria can be applied to the trajectory file, as given either in a selection file or an explicit seclection criterion (given in
 21 
either as position file or as criteria for starting positions. Furthermore, some selection criteria can be applied to the trajectory file, as given either in a selection file or an explicit seclection criterion (given in
22 
.I select
 22 
.I select
23 
). Each tracjectory calculation is given a case identifier
 23 
). Each tracjectory calculation is given a case identifier
24 
.I caseid
 24 
.I caseid
25 
which determines where the input data and output files are located.
 25 
which determines where the input data and output files are located.
26 
.SH PARAMETERS
 26 
.SH PARAMETERS
27 
.TP 10
 27 
.TP 10
28 
.B caseid
 28 
.B caseid
29 
identifier for a trajectory calculation; "caseid" determines where the input netCDF files are found and where the output trajectory file is written. The different options are:
29 
identifier for a trajectory calculation; "caseid" determines where the input netCDF files are found and where the output trajectory file is written. The different options are:
30 
.B 1) local
 30 
.B 1) local
31 
(the input P and S files must be ready in the directory where Lagranto is called; the output directory is also written to the local directory);
 31 
(the input P and S files must be ready in the directory where Lagranto is called; the output directory is also written to the local directory);
32 
.B 2) casename
 32 
.B 2) casename
33 
(the input files are found in "${HOME}/cdf/casename/" and the output is written to "${HOME}/tra/casename/";
 33 
(the input files are found in "${HOME}/cdf/casename/" and the output is written to "${HOME}/tra/casename/";
34 
.B 3) interim
 34 
.B 3) interim
35 
(the input files are taken from the ERA-Interim archive, the output is written to the local directory);
 35 
(the input files are taken from the ERA-Interim archive, the output is written to the local directory);
36 
.B 4) analysis
 36 
.B 4) analysis
37 
(as in 3), but for the ECMWF operational analysis);
 37 
(as in 3), but for the ECMWF operational analysis);
38 
.B 5) forecast
 38 
.B 5) forecast
39 
(as in 3), but for the ECMWF deterministic forecast).
 39 
(as in 3), but for the ECMWF deterministic forecast).
40 
.TP 10
 40 
.TP 10
41 
.B caseid.label
 41 
.B caseid.label
42 
the specification of "label" is optional; it allows to attribute to the output directory name this label and hence to distinguish between several Lagranto runs. Note that "label" has no influence where the input files are found and where the output directory is writtem to. It only is added to the output directory name!
 42 
the specification of "label" is optional; it allows to attribute to the output directory name this label and hence to distinguish between several Lagranto runs. Note that "label" has no influence where the input files are found and where the output directory is writtem to. It only is added to the output directory name!
43 
.TP 10
 43 
.TP 10
44 
.B startdate
 44 
.B startdate
45 
starting date for the trajectory calculation in format YYYYMMDD_HH(MM). This date defines the reference date and time for the trajectory output, i.e. it corresponds to time 0.
 45 
starting date for the trajectory calculation in format YYYYMMDD_HH(MM). This date defines the reference date and time for the trajectory output, i.e. it corresponds to time 0.
46 
.TP 10
 46 
.TP 10
47 
.B enddate
 47 
.B enddate
48 
end date for the trajectory calculation in format YYYYMMDD_HH(MM); if "enddate" is later than "startdate", a forward trajectory calculation is performed, otherwise a backward calculation. As an example: "20100101_00 20100105_00" is forward, and 20100105_00 20100101_00" is backward in time.
48 
end date for the trajectory calculation in format YYYYMMDD_HH(MM); if "enddate" is later than "startdate", a forward trajectory calculation is performed, otherwise a backward calculation. As an example: "20100101_00 20100105_00" is forward, and 20100105_00 20100101_00" is backward in time.
49 
.TP 10
 49 
.TP 10
50 
.B startf
 50 
.B startf
51 
definition of the starting positions; they can be either available as a
51 
definition of the starting positions; they can be either available as a
52 
.B 1) (lon/lat/pressure)-list
52 
.B 1) (lon/lat/pressure)-list
53 
in a file; as an
 53 
in a file; as an
54 
.B 2) explicit criterion
 54 
.B 2) explicit criterion
55 
(e.g. "point(50,40) @ list(100,200,300,400) @ hPa') - for details, see documentation of
 55 
(e.g. "point(50,40) @ list(100,200,300,400) @ hPa') - for details, see documentation of
56 
.B startf;
 56 
.B startf;
57 
or as
 57 
or as
58 
.B 3) a single point
58 
.B 3) a single point
59 
in the format "longitude latitude pressure".
 59 
in the format "longitude latitude pressure".
60 
.TP 10
 60 
.TP 10
61 
.B select
 61 
.B select
62 
definition of selection criterion; it can be passed either in a file or as an explicit selection criterion (e.g. "GT:PV:2:LAST'). For further details, see documentation of command
 62 
definition of selection criterion; it can be passed either in a file or as an explicit selection criterion (e.g. "GT:PV:2:LAST'). For further details, see documentation of command
63 
.B select.
 63 
.B select.
64 
.SH OPTIONAL PARAMETERS
 64 
.SH OPTIONAL PARAMETERS
65 
.TP 10
 65 
.TP 10
66 
.B -o filename
 66 
.B -o filename
67 
name of the output trajectory file; default filename is "lsl_{startdate}".
 67 
name of the output trajectory file; default filename is "lsl_{startdate}".
68 
.TP 10
 68 
.TP 10
69 
.B -j
69 
.B -j
70 
jumping flag; if the trajectory runs into the ground, it is lifted a little and allowed to move on. This flag is directly passed to the command
 70 
jumping flag; if the trajectory runs into the ground, it is lifted a little and allowed to move on. This flag is directly passed to the command
71 
.B caltra.
 71 
.B caltra.
72 
See documentation for "caltra" for further details.
 72 
See documentation for "caltra" for further details.
73 
.TP 10
 73 
.TP 10
74 
.B -v tracefile
 74 
.B -v tracefile
75 
name of the tracing file which enlists all fields to be traced along the trajectories; the tracing file is directly passed to
 75 
name of the tracing file which enlists all fields to be traced along the trajectories; the tracing file is directly passed to
76 
.B create_startf
 76 
.B create_startf
77 
and
77 
and
78 
.B trace
 78 
.B trace
79 
(see documentation of these two commands for further details).
79 
(see documentation of these two commands for further details).
80 
.TP 10
 80 
.TP 10
81 
.B -r regionfile
 81 
.B -r regionfile
82 
name of the region file which enlists all regions; the region file is directly passed to
 82 
name of the region file which enlists all regions; the region file is directly passed to
83 
.B create_startf
 83 
.B create_startf
84 
and
84 
and
85 
.B select
 85 
.B select
86 
(see documentation of these two commands for further details).
86 
(see documentation of these two commands for further details).
87 
.TP 10
 87 
.TP 10
88 
.B -changet
 88 
.B -changet
89 
change the times on the netCDF files relative to the starting date; Lagranto expects the netCDF times to be relative to the starting date. The default value of "-changet" is false.
89 
change the times on the netCDF files relative to the starting date; Lagranto expects the netCDF times to be relative to the starting date. The default value of "-changet" is false.
90 
.TP 10
 90 
.TP 10
91 
.B -noclean
 91 
.B -noclean
92 
do no cleaning after a trajectory run; the default is that the output directory will be cleaned. If cleaning is requested (the default), the following files will be kept in the outputdirectory:
92 
do no cleaning after a trajectory run; the default is that the output directory will be cleaned. If cleaning is requested (the default), the following files will be kept in the outputdirectory:
93 
.B 1) the output trajectory file;
93 
.B 1) the output trajectory file;
94 
.B 2) the log file of the trajectory run;
94 
.B 2) the log file of the trajectory run;
95 
.B 3) the run script.
95 
.B 3) the run script.
96 
All other files are deleted.
 96 
All other files are deleted.
97 
.TP 10
 97 
.TP 10
98 
.B -log
 98 
.B -log
99 
write log of Lagranto run on screen instead into a file. No log file will be created with this option.
 99 
write log of Lagranto run on screen instead into a file. No log file will be created with this option.
100 
.TP 10
 100 
.TP 10
101 
.B -prep
 101 
.B -prep
102 
create the run directory, prepare all files and build the run script - but do not run it. Hence, everything is ready for the Lagranto run, but it is not launched. It can be launched manually, possibly after some manual modifications to the run script, with the following steps:
 102 
create the run directory, prepare all files and build the run script - but do not run it. Hence, everything is ready for the Lagranto run, but it is not launched. It can be launched manually, possibly after some manual modifications to the run script, with the following steps:
103 
.B 1) change to run directory
103 
.B 1) change to run directory
104 
(for instance with "lagranto -open caseid.label");
 104 
(for instance with "lagranto -open caseid.label");
105 
.B 2) start the run script
 105 
.B 2) start the run script
106 
(with ./runscript.sh, where you have to pass the name of your runscript name).
106 
(with ./runscript.sh, where you have to pass the name of your runscript name).
107 
.SH INPUT FILES
 107 
.SH INPUT FILES
108 
A sucessful Lagranto runs needs several input files; the following list shows all mandatory and optional input files
 108 
A sucessful Lagranto runs needs several input files; the following list shows all mandatory and optional input files
109 
.TP 10
 109 
.TP 10
110 
.B P and S files [mandatory]
 110 
.B P and S files [mandatory]
111 
input netCDF files; at least the following meteeorological fields must be available on the P files: U=zonal wind [m/s]; V=meridional wind [m/s]; OMEGA=vertical wind [Pa/s]; PS=surface pressure [hPa]. Secondary field can be made available on the S file. Both P and S files have the following format: [P|S]YYYYMMDD_HH, e.g. P20100101_00 for 1st January 2010, 00 UTC.
111 
input netCDF files; at least the following meteeorological fields must be available on the P files: U=zonal wind [m/s]; V=meridional wind [m/s]; OMEGA=vertical wind [Pa/s]; PS=surface pressure [hPa]. Secondary field can be made available on the S file. Both P and S files have the following format: [P|S]YYYYMMDD_HH, e.g. P20100101_00 for 1st January 2010, 00 UTC.
112 
.TP 10
 112 
.TP 10
113 
.B tracevars [optional]
 113 
.B tracevars [optional]
114 
tracing file where all meteorological fields are listed which should be traced along the trajectories. The tracing file is needed by the program
114 
tracing file where all meteorological fields are listed which should be traced along the trajectories. The tracing file is needed by the program
115 
.B create_startf
 115 
.B create_startf
116 
and particularly
 116 
and particularly
117 
.B trace
 117 
.B trace
118 
(for further details about the format of the file, consider the documentation for these two commands). If no tracing of meteorological fields is needed, no tracing file must be specified. Furthermore, the name of the file can be changed from its default (tracevars) with the optional parameter "-v filename" (see above).
 118 
(for further details about the format of the file, consider the documentation for these two commands). If no tracing of meteorological fields is needed, no tracing file must be specified. Furthermore, the name of the file can be changed from its default (tracevars) with the optional parameter "-v filename" (see above).
119 
.TP 10
 119 
.TP 10
120 
.B regionf [optional]
 120 
.B regionf [optional]
121 
region specification for definition of strting positions (with
 121 
region specification for definition of strting positions (with
122 
.B create_startf
 122 
.B create_startf
123 
) or application of Lagrangian selection criteria (with
 123 
) or application of Lagrangian selection criteria (with
124 
.B select
 124 
.B select
125 
). If no region is used in either "select" or "create_startf", no region file must be specified. The name of the region file can be changed from its default (regionf) with the option "-r filename".
125 
). If no region is used in either "select" or "create_startf", no region file must be specified. The name of the region file can be changed from its default (regionf) with the option "-r filename".
126 
.TP 10
 126 
.TP 10
127 
.B startf [optional]
 127 
.B startf [optional]
128 
definition of the starting positions, either as an explicit list of longitude, latitude, pressure; or as a criterion saved on the file. If the specification of the starting positions is done with an explicit specification in
 128 
definition of the starting positions, either as an explicit list of longitude, latitude, pressure; or as a criterion saved on the file. If the specification of the starting positions is done with an explicit specification in
129 
.B create_startf
 129 
.B create_startf
130 
(e.g. "point(50,40) @ list(100,200,300) @ hPa") no starting file is needed.
 130 
(e.g. "point(50,40) @ list(100,200,300) @ hPa") no starting file is needed.
131 
.TP 10
131 
.TP 10
132 
.B select [optional]
 132 
.B select [optional]
133 
definition of a selection criterion for command
 133 
definition of a selection criterion for command
134 
.B select.
 134 
.B select.
135 
If the selection criterion is given explicitely in the Lagranto call (e.g. GT:PV:2), no selection file is needed.
 135 
If the selection criterion is given explicitely in the Lagranto call (e.g. GT:PV:2), no selection file is needed.
136 
.SH OUTPUT FILES AND STRUCTURE
 136 
.SH OUTPUT FILES AND STRUCTURE
137 
For a Lagranto run a new directory will be created where all needed files are prepared. The name of the directory and the file within it (if cleaning is invoked) are:
 137 
For a Lagranto run a new directory will be created where all needed files are prepared. The name of the directory and the file within it (if cleaning is invoked) are:
138 
.TP 10
 138 
.TP 10
139 
.B ntr_${startdate}_{dir}${timerange}_{startf}_{select}
 139 
.B ntr_${startdate}_{dir}${timerange}_{startf}_{select}
140 
for instance, the Lagranto call "lagranto local 20100101_00 20100102_00 startf selectf" will create the directory "ntr_19891020_00_f24_local_startf_selectf". Correspondingly, for a backward calculation the name would be "ntr_19891021_00_b24_local_startf_selectf", i.e. the {dir} is set to 'b'.
 140 
for instance, the Lagranto call "lagranto local 20100101_00 20100102_00 startf selectf" will create the directory "ntr_19891020_00_f24_local_startf_selectf". Correspondingly, for a backward calculation the name would be "ntr_19891021_00_b24_local_startf_selectf", i.e. the {dir} is set to 'b'.
141 
.TP 10
 141 
.TP 10
142 
.B ls_${startdate}
 142 
.B ls_${startdate}
143 
default name of the output trajectory file placed in the ntr directory. The name can be changed with the option "-o filename". Note further that different output formats are supported, as described  in the documentation for command
143 
default name of the output trajectory file placed in the ntr directory. The name can be changed with the option "-o filename". Note further that different output formats are supported, as described  in the documentation for command
144 
.B reformat.
 144 
.B reformat.
145 
.TP 10
 145 
.TP 10
146 
.B runscript.sh
 146 
.B runscript.sh
147 
name of the run script, i.e. the script within the ntr directory which calls all Fortran programs. It cn be manually started with "./runscript.sh".
 147 
name of the run script, i.e. the script within the ntr directory which calls all Fortran programs. It cn be manually started with "./runscript.sh".
148 
.TP 10
 148 
.TP 10
149 
.B runscript.logfile
 149 
.B runscript.logfile
150 
name of the log file; all status information is written to this file. If a Lagranto run fails, this is the place where to start loking for the reason!
 150 
name of the log file; all status information is written to this file. If a Lagranto run fails, this is the place where to start loking for the reason!
151 
.SH SPECIAL COMMANDS
 151 
.SH SPECIAL COMMANDS
152 
The main focus of
152 
The main focus of
153 
.B lagranto
 153 
.B lagranto
154 
is to combine the calls to "create_startf", "caltra", "trace" and "select" into one convenient call. In addition to this, "lagranto" offers some handy special commands which allow more efficient working.
154 
is to combine the calls to "create_startf", "caltra", "trace" and "select" into one convenient call. In addition to this, "lagranto" offers some handy special commands which allow more efficient working.
155 
.TP 10
 155 
.TP 10
156 
.B -open caseid.label
 156 
.B -open caseid.label
157 
open a new
157 
open a new
158 
.B xterm
158 
.B xterm
159 
window and change to the run directory. If several directories with the same case ID are found, the user is interactively asked to choose one.
 159 
window and change to the run directory. If several directories with the same case ID are found, the user is interactively asked to choose one.
160 
.TP 10
 160 
.TP 10
161 
.B -remove caseid.label
 161 
.B -remove caseid.label
162 
remove a run directory. If several directories with the same case ID are found, the user is interactively asked to choose one.
 162 
remove a run directory. If several directories with the same case ID are found, the user is interactively asked to choose one.
163 
.TP 10
 163 
.TP 10
164 
.B -show caseid.label
 164 
.B -show caseid.label
165 
show the contents of the trajectory file as a list. If several directories with the same case ID are found, the user is interactively asked to choose one.
 165 
show the contents of the trajectory file as a list. If several directories with the same case ID are found, the user is interactively asked to choose one.
166 
.SH EXAMPLES
 166 
.SH EXAMPLES
167 
.TP 5
 167 
.TP 5
168 
.B [1] lagranto local 19891020_00 19891021_00 startf nil -changet
 168 
.B [1] lagranto local 19891020_00 19891021_00 startf nil -changet
169 
a forward trajectory calculation from 00 UTC, 20 October 2010 to 00 UTC, 21 October 2010. The starting positions are taken from the file "startf". No selection criterion is applied (nil), and the times on the input netCDF files are set relative to the starting date in advance.
169 
a forward trajectory calculation from 00 UTC, 20 October 2010 to 00 UTC, 21 October 2010. The starting positions are taken from the file "startf". No selection criterion is applied (nil), and the times on the input netCDF files are set relative to the starting date in advance.
170 
.TP 5
 170 
.TP 5
171 
.B [2] lagranto local 19891020_00 19891021_00 startf 'GT:PV:2:LAST' -changet
 171 
.B [2] lagranto local 19891020_00 19891021_00 startf 'GT:PV:2:LAST' -changet
172 
as in example [1], but now an explicit selection criterion is applied (GT:PV:2:LAST) - the potential vorticity at the end date (19891021_00) must be larger than 2 PVU.
 172 
as in example [1], but now an explicit selection criterion is applied (GT:PV:2:LAST) - the potential vorticity at the end date (19891021_00) must be larger than 2 PVU.
173 
.TP 5
 173 
.TP 5
174 
.B [3] lagranto local 19891020_00 19891021_00 startf 'GT:PV:2:LAST' -changet -prep
 174 
.B [3] lagranto local 19891020_00 19891021_00 startf 'GT:PV:2:LAST' -changet -prep
175 
as in the previous two examples, but now only the files and runscript are prepared: no Lagranto run is launched! To do so, you might change to the run directory with
 175 
as in the previous two examples, but now only the files and runscript are prepared: no Lagranto run is launched! To do so, you might change to the run directory with
176 
.B lagranto -open local
 176 
.B lagranto -open local
177 
and then start it manually with
 177 
and then start it manually with
178 
.B ./runscript.sh.
 178 
.B ./runscript.sh.
179 
.SH AUTHOR
 179 
.SH AUTHOR
180 
Written by Michael Sprenger and Heini Wernli (January 2011)
 180 
Written by Michael Sprenger and Heini Wernli (January 2011)