SMS:PTM Trap Output

From XMS Wiki
Revision as of 21:24, 31 January 2014 by Jcreer (talk | contribs)
Jump to navigationJump to search

Trap output files are generated by PTM when one or more traps have been specified (this can be done by linking to an existing "*.trap" file or SMS will create this file from a PTM coverage containing trap objects.

A PTM trap file is a tabular ASCII file which contains information about when parcels entered specific traps in a PTM simulation. The first row of the file must be a header row defining the contents of the file. Each row after the header defines a single entry event of a parcel into a trap

File Overview

The first line of a standard trap output files contains the header defining the standard five columns of output, e.g.:

   STEP     DATE         TIME       PARTICLE    TRAP

The trap output file may also include additional columns which give extra information about the parcel, e.g.:

   STEP     DATE         TIME       PARTICLE    TRAP        MASS        MEDIAN_SIZE        SOURCE

The header line is followed by entry lines. Each line defines an entry event of a parcel into a trap:

STEP DATE TIME PARTICLE TRAP MASS MEDIAN_SIZE SOURCE
1178 2001/01/01 02:38:10.000 53 1 2 0.1 2
1215 2001/01/01 02:41:15.000 47 3 3 0.05 1
1233 2001/01/01 02:42:45.000 99 1 3 0.2 2
.
.


When SMS is asked to read a trap output file, the file is identified by the extension "*_count.out". If the extension has been modified, SMS can be instructed to read this file using the file import wizard.

When SMS reads the standard trap output file, a time series curve for each trap represented in the file is created counting the number of parcels which entered the trap and logging the time (in hours from the first parcel) that the parcels entered. This is a "Count" time series curve. These time series curves are monotonically increasing.

If one or more "Value" column is specified when reading the file, SMS also creates one curve for each trap showing the accumulated value from this column. In the example above, the "MASS" column could be mapped as a value and the cumulative mass of each parcel would be summed as it enters the trap.

If one or more "Filter" column is specified, SMS asks for filter ranges associated with this quantity. For example, the user may wish to only count the parcels with a mean grain size below 0.15 mm. In this case, the "MEDIAN_SIZE" column above would be mapped as a "Filter" and a range of (0.00-0.15) specified in the filter range dialog that appears after the import wizard specification is complete. A parcel will be counted as in the range if it's value is greater than the minimum and less than or equal to the maximum). Ranges that are specified with the same minimum and maximum values are ignored. The values are always interpreted as doubles even when they represent an integer quantity such as "SOURCE". In this case, the ranges could be specified as (0.5-1.5) and (1.5-2.0) to filter out parcels from a specific source. SMS will create additional curves (both for count and cumulative value) for each trap for the parcels that fall into each filter range.

Therefore, the total number of curves created when reading a trap output file would be:

   Num_Curves = (1 + Num_Value_Columns) * (1 + Number_Filter_Ranges) * Number_Traps

These curves can be viewed using the Plot Wizard and selecting PTM Gage plots.