SMS:PTM Program Control File

The PTM program control file (.pcf) contains run time instruction for the model.

File Overview

The program control file (PCF) contains all the information necessary for the PTM to perform the simulation requested. The PCF file is a keyword oriented file. Lines in the file should contain either comments, with the line beginning with a "#" symbol, or a keyword, a single word beginning with a colon, ":", and its associated values. Some keywords have no associated values, e.g.:

    :MOBILITY_MAPPING

These are generally on/off instructions to the model. Keywords pointing ot filenames or setting constants have one or two associated values, e.g.:

    :MESH_FORMAT ADCIRC
    :MESH_FILE estuary.grd

Keywords and values are not case sensitive with the single exception of the simulation output file names (i.e. file names like "Run_C1_Tp_12s_paths.out" are possible).

The PCF file is read until the instruction :

    :END_DATA

is encountered.

The following list summarizes the rules for construction of a PCF:

• Keywords should be preceeded with ":".
• Comments should be preceeded with "#".
• Keywords are not case sensitive.
• Keywords and value(s) are white space delimited (tab or space) and, so, should not contain blanks.
• Keywords may be placed in any order in the file.
• If a keyword appears more than once, then the final incidence is used.
• All value units are S.I.
• All times are relative to the clock defined by the currents file.

Example PCF File

##########################################################
# PTM Simulation file written by SMS 9.2.1
# SMS Build Date: Mar  9 2007
# Date: 03/09/07
# Time: 16:36:04
##########################################################
:CURRENTS
#
:ID_OUTPUT
:ELEVATION_OUTPUT
:GRAIN_SIZE_OUTPUT
:MOBILITY_OUTPUT
:STATE_OUTPUT
:PARCEL_MASS_OUTPUT
:OUTPUT_INC 10
:MAPPING_INC 1000
#
:BY_WEIGHT
:GRID_UPDATE 300
#
:MESH_FORMAT ADCIRC
:MESH_FILE estuary.grd
:FLOW_FORMAT XMDF
:FLOW_FILE_XMDF estuary_tide.h5
:XMDF_VEL_PATH Datasets/tide only velocity
:XMDF_WSE_PATH Datasets/tide only wse
:NEIGHBOR_FILE estuary.neighbors
:SOURCE_FILE estuary_Tides.source
:SEDIMENT_FILE estuary.sediments
:OUTPUT_PREFIX estuary_Tides
#
:START_RUN 2004 2 11 0 0 0
:STOP_RUN 2004 2 12 7 45 0
:START_FLOW 2004 2 9 0 0 0
#
:TIME_STEP 3.000000
#
:KET 0.25
:KEV 0.00859
:TEMPERATURE 15
:SALINITY 34
:RHOS 2650
:MIN_DEPTH 0.01
#
:ETMIN 0.02
:EVMIN 0
#
:EMRL_GUID_COV 7d0bcdf2-f218-4046-ba24-218294d74794
:EMRL_PARTICLE_SET_GUID b7183313-bcba-45d9-8cf7-f6ce96cf1d45
:END_DATA

Keywords

Keyword	Value(s)	Action
:waves		Instructs the model that waves are to be runs in the model. Turns on the various wave flags. Default is inactive.
:currents		Instructs the model that currents are to be runs in the model. Turns on the various wave flags. Default is inactive.
:no_parcels		Instructs the model to only perform Eulerian calculations (i.e. no particles are released). Source file is not required if this option is used. Default is inactive.
:ensim		Tells the model that the input bathymetry file uses the CHC EnSim convention of positive upwards. Default is inactive. Default is inactive.
:paths		Instructs the model to output the parcel path files. Default is inactive.
:morphology		Instructs the model to output the predicted bed evolution on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Same result as “:bed_level_mapping “. Default is inactive.
:flow_mapping		Instructs the model to output the flow conditions on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Default is inactive.
:bedform_mapping		Instructs the model to output the predicted native sediment bedforms on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Default is inactive.
:wave_mapping		Instructs the model to output the three predicted wave parameters (H, T, θ) on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Default is inactive.
:mobility_mapping		Instructs the model to output the predicted mobility of the native sediments on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Same result as “:morphology”. Default is inactive.
:bed_level_mapping		Instructs the model to output the predicted bed evolution on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Same result as “:morphology“. Default is inactive.
:bed_level_change_mapping		Instructs the model to output the predicted bed level change on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Default is inactive.
:transport_mapping		Instructs the model to output the predicted potential sediment transport rate of the native sediments on the Eulerian mesh node locations. Frequency of output is given by ‘mapping_inc’. Default is inactive.
:grain_size_output		Instructs the model to output the grain size of the parcels. Frequency of output is given by ‘output_inc’. Default is inactive.
:mobility_output		Instructs the model to output the mobility of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:elevation_output		Instructs the model to output the elevation of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:height_output		Instructs the model to output the height of each parcel above the bed. Frequency of output is given by ‘output_inc’. Default is inactive.
:state_output		Instructs the model to output the state of each parcel (active=1, dormant=0). Frequency of output is given by ‘output_inc’. Default is inactive.
:id_output		Instructs the model to output the identification number of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:source_output		Instructs the model to output the original source of the each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:flow_output		Instructs the model to output the velocity components of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:density_output		Instructs the model to output the density of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:parcel_mass_output		Instructs the model to output the mass of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:time_step	<real>	The time step of the simulation in seconds, e.g.: time_step 2. Input value required.
:by_weight		Instructs the model to build up the distributions of parcel grain sizes at each source such that they are Gaussian in terms of weight (i.e. “percentage finer by weight”), rather than by grain size. Default is inactive.
:no_bedforms		Instructs the model to skip bedform calculations on the Eulerian grid. Default is inactive.
:bed_porosity		Input statement for bed porosity. Default value is 0.4.
:eulerian_method	ptm or van_rijn	Selects which method to use to determine the native sediment mobility and shears on the Eulerian grid. The two choices are ptm and van_rijn, e.g.: eulerian_method van_rijn The ptm method is much faster. Default is ptm.
:centroid_method	rouse or van_rijn	Selects which method to use to determine the parcel mobility and shears. The two choices are rouse and van_rijn, e.g.: lagrangian_method rouse The rouse method uses empirical approximations of integrated Rouse curves. The van_rijn method uses a numerical integration of the total sediment transport at the location of the parcel to compute the centroid elevation. The rouse method if much faster. Default is rouse.
:advection_method	1d (formerly 2d - not available in SMS interface) or 2d (formerly q3d - default) or 3d	Selects which method to use for the advection of the parcels. The three choices are 1d, 2d and 3d, e.g.: advection_method 2d The 1d method places the parcel at the elevation of the centroid of the local total load distribution. The 2d method allows the parcel to be above or below the total load centroid elevation with the parcel moving vertically towards the centroid. The 3d option allows the parcel to move freely in the vertical in response to a vertical force balance. Default is 2d.
:velocity_method	2d (log) or 2d (uniform) or 2d (two-point) or 3d or 3ds or 3dz	Selects which method to use to compute the velocity profile in the vertical, e.g.: velocity_method 3dz The 2d (uniform) option causes the model to use the given velocity throughout the water column. This method is designed primarily for testing. The 2d (log) option causes the model to use a logarithmic velocity profile. The 3d variants force the model to use the given three-dimensional velocity components. These should only be used with three-dimensional input. Default is 2d (log)
:mesh_format	ADCIRC	Gives the format of the mesh file, e.g.: mesh_format ADCIRC Options are CMS-2D, CMS-3D, ADCIRC, M2D and CH3D Default value is ADCIRC.
:mesh_file	<character>	Gives the name of the mesh file, e.g.: mesh_file test.grd Input value required.
:flow_format	ADCIRC or CMS-2D or CMS-3D or CH3D	Gives the format of the hydrodynamic files: flow_format ADCIRC Options are ADCIRC, CMS-2D (for M2D), CMS-3D (for M3D) and CH3D. Default value is ADCIRC.
:flow_files	<character> <character>	Gives names of the hydrodynamic files, e.g.: flow_files A1.63 A1.64 Note that the extensions are optional; if a ‘.’ is not found in the filename, the *.63 and *.64 will be appended. Input values required.
:flow_file_uv	<character>	Gives names of the hydrodynamic flow file, e.g.: flow_file_uv A1.64 Note that the extensions are optional; if a ‘.’ is not found in the filename, the *.64 will be appended. Input values required. This command allows names with spaces, including directories.
:flow_file_z	<character>	Gives names of the hydrodynamic elevation file, e.g.: flow_file_z A1.63 Note that the extensions are optional; if a ‘.’ is not found in the filename, the *.63 will be appended. Input values required. This command allows names with spaces, including directories.
:flow_file_xmdf	<character>	Gives the name of the XMDF format flow file. This is a single file in h5 format.
:flow_file_dst	<character>	Gives name of the density/salinity/temperature file, e.g.: flow_file_dst A1.45 This is only used for some ADCIRC-3D model input. If IDEN=0, then no file is required.
:bc_file	<character>	Gives the name of the boundary condition file. Format depends on model type.
:xmdf_wse_path	<character>	Gives the internal data structure path in the XMDF format flow file. The default is 'Datasets/Water Surface Elevation (63)'
:xmdf_vel_path	<character>	Gives the internal data structure path in the XMDF format flow file. The default is 'Datasets/Velocity (64)'
:xmdf_u_path	<character>	Gives the internal data structure path for the U velocity component in the XMDF format flow file (M3D uses three scalars for the three components of velocity). The default is 'Datasets/U'
:xmdf_v_path	<character>	Gives the internal data structure path for the V velocity component in the XMDF format flow file (M3D uses three scalars for the three components of velocity). The default is 'Datasets/U'
:xmdf_w_path	<character>	Gives the internal data structure path for the W velocity component in the XMDF format flow file (M3D uses three scalars for the three components of velocity). The default is 'Datasets/U'
:m2d_control_file	<character>	Gives the name of the M2D control file {*.m2c}. This is only used for M2D version 3.02 and requires the mesh format to be specified as ‘m2d’, rather than ‘cms-2d’
:xmdf_dep_path	<character>	Gives the internal data structure path for the depth in the XMDF format file (M3D only). The default is 'Datasets/Depth'
:xmdf_sal_path	<character>	Gives the internal data structure path for the salinity in the XMDF format file (M3D and CH3D). The default is 'Datasets/Salinity'
:xmdf_temp_path	<character>	Gives the internal data structure path for the temperature in the XMDF format file (M3D and CH3D). The default is 'Datasets/Temperature'
:xmdf_M3D_path	<character>	Gives the internal data structure path for the 3D data in the XMDF format file (M3D only). The default is blank.
:xmdf_d35_path	<character>	Gives the internal data structure path for the D35 values in the XMDF format sediment file. The default is blank.
:xmdf_d50_path	<character>	Gives the internal data structure path for the D50 values in the XMDF format sediment file. The default is blank.
:xmdf_d90_path	<character>	Gives the internal data structure path for the D90 values in the XMDF format sediment file. The default is blank.
:start_flow	yyyy mm dd hh mm ss	Time origin of the ADCIRC flow files, e.g.: start_flow 1999 12 3 22 30 0 Each output step of the ADCIRC .63 and .64 files has a timestamp in seconds that is relative to a UTC time selected when the ADCIRC model control file is established. Input values required.
:wave_format	STWAVE or WABED or XMDF	Gives the format of the wave file, e.g.: wave_format STWAVE Options are STWAVE, WABED or XMDF. Default value is STWAVE.
:wave_files	<integer>	Gives the number of STWAVE .wav files that are to be used in the present simulation, e.g.: wave_files 100 The list of file names should start on the line immediately after the :end_data statement. Input value required if waves are used.
:wave_file_xmdf	<character>	Gives the name of the XMDF input file with wave data, e.g.: wave_file_xmdf south_waves_example.h5 This is the main (parent) grid. Input value required.
:wave_file_2_xmdf	<character>	Gives the name of the XMDF input file with wave data, e.g.: wave_file_xmdf south_waves_example.h5 This is the nested (child) grid. Input value required.
:wave_frames	<integer>	Gives the number of output frames (steps) that appear in each STWAVE .wav file, e.g.: wave_frames 1 In general, STWAVE files will contain a single frame if produced using the SMS steering module and more than one frame if produced using a stand-alone version of STWAVE (e.g. steering module run -> 100 files with one frame each; stand-alone -> 1 file with 100 frames. Input value required if waves are used.
:wave_step	<real>	Gives the time (in seconds) between each output frame (step) in the STWAVE .wav file(s), e.g.: wave_step 7200. Input value required if waves are used.
:m2d_step	<real>	Gives the time (in seconds) between each output frame (step) in the XMDF-format M2D file, e.g.: m2d_step 3600. I believe that the new XMDF files have the time units specified, so this may now longer be required.
:wave_grid_angle	<real>	Gives the orientation angle (in degrees, clockwise from y-axis to N) of the STWAVE grid, e.g.: wave_grid_angle 20. Input value required if waves are used.
:wave_x_origin	<real>	x-ordinate of the STWAVE grid origin, e.g.: wave_x_origin 1226722.50 Input value required if waves are used.
:wave_y_origin	<real>	y-ordinate of the STWAVE grid origin, e.g.: wave_y_origin 39990.15 Input value required if waves are used.
:nested		Instructs the model that nested STWAVE grids are to be used. The list of file names should start on the line immediately after the list of parent STWAVE file names. The nested and parent STWAVE grids must have the same number of frames and the same times associated with each frame.
:wave_grid_angle_2	<real>	Gives the orientation angle (in degrees, clockwise from y-axis to N) of the nested STWAVE grid, e.g.: wave_grid_angle 20. Input value required if waves are used.
:wave_x_origin_2	<real>	x-ordinate of the nested STWAVE grid origin, e.g.: wave_x_origin 1226722.50 Input value required if waves are used.
:wave_y_origin_2	<real>	y-ordinate of the nested STWAVE grid origin, e.g.: wave_y_origin 39990.15 Input value required if waves are used.
:start_waves	yyyy mm dd hh mm ss	Time of the first STWAVE frame, e.g.: start_waves 2004 12 3 0 30 0 Input values required if waves are used.
:exceed_waves		Instructs model to hold waves steady, if simulation exceeds duration of wave input file
:source_file	<character>	Gives the name of the file containing the sediment source information, e.g.: source_file test_2.source Input value required.
:neighbor_file	<character>	Gives the name of the file containing the neighbor source information, e.g.: neighbor_file test.neighbor The model will generate a file if one is not supplied. Input value required.
:output_prefix	<character>	Gives the prefix of the files used for output, e.g.: output_prefix west_test_1 The model will append an extension depending on the nature of the output file. Input value required.
:undertow		The model computes wave undertow. Default is inactive. Needs to be made more general.
:trap_file	<character>	Gives the name of the trap file, e.g.: trap_file trap_A.dat See trap section for details. If this keyword command is not issued, then no trap is present. Default is no trap.
:xmdf_grid_path	<character>	Path to the main folder in an M2D h5 file. This is the folder with such data as the Origin, Bearing etc. The datasets folder is usually below this one.
:last_step_trap		Surveys all particles on the last time step and places them in a trap, whether they are moving or not.
:start_trap	yyyy mm dd hh mm ss	Time at which the trap, if specified, is operational, e.g.: start_trap 2004 12 4 16 0 50 Input values required if trap is used. Default start time is the start of the simulation.
:stop_trap	yyyy mm dd hh mm ss	Time at which the trap, if specified, ceases operation, e.g.: stop_trap 2004 12 4 19 20 0 Input values required if trap is used. Default stop time is the end of the simulation.
:sediment_format	ADCIRC or XMDF_PROPERTY or XMDF_DATASET or m2d	Gives the format of the native sediment file, e.g.: sediment_format ADCIRC Default value is ADCIRC.
:sediment_file	<character>	Gives the name of the file containing the grain sizes of the native sediments, e.g.: sediment_file sed-A2.grd
:start_run	yyyy mm dd hh mm ss	Start time of the simulation, e.g.: start_run 2004 11 4 16 0 0 Input value required.
:stop_run	yyyy mm dd hh mm ss	Stop time of the simulation, e.g.: stop_run 2004 11 14 13 30 0 Must specify either :duration or :stop_run.
:duration	<real>	The duration of the simulation in seconds. Must specify either :duration or :stop_time.
:grid_update	<integer>	The increment in steps between updating of the mobility, shears and bedforms of the Eulerian grid
:flow_update	<Integer>	The increment in steps between updating of the flows and elevations of the Eulerian grid
:ket	<real>	Diffusion scalar. Default value is 0.25.
:temperature	<real>	The water temperature in °C. The default value is 15°C.
:salinity	<real>	The water salinity in ‰. The default value is 34 ‰.
:output_inc	<integer>	The increment in number of steps between output of the Lagrangian parcel data. The default value is 10.
:mapping_inc	<integer>	The increment in number of steps between output of the Eulerian grid data. The default value is 1000.
:min_depth	<real>	The minimum computation depth in m. The default value is 0.01 m.
:debug		Tells the model to turn off certain random generators routines and output stage times
:ensim_parcels		The model outputs a file with particle data in EnSim format (.pcl)
:ensim_maps		The model outputs a file with map data in EnSim format (.t3s)
:tecplot_parcels		The model outputs a file with particle data in Tecplot format (.plt)
:tecplot_maps		The model outputs a file with map data in Tecplot format (.plt)
:no_xmdf_parcels		The model will not output a parcel data file in XMDF format (.h5)
:no_xmdf_maps		The model will not output a map data file in XMDF format (.h5)
:population_record		A file with population history (e.g. particles born, trapped, deposited, etc.) is output as in Tecplot format as *_population.plt
:tau_cr_output		Instructs the model to output the critical shear for the initiation of motion of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:fall_velocity_output		Instructs the model to output the fall velocity of each parcel. Frequency of output is given by ‘output_inc’. Default is inactive.
:xmdf_compressed		Instructs the model to use compressed XMDF files. Default is inactive.
:no_hiding_exposure		Turns off hiding and exposure routines. Default is active.
:no_turbulent_shear		Turns off probabilistic shear calculations. Default is active.
:no_bed_interaction		Turns off bed interaction routines. Default is active.
:no_wave_mass_transport		Turns off wave mass transport calculations. Default is active.
:wave_mass_transport		Turns on wave mass transport calculations. Default is inactive.
:residence_calc		Model performs residency calculations (requires a polygon trap to be active)
:neutrally_buoyant		Model assumes all particles are neutrally buoyant (i.e. particle density set to that of the fluid and fall velocity is set to 0.). Default is inactive.
:bottom_flow_format	ADCIRC or XMDF	Gives the format of the bottom currents file. Options are ‘Default is ‘adcirc’.
:xmdf_bot_path	<character>	Gives the internal data structure path in the XMDF format flow file. The default is 'Datasets/Velocity (64)'
:bottom_flow_file	<character>	Gives the name of the bottom currents file.
:bottom_flow_height	<real>	Sets the height of the input bottom currents.
:bottom_mask_file	<character>	Gives the locations of the nodes where bottom currents are provided (1) and not provided (0)
:bottom_start_flow	yyyy mm dd hh mm ss	Time origin of the bottom flow files, e.g.: bottom_start_flow 1997 10 5 12 45 0 Each output step of the bottom flow file has a timestamp in seconds that is relative to a UTC time selected when the ADCIRC model control file is established. Input values required.
:wave_breaking		Instructs model to open a *.brk file for each *.wav file opened and to use breaking indices (Bi) estimate increased surf zone mixing.
:kew	<real>	Sets diffusion coefficient for waves. Default is 5. The horizontal eddy viscosity is adjusted by the factor:
:kev	<real>	Sets vertical diffusion coefficient. Default is 0.00859.
:etmin	<real>	Sets minimum vertical eddy viscosity. Default is 0.02.
:evmin	<real>	Sets minimum vertical eddy viscosity. Default is 0.0.
:source_to_datum		Sets the z-value of parcels released by sources to a z-value relative to datum rather than the bed
:numerical_scheme	<Integer>	Controls the order of the numerical scheme. Only valid options are 2 or 4.
:rhos	<real>	Sets the density of the bed sediments. Default is 2650.
:emrl_particle_set_guid	<character>	Used by SMS. Model will pass string to output files.
:emrl*		Model will ignore lines with these first four characters, except :emrl_particle_set_guid.
:end_data		Indicates the end of the keyword part of the file. The only contents of the file beyond this point should be the names of the wave files (if required).

Related Topics

• Particle Module
• Particle Tracking Model (PTM)
• Sediment File
• Source File
• Trap File