PTM Frequently Asked Questions (FAQ)

Moving from ptm source directory in github. This should belong in the documentation and not buried in source code

Q1. What is PTM?

PTM is Particle Tracking Model. It is written partly in Java and partly in Fortran. I/O is mainly handled by Fortran.

Q2. What are the inputs to PTM?

1. Hydrodynamic information:
This is the dynamic information about flow, flow-area, (therefore velocity) and depth. This information comes from the tidefile which is generated by hydro. One has to make sure that in addition to the tidefile the correct network configuration is being used. This information is typically done by the following io structure.

TIDEFILE
START_DATE START_TIME END_DATE END_TIME FILENAME
generic none length none tidefile.out
END

2. Network configuration:
This defines how channels and reservoirs are linked up and what their characteristics such as x-section, length, etcetra are. This also is read by Fortran. - channels.inp, xsects.inp, junctions.inp, reservoirs.inp, translations.inp

Refer to DSM2 docs

3. Particle information:

a. Type of particle:
Uptil now we have been dealing only with neutrally-bouyant or particles with a certain falling velocity. For other kind of particles such as fish no IO had been decided.

b. Particle insertion information:
Number of particles, time of insertion, location of insertion and duration of insertion. Refer to ptm_insertion.inp.

PARTINP
[NODE NPARTS SDATE STIME EDATE ETIME] |
44 500 01jan1990 0133 05jan1990 0333

This means that insert 500 particles at 44 evenly distributed from start time to end time

[NODE NPARTS SDATE LENGTH]
44 600 01jan1990 5days
END

c. Run time information

This is similar to run time settings for hydro and qual. Refer to DSM2 docs.

d. PTM has the following scalars

SCALAR
ptm_time_step 15min # PTM time step
display_intvl 1hour # how often to display run progress
ptm_ivert t # Use Vertical velocity profile
ptm_itrans t # Use Transverse velocity profile
ptm_iey t # Use transverse mixing
ptm_iez t # Use vertical mixing
ptm_fallvel 0.05 # settling velociy in ft/s
ptm_random_seed 32001 # Starting Random Number Seed
ptm_trans_constant 0.06 # Transverse Mixing Constant
ptm_vert_constant 0.0067 # Vertical Mixing Constant
END

d. IO from PTM

IO_FILES
MODEL TYPE IO INTERVAL FILENAME
ptm anim out 15min anim.bin # animation file
ptm trace out none trace.bin # trace file
ptm restart out 6hours restart.out # restart output file
ptm restart in none restart.inp # restart input file
END

Animation file:
Contains the data for the first 100 particles movement every time interval as specified. This is a binary file if the file name does not end in ".out" else it will be a ascii file. One can use PTM Animator to run the binary file to look at the animation visually

Trace file:
The trace file contains the trace of every particle in the system. It records the entrance/exit of a particle into a waterbody such as a channel etcetra. ".out" for ascii file. The trace file is used to calculate the flux and so the flux may be calculated after the PTM run.

Restart file:
This is a snapshot of the current locations of every particle inthe system. Useful mainly for restarting a run from a previously saved state.

This instructs ptm to calculate flux from the trace file. This can be done at the end of a ptm run or from a trace file later. Its the users responsibility to provide the correct network configuration The filename flux.txt means the user wants the output in ascii format else it would be flux.dss which is output in dss format. The DSS pathnames B part == B_PART from the above table.

The interval at which the flux is calculated is as given above in the

INTERVAL column

The particle flux is calculated from a waterbody to a waterbody. A waterbody is specified by a type string followed by an identifier. The type string is one of chan, res, qext, stage.

The identifier is either a number for the the chan or a name as defined in the translations.inp file. If a generic type follows in place of the identifier than the flux tracks all particles entering or leaving that particular type of waterbody. If no from_wb or to_wb is defined it is
assumed that it is the same as to all waterbodies.

Particle dynamics:

The particle can move in x, y and z directions. However as DSM2 is a 1-D model this information is gleaned by applying a vertical and transverse velocity profile to the average velocity available from the tidefile.

A particle has a deterministic and random component to its movement.

Deterministic component == Average velocity + transformations