1# Runtime Options 2 3## Common Options 4HONEE is controlled via command-line options. 5The following options are common among all problem types: 6 7:::{list-table} Common Runtime Options 8:header-rows: 1 9 10* - Option 11 - Description 12 - Default value 13 14* - `-ceed` 15 - CEED resource specifier 16 - `/cpu/self/opt/blocked` 17 18* - `-problem` 19 - Problem to solve (`advection`, `density_current`, `euler_vortex`, `shocktube`, `blasius`, `channel`, `gaussian_wave`, and `taylor_green`) 20 - `density_current` 21 22* - `-implicit` 23 - Use implicit time integrator formulation 24 - 25 26* - `-degree` 27 - Polynomial degree of tensor product basis (must be >= 1) 28 - `1` 29 30* - `-q_extra` 31 - Number of extra quadrature points 32 - `0` 33 34* - `-ts_monitor_wall_force` 35 - Viewer for the force on each no-slip wall, e.g., `ascii:force.csv:ascii_csv` to write a CSV file. 36 - 37 38* - `-ts_monitor_total_kinetic_energy` 39 - Viewer for the total kinetic energy in the domain and other terms, e.g., `ascii:total_ke.csv:ascii_csv` to write a CSV file. 40 - 41 42* - `-ts_monitor_total_kinetic_energy_interval` 43 - Number of timesteps between calculating and printing the total kinetic energy 44 - `1` 45 46* - `-ts_monitor_cfl` 47 - Viewer for the min/max CFL in the domain e.g., `ascii:cfl.csv:ascii_csv` to write a CSV file. 48 - 49 50* - `-ts_monitor_cfl_interval` 51 - Number of timesteps between calculating and printing the min/max CFL 52 - `1` 53 54* - `-honee_check_step_interval` 55 - Number of time steps between checking the solution for Nans. Negative interval indicates it will not run. 56 - `-1` 57 58* - `-honee_max_wall_time_duration` 59 - Wall clock duration of simulation before it should be stopped. Acceptable formats are `hh`, `hh:mm`, and `hh:mm:ss`. Simulation is stopped at `start_time + duration - buffer` 60 - `'0'` 61 62* - `-honee_max_wall_time_buffer` 63 - Approximate time required to exit simulation cleanly (write checkpoints, etc.) 64 - `'00:01'` 65 66* - `-honee_max_wall_time_interval` 67 - Number of time steps between checking whether simulation should stop based on `-honee_max_wall_time_duration` 68 - `1` 69 70* - `-mesh_transform` 71 - Transform the mesh, usually for an initial box mesh. 72 - `none` 73 74* - `-help` 75 - View comprehensive information about run-time options 76 - 77::: 78 79### File I/O Options 80 81:::{list-table} File I/O Options 82:header-rows: 1 83 84* - Option 85 - Description 86 - Default value 87 88* - `-dm_plex_filename` 89 - Filename of mesh file to load in 90 - 91 92* - `-ts_monitor_solution` 93 - PETSc output format, such as `cgns:output-%d.cgns` (requires PETSc `--download-cgns`) 94 - 95 96* - `-ts_monitor_solution_interval` 97 - Number of time steps between visualization output frames. 98 - `1` 99 100* - `-viewer_cgns_batch_size` 101 - Number of frames written per CGNS file if the CGNS file name includes a format specifier (`%d`). 102 - `20` 103 104* - `-checkpoint_interval` 105 - Number of steps between writing binary checkpoints. `0` has no output, `-1` outputs final state only 106 - `0` 107 108* - `-checkpoint_vtk` 109 - Checkpoints include VTK (`*.vtu`) files for visualization. Consider `-ts_monitor_solution`instead. 110 - `false` 111 112* - `-viz_refine` 113 - Use regular refinement for VTK visualization 114 - `0` 115 116* - `-output_dir` 117 - Output directory for binary checkpoints and VTK files (if enabled). 118 - `.` 119 120* - `-output_add_stepnum2bin` 121 - Whether to add step numbers to output binary files 122 - `false` 123 124* - `-continue_filename` 125 - Path to file from which to continue from. Either binary file or CGNS 126 - 127 128* - `-ts_eval_times` 129 - Sets intermediate time points to evaluate the solution at. See [PETSc documentation](https://petsc.org/main/manualpages/TS/TSSetEvaluationTimes/) for more details. 130 - 131 132* - `-ts_eval_solutions_view` 133 - PETSc output format for `-ts_eval_times` solutions to be written to 134 - 135 136::: 137 138Note that to use `-continue_filename` with CGNS files, the same file must be used with `-dm_plex_filename` and `-dm_plex_cgns_parallel`. 139 140### Testing Options 141 142:::{list-table} Testing Options 143:header-rows: 1 144 145* - Option 146 - Description 147 - Default value 148 149* - `-test_type` 150 - Run in test mode and specify whether solution (`solver`) or turbulent statistics (`turb_spanstats`) output should be verified 151 - `none` 152 153* - `-compare_final_state_atol` 154 - Test absolute tolerance 155 - `1E-11` 156 157* - `-compare_final_state_filename` 158 - Test filename 159 - 160 161* - `-newtonian_unit_tests` 162 - Run unit tests of Newtonian state variable transformation functions 163 - `false` 164 165* - `-riemann_solver_unit_tests` 166 - Run unit tests of Riemann problem solver and it's Jacobian 167 - `false` 168::: 169 170### Logging Options 171 172Some of these are PETSc options here as reference, while others are custom to HONEE. 173 174:::{list-table} Logging Options 175:header-rows: 1 176 177* - Option 178 - Description 179 - Default value 180 181* - `-ts_pre_view` 182 - View PETSc `TS` solver configuration before it begins it's solve 183 - 184 185* - `-mass_ksp_view_pre_ts_solve` 186 - View mass KSP once before `TSSolve()` is called 187 - 188 189* - `-ts_monitor` 190 - View log for every timestep taken by the `TS` solver 191 - 192 193* - `-snes_monitor` 194 - View log for every iteration taken by the `SNES` solver 195 - 196 197* - `-snes_converged_reason` 198 - View convergence reason for every iteration taken by the `SNES` solver 199 - 200 201* - `-ksp_converged_reason` 202 - View convergence reason for every iteration taken by the `KSP` solver 203 - 204 205* - `-log_view` 206 - View PETSc performance log 207 - 208 209* - `-ksp_post_solve_residual` 210 - Print KSP residual summary information after each 211 - 212::: 213 214### Nondimensionalization 215These options allow the units used during solving to be changed. 216For problems where solution components can differ by many orders of magnitude, this can help problem conditioning 217 218:::{caution} 219This feature may be broken for certain use cases. If you discover a bug related to nondimensionalization, please submit a issue to the HONEE repo so that we can address it. 220::: 221 222:::{list-table} Nondimensionalization Options 223:header-rows: 1 224 225* - Option 226 - Description 227 - Default value 228 229* - `-units_meter` 230 - 1 meter in scaled length units 231 - `1` 232 233* - `-units_second` 234 - 1 second in scaled time units 235 - `1` 236 237* - `-units_kilogram` 238 - 1 kilogram in scaled mass units 239 - `1` 240 241* - `-units_Kelvin` 242 - 1 Kelvin in scaled temperature units 243 - `1` 244::: 245 246(bc-flags)= 247## Boundary conditions 248 249:::{list-table} Boundary Condition Options 250:header-rows: 1 251 252* - Option 253 - Description 254 255* - `-bc_wall` 256 - Use wall boundary conditions on this list of faces 257 258* - `-wall_comps` 259 - An array of constrained component numbers for wall BCs 260 261* - `-bc_slip` 262 - Use weak slip boundary condition on this list of faces 263 264* - `-bc_symmetry_x` 265 - Use symmetry boundary conditions, for the x component, on this list of faces 266 267* - `-bc_symmetry_y` 268 - Use symmetry boundary conditions, for the y component, on this list of faces 269 270* - `-bc_symmetry_z` 271 - Use symmetry boundary conditions, for the z component, on this list of faces 272 273* - `-bc_inflow` 274 - Use inflow boundary conditions on this list of faces 275 276* - `-bc_outflow` 277 - Use outflow boundary conditions on this list of faces 278 279* - `-bc_freestream` 280 - Use freestream boundary conditions on this list of faces 281::: 282 283For the case of a square/cubic mesh, the list of face indices to be used with `-bc_wall`, `bc_inflow`, `bc_outflow`, `bc_freestream` and/or `-bc_symmetry_x`, `-bc_symmetry_y`, and `-bc_symmetry_z` are: 284 285:::{list-table} 2D Face ID Labels 286:header-rows: 1 287* - PETSc Face Name 288 - Cartesian direction 289 - Face ID 290 291* - faceMarkerBottom 292 - -z 293 - 1 294 295* - faceMarkerRight 296 - +x 297 - 2 298 299* - faceMarkerTop 300 - +z 301 - 3 302 303* - faceMarkerLeft 304 - -x 305 - 4 306::: 307 308:::{list-table} 3D Face ID Labels 309:header-rows: 1 310* - PETSc Face Name 311 - Cartesian direction 312 - Face ID 313 314* - faceMarkerBottom 315 - -z 316 - 1 317 318* - faceMarkerTop 319 - +z 320 - 2 321 322* - faceMarkerFront 323 - -y 324 - 3 325 326* - faceMarkerBack 327 - +y 328 - 4 329 330* - faceMarkerRight 331 - +x 332 - 5 333 334* - faceMarkerLeft 335 - -x 336 - 6 337 338::: 339 340 341Boundary conditions for compressible viscous flows are notoriously tricky. 342Here we offer some recommendations. 343 344### Inflow 345 346If in a region where the flow velocity is known (e.g., away from viscous walls), use `bc_freestream`, which solves a Riemann problem and can handle inflow and outflow (simultaneously and dynamically). 347It is stable and the least reflective boundary condition for acoustics. 348 349If near a viscous wall, you may want a specified inflow profile. 350Use `bc_inflow` and see {ref}`example-blasius` and discussion of synthetic turbulence generation for ways to analytically generate developed inflow profiles. 351These conditions may be either weak or strong, with the latter specifying velocity and temperature as essential boundary conditions and evaluating a boundary integral for the mass flux. 352The strong approach gives sharper resolution of velocity structures. 353We have described the primitive variable formulation here; the conservative variants are similar, but not equivalent. 354 355### Outflow 356 357If you know the complete exterior state, `bc_freestream` is the least reflective boundary condition, but is disruptive to viscous flow structures. 358If thermal anomalies must exit the domain, the Riemann solver must resolve the contact wave to avoid reflections. 359The default Riemann solver, HLLC, is sufficient in this regard while the simpler HLL converts thermal structures exiting the domain into grid-scale reflecting acoustics. 360 361If acoustic reflections are not a concern and/or the flow is impacted by walls or interior structures that you wish to resolve to near the boundary, choose `bc_outflow`. This condition (with default `outflow_type: riemann`) is stable for both inflow and outflow, so can be used in areas that have recirculation and lateral boundaries in which the flow fluctuates. 362 363The simpler `bc_outflow` variant, `outflow_type: pressure`, requires that the flow be a strict outflow (or the problem becomes ill-posed and the solver will diverge). 364In our experience, `riemann` is slightly less reflective but produces similar flows in cases of strict outflow. 365The `pressure` variant is retained to facilitate comparison with other codes, such as PHASTA-C, but we recommend `riemann` for general use. 366 367### Periodicity 368 369PETSc provides two ways to specify periodicity: 370 3711. Topological periodicity, in which the donor and receiver dofs are the same, obtained using: 372 373```yaml 374dm_plex: 375 shape: box 376 box_faces: 10,12,4 377 box_bd: none,none,periodic 378``` 379 380The coordinates for such cases are stored as a new field with special cell-based indexing to enable wrapping through the boundary. 381This choice of coordinates prevents evaluating boundary integrals that cross the periodicity, such as for the outflow Riemann problem in the presence of spanwise periodicity. 382 3832. Isoperiodicity, in which the donor and receiver dofs are distinct in local vectors. This is obtained using `zbox`, as in: 384 385```yaml 386dm_plex: 387 shape: zbox 388 box_faces: 10,12,4 389 box_bd: none,none,periodic 390``` 391 392Isoperiodicity enables standard boundary integrals, and is recommended for general use. 393At the time of this writing, it only supports one direction of periodicity. 394The `zbox` method uses [Z-ordering](https://en.wikipedia.org/wiki/Z-order_curve) to construct the mesh in parallel and provide an adequate initial partition, which makes it higher performance and avoids needing a partitioning package. 395 396## Newtonian viscosity, Ideal Gas 397 398For the Density Current, Channel, and Blasius problems, the following common command-line options are available: 399 400:::{list-table} Newtonian Ideal Gas problems Runtime Options 401:header-rows: 1 402 403* - Option 404 - Description 405 - Default value 406 - Unit 407 408* - `-stab` 409 - Stabilization method (`none`, `su`, or `supg`) 410 - `none` 411 - 412 413* - `-Ctau_t` 414 - Stabilization time constant, $C_t$ 415 - `1.0` 416 - 417 418* - `-Ctau_v` 419 - Stabilization viscous constant, $C_v$ 420 - `36, 60, 128 for degree = 1, 2, 3` 421 - 422 423* - `-Ctau_C` 424 - Stabilization continuity constant, $C_c$ 425 - `1.0` 426 - 427 428* - `-Ctau_M` 429 - Stabilization momentum constant, $C_m$ 430 - `1.0` 431 - 432 433* - `-Ctau_E` 434 - Stabilization energy constant, $C_E$ 435 - `1.0` 436 - 437 438* - `-div_diff_flux_projection_method` 439 - Method used to calculate divergence of diffusive flux projection (`none`, `direct`, or `indirect`) 440 - `none` 441 - 442 443* - `-div_diff_flux_projection_ksp*` 444 - Control the KSP object for the projection of the divergence of diffusive flux 445 - N/A 446 - 447 448* - `-cv` 449 - Heat capacity at constant volume 450 - `717` 451 - `J/(kg K)` 452 453* - `-cp` 454 - Heat capacity at constant pressure 455 - `1004` 456 - `J/(kg K)` 457 458* - `-gravity` 459 - Gravitational acceleration vector 460 - `0,0,0` 461 - `m/s^2` 462 463* - `-lambda` 464 - Stokes hypothesis second viscosity coefficient 465 - `-2/3` 466 - 467 468* - `-mu` 469 - Shear dynamic viscosity coefficient 470 - `1.8e-5` 471 - `Pa s` 472 473* - `-k` 474 - Thermal conductivity 475 - `0.02638` 476 - `W/(m K)` 477 478* - `-state_var` 479 - State variables to solve solution with. `conservative` ($\rho, \rho \bm{u}, \rho e$), `primitive` ($P, \bm{u}, T$), or `entropy` ($\frac{\gamma - s}{\gamma - 1} - \frac{\rho}{P} (e - c_v T),\ \frac{\rho}{P} \bm{u},\ -\frac{\rho}{P}$) where $s = \ln(P\rho^{-\gamma})$ 480 - `conservative` 481 - string 482::: 483