User Instructions for Paranetric Wave Solver By: Samuel C. Boyd, and Robert J. Weaver Date: 6/15/2020 Institution: Florida Institute of Technology Department: Ocean Engineering and Marine Sciences Refrence: ECSS paper and thesis titled 'Improving Efficiency of Coupled Hydrodynamic Predictions by Implimenting a Fetch-based Parametric Wave Model' ***************************************************************************************************************** The pre-processing part of the solver is titled "pre_proc.cpp" Function: This code calculates fetch distances and depth values for all nodes in a given domain. The user inputs a distance value for the stepping process (should be on the same order as the smallest element in the domain). The code then calculates fetch distances along striaght-line fetch rays at angular headings with spacing defined by the user. Once all fetches are calculated, the cosine weighted effective fetch is computed according to the user's angular averaging distance considered. Inverse distance weighted depths are also calculated along straight-line fetch rays according to the IDW p-value specified by the user (5.0 was used for the IRL domain). Bottom slope is computed from a wet node to 1 step upwind of that node at each angular heading. The final output is 3 files (IDW_depths_2_deg.txt, Eff_fetch_2_deg.txt, Slope_upwind_2_deg.txt) that are later read in by the operational part of the solver Steps: 1) Code requires a grid file in the same directory as the code. The grid file needs to be in ADCIRC fort.14 format and named 'fort.14' OR the infile.open("fort.14"); line needs to be renamed according to the grid's file name. The following files on lines 74-80: "Distance_data_2_deg.txt" "Depth_data_2_deg.txt" "Slope_upwind_2_deg.txt" "p_values_2_deg.txt" "IDW_depths_2_deg.txt" "Eff_fetch_2_deg.txt" "Raw_depth_2_deg.txt" define the names of the files that the code will generate upon execution. The file contents, formats, and variables are defined in the Appendix section (bottom of this file). 2) Code requires an increase in stack size to allow for local array declarations. The command is: $ ulimit -s 1000000 The exact stack size required may depend on the domain and is also limited by the machine. Try the largest ulimit the machine will allow and see if a segmentation fault (core dump) still occurs. This size works for the IRL domain which has 126772 nodes. Future code improvement would be to reformat the variable arrays so that they are dynamically allocated and a large stack size is not required. 3) Code needs to be complied in the terminal with $ g++ pre_proc.cpp -o pre_proc before execution. 4) It is executed with command $ ./pre_proc and node numbers will be outputted on the terminal as the stepping process is running. This code takes 3.7 days to run for the IRL domain with 126772 nodes, 2 degree angular resolution, 40 degree cosine weighted average value, 50m bathymetric resolution step size, and constant IDW p-value of 5.0. ***************************************************************************************************************** The operational part of the parametric solver is titled "param_wave.cpp" Function: This code computes wave heights based on 4 different parametric formulations (SMB, SPM, TMA, and CEM) in addition to the ensemble average. The wave heights are calculated from the fetch and depth data created by the pre-processing part of the code, and are then modified according to the physical processes of friction, shoaling, and breaking. The results are files containing the final wave heights in ADCIRC fort.63 format. Steps: 1) This code reads in the pre-processed data for fetch, depth, and bottom slope created by the pre-processing part of the solver titled "pre_proc.cpp". These files are titled: "Eff_fetch_2_deg.txt" line: 189 and 246 "IDW_depths_2_deg.txt" line: 276 "Slope_upwind_2_deg.txt" line: 368 and must be placed in the same directory as the operational "param_wave.cpp" code. In addition, these files must be refrenced by their names properly on the lines on which they are called (shown above). 2) A wind file is required to force the solver and it must be in ADCIRC fort.22 (NWS=5) format and must be placed in the same directory as "param_wave.cpp" There is a code provided which can create 3 different wind fields. The wind field options are: 1) constant wind speed constant direction (input #0) 2) variable wind speed constant direction (input #2) 3) variable wind speed variable direction (input #1) The wind field type as well as simulation length will be entered in the terminal window upon wind code execution. The code is called "wind_gen2.cpp" and needs to be compiled and executed as mentioned above. SWAN is in Meteorlogical Convention while ADCIRC and PARAM are in Oceanographic convention. The wind code will format the fort.22 file accordingly. Currently all wind fields are with wind from the North (for theta wind #1 the wind starts from the north and rotates clockwise according to the angular resolution specified). The wind field is called at lines 324 and 440 and the file name needs to match this name. Code linearly interpolates wave heights if the wind direction provided falls in between the angular resolution specified. The results for each of the 4 parametric formulations, as well as the ensemble average between all 4 models are written to the files: "WEMO_Hcum_const_wind.63" line 407 "TMA_Hcum_const_wind.63" line 413 "CEM_Hcum_const_wind.63" line 419 "SPM_Hcum_const_wind.63" line 425 "ENS_Hcum_const_wind.63" line 431 in ADCIRC fort.63 file format. The results may be visualized in SMS. For reproducability of the results the wind files that were generated for the results of the study are also provided. These are labeled "PARAM_const_U_30.22" "PARAM_sin_U_30.22" and "PARAM_theta_U_30.22" and similarly "SWAN_const_U_30.22" "SWAN_sin_U_30.22" and "SWAN_theta_U_30.22" ***************************************************************************************************************** In the case that the user wants to change the inverse distance weighting function's p-value or effective fetch cosine angular value without re-running the pre-processing part of the code, "avg_modify.cpp" may be executed and parameters may be changed. Steps: 1) fort.14 grid file must be in the same directory as the code executable in order to read total number of nodes. 2) The files generated by the pre-processing code: "Distance_data_2_deg.txt" and "Depth_data_2_deg.txt" need to be in the same directory also. 3) The new files generated upon completion are called "IDW_depth_MOD.txt" "Eff_fetch_MOD.txt" and "Slope_upwind_MOD.txt". These modified names need to be adjusted within the "param_wave.cpp" before it can read these files OR rename the files to their original names and move them to the "param_wave.cpp" drirectory before execution. ***************************************************************************************************************** For comparing the wave height results of param_wave.cpp to the wave heights generated by SWAN for the same wind forcing, the code 'DS_v7.cpp' is provided. This code needs to be compiled and executed as mentioned above. Steps: 1) This code requires the SWAN wave height file (generated by the table output requested in the SWAN INPUT file) in the same directory as the executable. The SWAN INPUT file that was used to generate the results is also provided for reference. This file will be converted to fort.63 file format upon code execution. The raw SWAN file need to be accurately named on line 60 of DS_v7.cpp. The fort.63 file that will be created is named on line 63. This file is called again on line 122, so ensure that the names match within the code. 2) The code also requires the parametric wave height solution (fort.63 file generated by param_wave.cpp) in the same directory as the executable this is called on line 119. Note: only 1 wave height solution (SMB,SPM,TMA,CEM, or ENS) may be compared to SWAN per code execution. The parametric files need to be renamed within the code to the appropriate name of the model solution of interest to be compared to SWAN (rename file on line 119 for comparison). 3) The results of the solution comparison can be seen for every timestep, as well as the total simulation statistics, in the results.txt file named on line 124. These results are also formatted in an XLS, or .csv file format in the file named on line 126. ***************************************************************************************************************** ***Appendix*** Variable Definitions: N_tot: total number of nodes in the computational domain (fort.14 file) Ang_res: user-specified angular resolution of the stepping process (in degrees) Num_angs: total number of angular increments (360/Ang_res) or toal number of fetch rays per node num_steps: number of steps taken from wet node to d_num_steps (varies per node and per direction) step_res: user-specified step distance [m] d_num_steps: depth value along staight-line fetch ray right before land is reached U_inp: the user-specified expected maximum wind speed associated with the operational part of the solver n1,n2,n3... : node numbers F1,F2,F3... : fetch values [m] d1,d2,d3... : depth values [m] along fetch rays dir_1,dir_2,dir_3: direction number (1 to Ang_res) per node d_IDW1,d_IDW2,d_IDW3: inverse distance weighted depth according to p-value function File Formats: "Distance_data_2_deg.txt" Fetch Distances at spatial res: Step_res[m] and angular res: Ang_res[deg] Grid used to generate file: 'fort.14' n1 F1 F2 F3 ... F(Num_Angs) n2 n3 . . . N_tot F1 F2 F3 ... F(Num_Angs) notes: if a node is dry then the fetches will not be written. This file represents the raw fetch rays generated by the stepping process that will be read in by pre_proc.cpp at line (1462) which will then be cosine averaged according to the users Eff_res value. "Depth_data_2_deg.txt" Water Depths along fetch rays from 'fort.14' N_tot Ang_res n1 dir_1 num_steps d1 d2 d3 ... d_num_steps n1 dir_2 num_steps d1 d2 d3 ... d_num_steps . . . n2 dir_1 num_steps d1 d2 d3 ... d_num_steps n2 dir_2 num_steps d1 d2 d3 . . . d_num_steps (repeat process for all nodes) notes: this file contains the interpolated depth values along a straight-line fetch ray that are calculated at every step untill land is reached. d_num_steps represents the last depth recorded before land is reached. This file will be read in by the code at line (1529) where the values will then be inverse-distnace averaged according to the p-value specified by the user. "Slope_upwind_2_deg.txt" n1 m1 m2 m3 ... m(Num_Angs) n2 n3 . . . N_tot m1 m2 m3 ... m(Num_Angs) notes: This file represents the bottom slope between the depth at the wet node and the depth 1 step upwind (step according to step_res) at every angular heading (Num_Angs) "Eff_fetch_2_deg.txt" (N_tot) (Ang_res) n1 F1 F2 F3 ... F(360/Angres) n2 F1 F2 F3 ... F(360/Angres) . . . N_tot F1 F2 F3 ... F(360/Angres) notes: this file contains the cosine weighted fetch values that are averaged from the "Depth_data_2_deg.txt" file based on the user-specified p-value. "IDW_depths_2_deg.txt" (N_tot) (Ang_res) n1 d_IDW1 d_IDW2 d_IDW3 ... F(360/Angres) n2 d_IDW1 d_IDW2 d_IDW3 ... F(360/Angres) . . . N_tot d_IDW1 d_IDW1 d_IDW1 ... F(360/Angres) notes: this file contains the cosine weighted fetch values that are averaged from the "Depth_data_2_deg.txt" file based on the user-specified p-value.