SMS:PTM Trap File

From XMS Wiki
Revision as of 20:22, 16 April 2013 by Jcreer (talk | contribs)
Jump to navigationJump to search

A PTM trap file defines areas into which parcels enter and are counted. The traps can be open or closed traps. When a parcel enters an open trap, it is free to leave the trap. When a parcel enters a closed trap, it is not allowed to leave the trap. If the trap is a single trap, each parcel is only counted once per simulation.

File Overview

The first line contains the number of line traps, NLT. This is a single integer value. Any comments can follow on the line, e.g.:

    1 Line Trap(s)

This is followed by NLT blocks of data. Each block of data contains:

  • An identification line giving the trap id number, and a label. In this example, there is one line trap, known as “My Line Trap”, that has an id of two:
    2 My Line Trap
  • A single line giving the trap direction, trap bottom elevation, trap top elevation, open trap flag, and single count trap flag:
    0  3  15  0  1
  • Two lines giving the x, y location of the line trap endpoints:
    3.99000000000000e+001 1.07600000000000e+002
    4.92000000000000e+001 1.78200000000000e+002

The next set of data contains information for Polygon Traps. The points must be ordered using a standard counter-clockwise convention. This begins with the number of Polygon Traps, NPT. This is a single integer value. Comments can follow on the line, e.g.:

    1 Polygon Trap(s)

This is followed by NPS blocks of data. Each block of data contains:

  • An identification line giving the trap id number, and a label, e.g.:
    1 My Polygon Trap
  • A single line giving the number of points in the trap, NP, trap bottom elevation, trap top elevation, open trap flag, and single count trap flag:
    8 2 5 1 0
  • For each point in the polygon (1 point per line), the point id, x, y location of the point:
    1 1.78600000000000e+001 2.39300000000000e+001
    2 3.54200000000000e+001 1.46700000000000e+001
    3 7.29400000000000e+001 2.04200000000000e+001
    4 7.91600000000000e+001 5.42600000000000e+001
    5 6.11200000000000e+001 7.88400000000000e+001
    6 2.93600000000000e+001 8.14000000000000e+001
    7 9.08000000000000e+000 6.55900000000000e+001
    8 3.97000000000000e+000 5.18600000000000e+001

Trap File Flag Values

Flag Value(s)
Trap direction -1 (decreasing x-coordinate), 0 (any direction), or 1 (increasing x-coordinate)
Open trap 0 (closed trap) or 1 (open trap)
Single count trap 0 (Count parcels every time they enter a trap) or 1 (Count parcels once per simulation)

If the keyword :LAST_STEP_TRAP is included in the Program Control File (PCF File), the traps will only be active on the last time step of the PTM simulation.

Example Trap File

1 Line Trap(s)
 0 My Line Trap
  0  2  12  1  0
   -5.28000000000000e+000 7.08600000000000e+001
   4.67600000000000e+001 8.57100000000000e+001
1 Polygon Trap(s)
 1 My  Polygon Trap
  6 5 20 0 1
   1 3.55800000000000e+001 1.56300000000000e+001
   2 6.54300000000000e+001 1.45100000000000e+001
   3 7.64500000000000e+001 2.90400000000000e+001
   4 5.92100000000000e+001 5.42600000000000e+001
   5 3.36700000000000e+001 5.18600000000000e+001
   6 2.18500000000000e+001 3.06300000000000e+001
*********************************************************************************************************
* Guide:
*********************************************************************************************************
Number of Line Traps(s)
For each Line Trap:
  Trap ID, Trap Name
   Trap Direction, Trap Bottom, Trap Top, Open Trap, Single Trap
    First node x1_location, y1_location
    Second node x2_location, y2_location
Number of Polygon Trap(s)
For each Polygon Trap:
  Trap ID, Trap Name
   Number of points in trap, Trap Bottom, Trap Top, Open Trap, Single Count Trap
    For each point: (1 point per line): x_location, y_location
*********************************************************************************************************
* Trap Keyword Values:
*********************************************************************************************************
Line Trap Direction:
  -1 (decreasing x-coordinate), 0 (any direction), or 1 (increasing x-coordinate)
  Default value is 0 (any direction)
Open Trap:
  0 (closed trap) or 1 (open trap)
  Default value is 1 (open trap)
Single Count Trap:
  0 (Count parcels every time they enter a trap) or 1 (Count parcels once per simulation)
  Default value is 0 (Count parcels every time they enter a trap)
*********************************************************************************************************
* Trap file written by SMS 10.1.0 Development Release
* SMS Build Date: Sep  9 2008
* Date saved: 09/09/08
* Time saved: 14:05:03
*********************************************************************************************************

Related Topics