cdflagr −− compute lagrangian parcel trajectories
cdflagr u [v [w]] time_var tstart dt ntminus ntplus [select_var value ... ]
Cdflagr accepts a common data format file on the standard input containing one, two, or three−dimensional eulerian flow fields and writes a common data format file to the standard output containing trajectories of parcels computed from the flow fields. In addition, values of all input variable fields with the same domain as the flow fields are interpolated along the parcel trajectories and included in the output.
Cdflagr determines the dimensionality of the space in which trajectories are drawn by examining all index fields in the static slice. Each index field is assumed to correspond to a dimension, and all flow fields must have their dimensions correspond in name and size to the index fields.
The names of the existing flow field components are requested on the command line, and are represented by u, v, and w in the synopsis. For one−dimensional fields, only u is required, where as two and three dimensional fields respectively require v, and v and w as well. If the names substituted here don’t exist in the input file, cdflagr reports an error and dies.
Successive variable slices are assumed to represent flow and other fields at successive times, which must be monotonically increasing, but need not be equally spaced. A scalar variable field named time_var must contain the time at which each variable slice is defined. The integration is begun at time = tstart and is done by forward differencing with time step dt for -ntminus + 1 steps backward in time and ntplus - 1 steps forward in time. Ntminus must be zero or negative, and ntplus must be zero or positive. The time step dt must be positive.
In computing trajectories, cdflagr linearly interpolates between slices and between eulerian grid points within each slice in order to define field values at parcel positions. An exception occurs when the interpolated value in one slice is good and the other is bad. In this case the good value alone is used. If parcels exit the space defined by the index fields, the integration is terminated. If integration times outside the range of those available in the first or last variable slice are requested, field values from one or the other of these limiting slices are taken. Care is therefore required to keep the interval [tstart, tstart + dt*nt] bounded by available times in time−dependent situations. On the other hand, trajectories in time−independent situations are correctly computed from an input file with a single variable slice using this scheme. If only a single time is available in a time−dependent situation, the computed "trajectories" are actually streamlines valid at the time in question.
Cdflagr normally starts parcels from every grid point in the space that has a valid flow velocity. This is often undesirable as it can result in a huge number of trajectories in a three−dimensional situation. Parcel initiation can be confined to planes or lines parallel to coordinate axes, or to a single point, by including optional selection variables (select_var) and their corresponding values on the command line. These variables must correspond in name to one of the index fields. The particular plane or line selected is that with the index value closest to the requested value. The number of selection variables must not exceed the number of dimensions, and each dimension may only be selected once.
The output common data format file has the following format. The static slice has two index fields, "time" and "parcel". The time index field contains the times at which the parcel positions are defined, i. e., over the range [tstart + (ntminus + 1)*dt, tstart + (ntplus - 1)*dt] at intervals of dt. Note that the times of input slices are lost. The parcel field simply contains sequential integers starting from zero, and may be thought of as a parcel labelling device.
The single variable slice contains two−dimensional fields with "parcel" being the first dimension and "time" being the second dimension. The fields present are "x", and possibly "y" and "z", depending on the dimensionality of the flow field. In addition, all input fields defined over the same space as the flow field are sampled along parcel trajectories. These are given the same names on output as they have on input, though of course they have a lagrangian rather than an eulerian interpretation. No input fields are passed to the output.
The above−defined output structure facilitates direct plotting of results using the program cdfplot "z" plots the y−z projection of parcel trajectories for each parcel, while graphing the input field "a" against "z" results in z−profiles of "a" for all parcels.
kestrel%cdflagr ux uz time 10 0.1 0 50 < infile > outfile
In this instance cdflagr looks for variable fields named "ux" and "uz" as the components of a two−dimensional flow field in the file "infile". A time variable named "time" is sought, and the time integration is started at time = 10 and continued for 50 − 1 = 49 steps at intervals of 0.1. Parcel trajectories are initiated at every grid point. Cdflagr knows to interpret only the first two command line arguments as velocity components as it (presumably) finds only two index fields in the static slice of "infile". The lagrangian trajectories are written to "outfile".
kestrel%cdflagr u v w tempus 20 1 -100 0 z 4 x 8 < infile > outfile
This case differs from the one above in that a three−dimensional space is assumed (and cdflagr better find three index fields!) and parcels are only initiated along a line defined by z = 4 and x = 8. There should be index fields named x and z in "infile".
Cdfpsel accepts cdflagr output, passing only those trajectories that meet specified conditions.
If the number of index files and the number of flow components aren’t equal, either obscure diagnostics result, or the output is total nonsense. Beware!
Cdflagr reads the entire input file into memory so that backward stepping in time may easily be done. This could be a problem for very large files. However, on virtual memory systems, paging death is avoided by time−stepping all parcels at once. Thus, if real memory can accomodate two input variable slices plus the output variable slice, each slice need be paged in only once.