SMS:PTM 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.:
|
: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.:
|
: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.:
|
: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.:
|
: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.:
|
:mesh_format | ADCIRC | Gives the format of the mesh file, e.g.:
|
:mesh_file | <character> | Gives the name of the mesh file, e.g.:
|
:flow_format | ADCIRC
or CMS-2D or CMS-3D or CH3D |
Gives the format of the hydrodynamic files:
|
:flow_files | <character> <character> | Gives names of the hydrodynamic files, e.g.:
|
:flow_file_uv | <character> | Gives names of the hydrodynamic flow file, e.g.:
|
:flow_file_z | <character> | Gives names of the hydrodynamic elevation file, e.g.:
|
: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.:
|
: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.:
|
:wave_format | STWAVE
or WABED or XMDF |
Gives the format of the wave file, e.g.:
|
:wave_files | <integer> | Gives the number of STWAVE .wav files that are to be used in the present simulation, e.g.:
|
:wave_file_xmdf | <character> | Gives the name of the XMDF input file with wave data, e.g.:
|
:wave_file_2_xmdf | <character> | Gives the name of the XMDF input file with wave data, e.g.:
|
:wave_frames | <integer> | Gives the number of output frames (steps) that appear in each STWAVE .wav file, e.g.:
|
:wave_step | <real> | Gives the time (in seconds) between each output frame (step) in the STWAVE .wav file(s), e.g.:
|
:m2d_step | <real> | Gives the time (in seconds) between each output frame (step) in the XMDF-format M2D file, e.g.:
|
:wave_grid_angle | <real> | Gives the orientation angle (in degrees, clockwise from y-axis to N) of the STWAVE grid, e.g.:
|
:wave_x_origin | <real> | x-ordinate of the STWAVE grid origin, e.g.:
|
:wave_y_origin | <real> | y-ordinate of the STWAVE grid origin, e.g.:
|
: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_x_origin_2 | <real> | x-ordinate of the nested STWAVE grid origin, e.g.:
|
:wave_y_origin_2 | <real> | y-ordinate of the nested STWAVE grid origin, e.g.:
|
:start_waves | yyyy mm dd hh mm ss | Time of the first STWAVE frame, e.g.:
|
: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.:
|
:neighbor_file | <character> | Gives the name of the file containing the neighbor source information, e.g.:
|
:output_prefix | <character> | Gives the prefix of the files used for output, e.g.:
|
: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.:
|
: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.:
|
:stop_trap | yyyy mm dd hh mm ss | Time at which the trap, if specified, ceases operation, e.g.:
|
:sediment_format | ADCIRC
or XMDF_PROPERTY or XMDF_DATASET or m2d |
Gives the format of the native sediment file, e.g.:
|
:sediment_file | <character> | Gives the name of the file containing the grain sizes of the native sediments, e.g.:
|
:start_run | yyyy mm dd hh mm ss | Start time of the simulation, e.g.:
|
:stop_run | yyyy mm dd hh mm ss | Stop time of the simulation, e.g.:
|
: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.:
|
: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
SMS – Surface-water Modeling System | ||
---|---|---|
Modules: | 1D Grid • Cartesian Grid • Curvilinear Grid • GIS • Map • Mesh • Particle • Quadtree • Raster • Scatter • UGrid | |
General Models: | 3D Structure • FVCOM • Generic • PTM | |
Coastal Models: | ADCIRC • BOUSS-2D • CGWAVE • CMS-Flow • CMS-Wave • GenCade • STWAVE • WAM | |
Riverine/Estuarine Models: | AdH • HEC-RAS • HYDRO AS-2D • RMA2 • RMA4 • SRH-2D • TUFLOW • TUFLOW FV | |
Aquaveo • SMS Tutorials • SMS Workflows |