Input Configuration Reference

Input Configuration Reference

This guide details all physical, computational, and boundary settings configured within the input namelist file (case.nml).

1. Grid Configuration (&mesh_input)

mesh_dir

  • Definition: Absolute or relative path to the directory containing native hexahedral grid definition files (points.dat, cells.dat, faces.dat, patches.dat, and optional periodic.dat).
  • When to Use: Always required.
  • How to Use: fortran mesh_dir = "cases/counterflow_nonreacting_gmsh/mesh_native"

2. Time Integration Controls (&time_input)

nsteps

  • Definition: Total number of physical timesteps to march.
  • When to Use: Always required. Set to 0 for static validation or initial grid checks.
  • How to Use: fortran nsteps = 5000

dt

  • Definition: Initial or constant timestep size (seconds).
  • When to Use: Choose based on grid spacing and expected velocity to keep CFL below stability limits ().
  • How to Use: fortran dt = 1.0e-4

output_interval

  • Definition: Frequency (in timesteps) of unstructured VTK/PVTU visualization output file writing.
  • When to Use: Set high for production runs to save disk I/O, or low for active debugging.
  • How to Use: fortran output_interval = 500

terminal_interval

  • Definition: Frequency (in timesteps) of rank-0 console status reporting.
  • When to Use: Set to 1 to monitor progress closely, or larger integers (e.g. 100) to keep console outputs clean.
  • How to Use: fortran terminal_interval = 10

terminal_detail

  • Definition: Level of terminal detail to report. Valid values: "brief", "health", or "full".
  • When to Use:
  • "brief": Minimizes console logging overhead.
  • "health": Reports CFL, Poisson CG iterations, and global conservation errors.
  • "full": Shows detailed cell indices and subcycling details.
  • How to Use: fortran terminal_detail = "health"

use_dynamic_dt

  • Definition: Master switch to enable dynamic, CFL-based timestep adjustment.
  • When to Use: Recommended for reacting setups to prevent solver crashes during heat release.
  • How to Use: fortran use_dynamic_dt = .true.

max_cfl

  • Definition: Target maximum convective Courant-Friedrichs-Lewy (CFL) number.
  • When to Use: Required if use_dynamic_dt = .true.. Standard finite-volume projection solvers require for stability.
  • How to Use: fortran max_cfl = 0.45

max_dt

  • Definition: Hard ceiling [s] for dynamic timesteps.
  • When to Use: Prevents dt from growing too large during slow, low-velocity phases.
  • How to Use: fortran max_dt = 1.0e-3

min_dt

  • Definition: Hard floor [s] for dynamic timesteps before cutting halts.
  • When to Use: Set to prevent infinite cuts during extreme numerical stiffness or physical instability.
  • How to Use: fortran min_dt = 1.0e-8

dt_growth_limit

  • Definition: Timestep growth ceiling limit per step.
  • When to Use: Keeps timestep size adjustments smooth and prevents rapid oscillations in timestep size.
  • How to Use: fortran dt_growth_limit = 1.02

enable_step_rejection

  • Definition: Master switch for rollback-based stability checks. Timestep is rejected and retried with a cut dt if any physical health test fails.
  • When to Use: Strongly recommended for reacting flow runs. It prevents code aborts by backing up and using a smaller timestep when transient stiff reactions occur.
  • How to Use: fortran enable_step_rejection = .true.

max_step_retries

  • Definition: Maximum consecutive rollback retry cuts allowed for a single step before calling a fatal error.
  • When to Use: Set higher (up to 10) for highly transient reacting ignitions where multiple cuts are expected.
  • How to Use: fortran max_step_retries = 8

step_reject_cut_factor

  • Definition: Multiplicative factor applied to the current dt after a step rejection. Must be in (0, 1).
  • When to Use: Standard values are 0.5 (halves dt) or 0.25 for faster reduction.
  • How to Use: fortran step_reject_cut_factor = 0.5

3. Fluid Physics & Backend Selectors (&fluid_input)

rho

  • Definition: Constant fluid density [kg/m^3] for constant-density runs, and startup/fallback density when variable-density is enabled.
  • When to Use: Physical density of your carrier fluid.
  • How to Use: fortran rho = 1.18

enable_variable_density

  • Definition: Master switch to enable variable-density projection coupling.
  • When to Use: Must be .true. for variable-density flows (including reacting flames and non-reacting mixing of streams with different densities).
  • How to Use: fortran enable_variable_density = .true.

enable_density_corrector_projection

  • Definition: Post-chemistry pressure Poisson projection solve to enforce divergence constraints after local density changes in variable density mode.
  • When to Use: Strongly recommended in reacting cases where intense local density fluctuations can occur post-chemistry. Executing this to .true. executes an additional pressure-only correction step to ensure the face fluxes strictly respect the divergence constraints.
  • How to Use: fortran enable_density_corrector_projection = .true.

density_eos

  • Definition: Selector for active flow density. Choices: "constant" (uses rho), "cantera" (density from Cantera YAML thermo state).
  • When to Use: Use "cantera" for all real and ideal gas mixtures coupled with chemical kinetics.
  • How to Use: fortran density_eos = "cantera"

nu

  • Definition: Kinematic viscosity [m^2/s] when variable viscosity is off.
  • When to Use: Use in constant-property aerodynamic runs to enforce a specific Reynolds number.
  • How to Use: fortran nu = 1.5e-5

enable_variable_nu

  • Definition: If .true., kinematic viscosity nu is dynamically updated using Cantera mixture-averaged dynamic viscosity and active cell density.
  • When to Use: Use in physical reacting runs where heat release changes the temperature (and therefore viscosity) significantly.
  • How to Use: fortran enable_variable_nu = .true.

enable_cantera

  • Definition: Enables Cantera-backed fluid transport path (specifically dynamic viscosity mu).
  • When to Use: Must be .true. if enable_variable_nu = .true. is active.
  • How to Use: fortran enable_cantera = .true.

cantera_mech_file

  • Definition: Path to the YAML chemical mechanism file.
  • When to Use: Required if Cantera thermo, reactions, or transport are active.
  • How to Use: fortran cantera_mech_file = "mechanisms/ideal_mixavg.yaml"

cantera_phase_name

  • Definition: Optional phase name within the Cantera mechanism file. Blank uses default/first phase.
  • When to Use: Use if your mechanism contains multiple phases (e.g. real gas models) and you need to select a specific one (e.g., "gas").
  • How to Use: fortran cantera_phase_name = "gas"

background_temp

  • Definition: Uniform temperature [K] used for property evaluations if enable_energy = .false..
  • When to Use: Use in isothermal species mixing runs where Cantera transport properties depend on temperature, but no energy equation is transported.
  • How to Use: fortran background_temp = 300.0

background_press

  • Definition: Uniform reference thermodynamic pressure [Pa] used by Cantera for state evaluations.
  • When to Use: Set to match the operating environment pressure (e.g. 101325.0 for 1 atm). Crucial for calculating chemical rates and gas densities correctly.
  • How to Use: fortran background_press = 101325.0

4. Solver Discretization Settings (&solver_input)

pressure_max_iter

  • Definition: Maximum iterations allowed for the pressure Poisson Conjugate Gradient solver.
  • When to Use: Increase (up to 2000) for high-aspect-ratio grids or highly transient variable-density cases where convergence requires more iterations.
  • How to Use: fortran pressure_max_iter = 1000

pressure_tol

  • Definition: Residual convergence tolerance for the CG solver.
  • When to Use: Set between 1.0e-8 and 1.0e-12. Smaller values ensure a divergence-free velocity field but increase iteration count.
  • How to Use: fortran pressure_tol = 1.0e-10

pressure_abs_tol

  • Definition: Absolute RMS residual convergence tolerance for the pressure Poisson CG solver (used alongside pressure_tol).
  • When to Use: Highly recommended to prevent the CG solver from stalling or performing unnecessary iterations when the relative residual target pressure_tol is excessively tight due to a very small initial residual.
  • How to Use: fortran pressure_abs_tol = 1.0e-8

body_force_x, body_force_y, body_force_z

  • Definition: Constant volumetric acceleration components [m/s^2] added as sources to the momentum equations.
  • When to Use: Set to non-zero values to represent gravity or driving body forces (e.g., in periodic channel flows).
  • How to Use: fortran body_force_x = 1.5

convection_scheme

  • Definition: Legacy/fallback advection reconstruction. Choices: "upwind", "central".
  • When to Use: Acts as the master default for fields that do not override their specific schemes.
  • How to Use: fortran convection_scheme = "upwind"

momentum_convection_scheme

  • Definition: Momentum-specific advection reconstruction. Blank falls back to convection_scheme. Choices: "upwind", "central".
  • When to Use: Use "central" for clean aerodynamic validation of laminar flows. Use "upwind" to stabilize high-shear region calculations.
  • How to Use: fortran momentum_convection_scheme = "central"

species_convection_scheme

  • Definition: Advection reconstruction for species mass fractions. Choices: "upwind", "central", "bounded_central", "bounded_linear", "muscl", "limited_linear", "quick".
  • When to Use: Use "quick" (or "muscl") for chemical species transport to achieve high spatial accuracy. QUICK uses a quadratic upstream interpolation scheme.
  • How to Use: fortran species_convection_scheme = "quick"

energy_convection_scheme

  • Definition: Advection reconstruction for sensible enthalpy. Choices: "upwind", "central", "bounded_central", "bounded_linear", "muscl", "limited_linear", "quick".
  • When to Use: Use "quick" (or "muscl") to prevent unphysical temperature spikes near flames while keeping thermal interfaces sharp.
  • How to Use: fortran energy_convection_scheme = "quick"

scalar_limiter

  • Definition: TVD slope/value limiter used for higher-order scalar reconstruction. Choices: "none", "minmod", "vanleer", "mc", "superbee", "barth_jespersen", "venkatakrishnan", "hlpa", "quick_limited".
  • When to Use: "hlpa" (Hybrid Linear/Parabolic Approximation) or "quick_limited" is highly recommended when using the "quick" convection scheme to enforce the Convective Boundedness Criterion (CBC) and keep mass fractions bounded within .
  • How to Use: fortran scalar_limiter = "hlpa"

5. Multi-Physics Boundary Parameters (&boundary_input)

n_patches

  • Definition: Number of boundary patches to map. Must match the boundaries defined in the grid.
  • When to Use: Required for every case.
  • How to Use: fortran n_patches = 4

patch_name

  • Definition: Name identifier matching the boundaries declared in patches.dat.
  • When to Use: Required for each patch.
  • How to Use: Provide as a comma-separated list of quoted strings: fortran patch_name = "inlet", "outlet", "walls", "symmetry"

patch_velocity_type

  • Definition: Boundary condition for velocity. Choices: "fixed_value", "zero_gradient", "symmetric", "wall", "convective".
  • When to Use:
  • "wall" or "no_slip": For physical solid walls ().
  • "fixed_value": For inflows with prescribed velocities.
  • "zero_gradient": For outflows.
  • How to Use: fortran patch_velocity_type = "fixed_value", "zero_gradient", "wall", "symmetric"

patch_pressure_type

  • Definition: Boundary condition for projection pressure. Choices: "fixed_value", "zero_gradient", "symmetric", "farfield_gradient".
  • When to Use: Outlet patches must have at least one patch set to "fixed_value" with patch_p = 0.0 to serve as a reference pressure anchor for the Poisson solver. Walls and inflows typically use "zero_gradient".
  • How to Use: fortran patch_pressure_type = "zero_gradient", "fixed_value", "zero_gradient", "symmetric"

patch_temperature_type

  • Definition: Boundary condition for enthalpy/temperature. Choices: "fixed_value", "zero_gradient", "symmetric".
  • When to Use: Use "fixed_value" to represent heated/cooled walls or prescribed inlet streams. Use "zero_gradient" for adiabatic walls.
  • How to Use: fortran patch_temperature_type = "fixed_value", "zero_gradient", "zero_gradient", "symmetric"

patch_species_type

  • Definition: Boundary condition for chemical species. Choices: "fixed_value", "zero_gradient", "symmetric".
  • When to Use: Use "fixed_value" for gas inlets to prescribe composition. Use "zero_gradient" for non-reacting walls.
  • How to Use: fortran patch_species_type = "fixed_value", "zero_gradient", "zero_gradient", "symmetric"

patch_u, patch_v, patch_w

  • Definition: Prescribed boundary velocity components [m/s].
  • When to Use: Required for patches where patch_velocity_type = "fixed_value".
  • How to Use: fortran patch_u(1) = 0.5 ! inlet velocity along x-direction

patch_mass_flux

  • Definition: Prescribed face mass flux [kg/m^2/s] (positive for inflow, negative for outflow).
  • When to Use: Use instead of velocity components when you want to enforce a strict mass flow rate under variable-density conditions.
  • How to Use: fortran patch_mass_flux(1) = 1.18 ! Enforces mass flux at inlet

patch_p

  • Definition: Prescribed boundary projection pressure value [Pa].
  • When to Use: Required for pressure Dirichlet anchor patches (typically outlets).
  • How to Use: fortran patch_p(2) = 0.0

patch_dpdn

  • Definition: Prescribed normal physical pressure gradient () [Pa/m] for pressure Neumann patches.
  • When to Use: Use to enforce gravity-driven hydrostatic pressure gradients () or centrifugal/accelerating pressures at open boundaries or walls.
  • How to Use: fortran patch_dpdn(1) = -11.5 ! Enforces a -11.5 Pa/m normal pressure gradient

patch_T

  • Definition: Prescribed boundary temperature [K].
  • When to Use: Required if patch_temperature_type = "fixed_value".
  • How to Use: fortran patch_T(1) = 400.0

patch_composition

  • Definition: Preferred named species mixture string for the boundary patch.
  • When to Use: Use to specify inlet compositions in multi-species runs cleanly. Mass fractions must sum to approximately 1.
  • How to Use: fortran patch_composition(1) = "CH4:0.05,O2:0.20,N2:0.75"

6. Energy & Thermodynamic Configurations (&energy_input)

enable_energy

  • Definition: Master switch to enable sensible-enthalpy () transport.
  • When to Use: Set to .true. for all non-isothermal configurations.
  • How to Use: fortran enable_energy = .true.

enable_cantera_thermo

  • Definition: If .true., use Cantera for HP thermodynamics updates (, , thermal conductivity , and ).
  • When to Use: Strongly recommended for multi-component reacting or real gas mixtures where CP and conductivity vary significantly with temperature and composition.
  • How to Use: fortran enable_cantera_thermo = .true.

enable_species_enthalpy_diffusion

  • Definition: Include species-enthalpy diffusion correction () in the energy equation.
  • When to Use: Physically required in multi-component reacting flows where species with widely different enthalpies diffuse (e.g. hydrogen-oxygen flames).
  • How to Use: Requires species transport and Cantera thermo to be active. fortran enable_species_enthalpy_diffusion = .true.

7. Restart Controls (&restart_input)

restart_from_file

  • Definition: Ingest initial fields from the restart file.
  • When to Use: Set to .true. to resume a long production run or initiate a perturbation study from a converged state.
  • How to Use: fortran restart_from_file = .true.

restart_file

  • Definition: Binary restart file path.
  • When to Use: Required if restart_from_file = .true..
  • How to Use: fortran restart_file = "restart/restart_step_010000.bin"

write_restart

  • Definition: Periodically write binary restart dumps.
  • When to Use: Strongly recommended for long production runs to preserve simulation state against system crashes.
  • How to Use: fortran write_restart = .true.

restart_interval

  • Definition: Cadence in steps for writing restart files (must be > 0 if write_restart = .true.).
  • When to Use: Choose an interval representing a reasonable computational block (e.g. every 1000 or 5000 steps).
  • How to Use: fortran restart_interval = 2000