LCOV - code coverage report
Current view: top level - solvers/turbulence - turbulence_solver_internal.h (source / functions) Coverage Total Hit
Test: coverage.info Lines: 100.0 % 3 3
Test Date: 2026-10-05 04:47:18 Functions: - 0 0

            Line data    Source code
       1              : /**
       2              :  * @file turbulence_solver_internal.h
       3              :  * @brief Internal workspace-aware turbulence solver interface and model constants
       4              :  *
       5              :  * Not part of the public API. Used by the NS solvers to avoid per-step
       6              :  * allocation of scratch buffers. Each backend (scalar, OMP, AVX2) provides a
       7              :  * workspace-aware turbulence step with identical numerics; the matching NS
       8              :  * backend calls its own variant so optimized solvers never fall back to the
       9              :  * scalar turbulence step.
      10              :  */
      11              : 
      12              : #ifndef CFD_TURBULENCE_SOLVER_INTERNAL_H
      13              : #define CFD_TURBULENCE_SOLVER_INTERNAL_H
      14              : 
      15              : #include "cfd/core/cfd_status.h"
      16              : #include "cfd/core/grid.h"
      17              : #include "cfd/solvers/navier_stokes_solver.h"
      18              : 
      19              : #include <math.h>
      20              : #include <stddef.h>
      21              : 
      22              : /* --- Standard k-epsilon (Launder-Spalding) constants --- */
      23              : #define TURB_C_MU      0.09
      24              : #define TURB_C1_EPS    1.44
      25              : #define TURB_C2_EPS    1.92
      26              : #define TURB_SIGMA_K   1.0
      27              : #define TURB_SIGMA_EPS 1.3
      28              : 
      29              : /* --- Spalart-Allmaras (no-ft2 variant) constants --- */
      30              : #define SA_CB1   0.1355
      31              : #define SA_CB2   0.622
      32              : #define SA_SIGMA (2.0 / 3.0)
      33              : #define SA_KAPPA 0.41
      34              : #define SA_CW1   (SA_CB1 / (SA_KAPPA * SA_KAPPA) + (1.0 + SA_CB2) / SA_SIGMA)
      35              : #define SA_CW2   0.3
      36              : #define SA_CW3   2.0
      37              : #define SA_CV1   7.1
      38              : 
      39              : /* --- Wall-function constants (log law and Spalding's law) --- */
      40              : #define WALL_KAPPA 0.41
      41              : #define WALL_B     5.2
      42              : 
      43              : /* --- Positivity floors and realizability limits --- */
      44              : #define TURB_K_MIN             1e-10  /* floor for k */
      45              : #define TURB_EPS_MIN           1e-10  /* floor for epsilon */
      46              : #define TURB_PROD_LIMIT_FACTOR 10.0   /* P_k <= factor * eps */
      47              : #define TURB_NU_T_MAX_FACTOR   1e5    /* nu_t <= factor * nu */
      48              : 
      49              : /* Workspace requirement: 2*nx*ny*nz doubles (k-epsilon uses both halves,
      50              :  * Spalart-Allmaras uses the first half only). */
      51              : #define TURB_WORKSPACE_SIZE(total) (2 * (total))
      52              : 
      53              : /**
      54              :  * Workspace-aware turbulence step (scalar CPU).
      55              :  *
      56              :  * When workspace is non-NULL and workspace_size >= 2*nx*ny*nz, uses it as
      57              :  * scratch instead of allocating. Caller owns the buffer lifetime.
      58              :  * When workspace is NULL, allocates internally (same as public API).
      59              :  */
      60              : cfd_status_t turbulence_step_explicit_with_workspace(
      61              :     flow_field* field, const grid* grid,
      62              :     const ns_solver_params_t* params,
      63              :     double dt, double time,
      64              :     double* workspace, size_t workspace_size);
      65              : 
      66              : /** OpenMP-parallelized turbulence step (cfd_omp). Same numerics as the scalar
      67              :  *  variant; the interior stencil loop is parallelized over j. */
      68              : cfd_status_t turbulence_step_explicit_omp_with_workspace(
      69              :     flow_field* field, const grid* grid,
      70              :     const ns_solver_params_t* params,
      71              :     double dt, double time,
      72              :     double* workspace, size_t workspace_size);
      73              : 
      74              : /** AVX2-vectorized turbulence step (cfd_simd). Same numerics as the scalar
      75              :  *  variant; the interior stencil is vectorized along i with a scalar tail. */
      76              : cfd_status_t turbulence_step_explicit_avx2_with_workspace(
      77              :     flow_field* field, const grid* grid,
      78              :     const ns_solver_params_t* params,
      79              :     double dt, double time,
      80              :     double* workspace, size_t workspace_size);
      81              : 
      82              : /** Scalar k-epsilon transport kernel: writes updated k/eps into k_new/eps_new
      83              :  *  (interior points only; boundary values are carried over by the caller). */
      84              : void turb_kepsilon_step_scalar(const flow_field* field, const grid* grid,
      85              :                                const ns_solver_params_t* params, double dt,
      86              :                                double* k_new, double* eps_new);
      87              : 
      88              : /** Scalar Spalart-Allmaras transport kernel: writes updated nu_tilde into
      89              :  *  nt_new (interior points only). */
      90              : void turb_sa_step_scalar(const flow_field* field, const grid* grid,
      91              :                          const ns_solver_params_t* params, double dt,
      92              :                          double* nt_new);
      93              : 
      94              : /**
      95              :  * Minimum wall distance for point (i,j): distance to the nearest face marked
      96              :  * BC_TYPE_NOSLIP (wall-function wall) in tbc. Sets *has_wall to 0 and returns
      97              :  * 0.0 when no face is a wall (SA destruction term must then be disabled).
      98              :  */
      99              : double turb_wall_distance(const grid* grid, const ns_turbulence_bc_config_t* tbc,
     100              :                           size_t i, size_t j, int* has_wall);
     101              : 
     102              : /** Recompute nu_t from the active model fields with realizability clipping
     103              :  *  (nu_t <= TURB_NU_T_MAX_FACTOR * nu). Used after transport and by BCs. */
     104              : void turb_update_nu_t(flow_field* field, const ns_solver_params_t* params);
     105              : 
     106              : /* --- Optional eddy-viscosity corrections (algebraic or learned) --- */
     107              : 
     108              : /** Features per cell: ln S*, ln Re_t, ln(nu_t/nu). The model's input width must
     109              :  *  equal this exactly; a model of any other shape is rejected at solver init. */
     110              : #define TURB_CLOSURE_FEATURES 3
     111              : /** The model predicts one multiplier per cell. */
     112              : #define TURB_CLOSURE_OUTPUTS 1
     113              : /** Bounds on the predicted multiplier. Both directions matter: the correction
     114              :  *  the channel DNS asks for is below 1 (k-epsilon over-predicts turbulent
     115              :  *  energy in the outer layer), so this is NOT a dissipation-only correction and
     116              :  *  the floor is what keeps a reduced nu_t away from zero. */
     117              : #define TURB_CLOSURE_BETA_MIN 0.1
     118              : #define TURB_CLOSURE_BETA_MAX 10.0
     119              : /** Cells per inference call. The correction walks the grid in tiles so it needs
     120              :  *  no per-step allocation and no context sized to the grid; a smaller context
     121              :  *  just means smaller tiles. */
     122              : #define TURB_CLOSURE_TILE 256
     123              : 
     124              : /* --- Algebraic correction: beta = A * (S*)^B, i.e. a strain-dependent C_mu ---
     125              :  *
     126              :  * Fitted by least squares on ln(k_dns / k_model) against ln S* at Re_tau =
     127              :  * 392.24 (9 comparison nodes), then evaluated at the held-out Re_tau = 587.19.
     128              :  * The target is the TKE ratio rather than the shear-stress ratio because in
     129              :  * fully developed channel flow the total shear stress is fixed by the mean
     130              :  * momentum balance, so -uv+ is nearly closure-independent and its apparent
     131              :  * error is dominated by discretisation. k is a genuine closure output.
     132              :  *
     133              :  * THE SIGN IS NOT THE INTUITIVE ONE, and the first version of these constants
     134              :  * had it backwards. Multiplying nu_t by beta is the same as using
     135              :  * C_mu' = beta * C_mu. In a stress-constrained flow the shear stress is set by
     136              :  * the mean momentum balance, not by the closure, so the strain rate absorbs any
     137              :  * change in nu_t: tau = nu_t |S| is fixed, P_k = tau^2 / nu_t, and local
     138              :  * equilibrium (P_k = eps) with nu_t = C_mu' k^2/eps gives
     139              :  *
     140              :  *     k = tau / sqrt(C_mu')  =>  k scales as beta^(-1/2).
     141              :  *
     142              :  * LOWERING nu_t therefore RAISES k. Measured: beta = 0.90 predicts +5.4% in k
     143              :  * and the run gave +6.0%. So to scale k by a factor r the multiplier must be
     144              :  * beta = r^(-2), which is how the fitted TKE ratio is converted below.
     145              :  *
     146              :  * Provenance, the failed first attempt and the a posteriori numbers are in
     147              :  * docs/technical-notes/ml-integration-design.md 2.7. These are fitted
     148              :  * constants, not derived ones -- treat them as a measured baseline for a
     149              :  * learned closure to beat, not as physics. */
     150              : #define TURB_ALG_BETA_A 1.6945
     151              : #define TURB_ALG_BETA_B (-0.2778)
     152              : 
     153              : /**
     154              :  * Apply whichever optional eddy-viscosity correction params selects: the
     155              :  * algebraic strain-rate power law, or the learned closure.
     156              :  *
     157              :  * Call immediately after turb_update_nu_t(). Returns CFD_SUCCESS and touches
     158              :  * nothing when neither is configured, so the un-corrected path stays
     159              :  * bit-identical. Additive by design: turb_update_nu_t keeps its signature and
     160              :  * its behaviour.
     161              :  *
     162              :  * @return CFD_SUCCESS; CFD_ERROR_UNSUPPORTED if a correction is configured with
     163              :  *         any model other than k-epsilon (S*, Re_t and nu_t/nu are built from k
     164              :  *         and epsilon, so they do not exist for Spalart-Allmaras), or if both
     165              :  *         corrections are configured at once; CFD_ERROR_INVALID for an unknown
     166              :  *         correction value, a NULL field/grid, a missing turbulence field or a
     167              :  *         model of the wrong shape; CFD_ERROR_DIVERGED if the model predicts a
     168              :  *         non-finite value. Never a silent skip: a caller that asked for a
     169              :  *         correction gets one or an error.
     170              :  */
     171              : cfd_status_t turb_apply_nu_t_correction(flow_field* field, const grid* grid,
     172              :                                         const ns_solver_params_t* params);
     173              : 
     174              : /**
     175              :  * Validate params->turb_closure and params->turb_nut_correction against
     176              :  * params->turb_model at solver init.
     177              :  *
     178              :  * Checked here rather than per step so a caller learns before init returns,
     179              :  * while they can still choose a different configuration.
     180              :  *
     181              :  * @return CFD_SUCCESS when no correction is set or the configuration is usable;
     182              :  *         CFD_ERROR_UNSUPPORTED when a correction is set without k-epsilon, or
     183              :  *         when both corrections are set at once;
     184              :  *         CFD_ERROR_INVALID for a value no enum defines, or when the model's
     185              :  *         input or output width does not match what the closure feeds it.
     186              :  */
     187              : cfd_status_t turb_check_closure_config(const ns_solver_params_t* params);
     188              : 
     189              : /**
     190              :  * Whether a segment carries the checkpoint's "profile not stored" marker: a
     191              :  * DIRICHLET segment with no profile whose k, eps and nu_tilde are all NaN, the
     192              :  * values cfd_checkpoint_write() stores in place of a profile's. Such a segment
     193              :  * becomes usable again once its profile is re-attached.
     194              :  */
     195          116 : static inline int turb_segment_profile_detached(const ns_turbulence_bc_segment_t* seg) {
     196           82 :     return seg->type == BC_TYPE_DIRICHLET && !seg->profile && isnan(seg->k) &&
     197          113 :            isnan(seg->eps) && isnan(seg->nu_tilde);
     198              : }
     199              : 
     200              : /**
     201              :  * Validate params->turb_bc.segments: the count against NS_TURB_BC_MAX_SEGMENTS,
     202              :  * every rule turbulence_bc_add_segment() applies, and, under k-epsilon, eps > 0
     203              :  * on a DIRICHLET segment without a profile.
     204              :  *
     205              :  * allow_detached accepts a segment marked by turb_segment_profile_detached().
     206              :  * Only solver init passes 1: load_simulation_from_checkpoint() initializes the
     207              :  * solver before its caller can re-attach the profile. Everything that steps
     208              :  * passes 0 -- the solver_step/solver_solve dispatchers, before any field moves,
     209              :  * and the shared step/BC validation, because the transport step reads the
     210              :  * segments (SA wall distance) before the BCs run.
     211              :  *
     212              :  * @return CFD_SUCCESS or CFD_ERROR_INVALID
     213              :  */
     214              : cfd_status_t turb_check_segments(const ns_solver_params_t* params, int allow_detached);
     215              : 
     216              : /** Shared argument/grid validation for the turbulence step (all backends):
     217              :  *  non-NULL args and fields, known model, 2D only, nx/ny >= 3, valid
     218              :  *  segments (turb_check_segments), uniform spacing. Assumes
     219              :  *  turb_model != TURB_MODEL_NONE was already checked. */
     220              : cfd_status_t turb_validate_step_args(const flow_field* field, const grid* grid,
     221              :                                      const ns_solver_params_t* params);
     222              : 
     223              : #endif /* CFD_TURBULENCE_SOLVER_INTERNAL_H */
        

Generated by: LCOV version 2.0-1