LCOV - code coverage report
Current view: top level - solvers/turbulence/cpu - turbulence_solver.c (source / functions) Coverage Total Hit
Test: coverage.info Lines: 91.6 % 546 500
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 32 32

            Line data    Source code
       1              : /**
       2              :  * @file turbulence_solver.c
       3              :  * @brief Scalar CPU implementation of the RANS turbulence solver
       4              :  *
       5              :  * Public entry points, model dispatch, boundary conditions, and the wall
       6              :  * functions (log law or Spalding's law of the wall). The per-model transport kernels live in
       7              :  * turbulence_kepsilon.c and turbulence_sa.c.
       8              :  */
       9              : 
      10              : #include "cfd/solvers/turbulence_solver.h"
      11              : #include "../turbulence_solver_internal.h"
      12              : #include "boundary/bc_edge_range.h"
      13              : 
      14              : #include "cfd/core/indexing.h"
      15              : #include "cfd/core/memory.h"
      16              : #include "cfd/nn/cfdnn.h"
      17              : 
      18              : #include <math.h>
      19              : #include <string.h>
      20              : 
      21              : /* Kinematic viscosity at a grid point (density-floored, like the RHS kernel). */
      22       176116 : static double local_nu(const ns_solver_params_t* params, const flow_field* field,
      23              :                        size_t idx) {
      24       176116 :     return params->mu / fmax(field->rho[idx], 1e-10);
      25              : }
      26              : 
      27              : /* SA viscous damping function fv1(chi). */
      28        55207 : static double sa_fv1(double chi) {
      29        55207 :     double chi3 = chi * chi * chi;
      30        55207 :     return chi3 / (chi3 + SA_CV1 * SA_CV1 * SA_CV1);
      31              : }
      32              : 
      33         1914 : void turb_update_nu_t(flow_field* field, const ns_solver_params_t* params) {
      34         1914 :     size_t total = field->nx * field->ny * field->nz;
      35              : 
      36         1914 :     if (params->turb_model == TURB_MODEL_K_EPSILON) {
      37       109379 :         for (size_t n = 0; n < total; n++) {
      38       108095 :             double nu = local_nu(params, field, n);
      39       108095 :             double k_c = fmax(field->turb_k[n], 0.0);
      40       108095 :             double eps_c = fmax(field->turb_eps[n], TURB_EPS_MIN);
      41       108095 :             double nu_t = TURB_C_MU * k_c * k_c / eps_c;
      42       108095 :             field->nu_t[n] = fmin(nu_t, TURB_NU_T_MAX_FACTOR * nu);
      43              :         }
      44          630 :     } else if (params->turb_model == TURB_MODEL_SPALART_ALLMARAS) {
      45        55751 :         for (size_t n = 0; n < total; n++) {
      46        55121 :             double nu = local_nu(params, field, n);
      47        55121 :             double nt = fmax(field->turb_nu_tilde[n], 0.0);
      48        55121 :             double nu_t = nt * sa_fv1(nt / nu);
      49        55121 :             field->nu_t[n] = fmin(nu_t, TURB_NU_T_MAX_FACTOR * nu);
      50              :         }
      51              :     }
      52         1914 : }
      53              : 
      54              : /* The k-epsilon eddy viscosity before the realizability clamp.
      55              :  *
      56              :  * turb_update_nu_t stores the CLAMPED value, so a correction that scaled
      57              :  * field->nu_t directly would be scaling the cap wherever the clamp had bound:
      58              :  * beta < 1 would shrink the cap rather than the model's own answer, and
      59              :  * beta > 1 could not lift a clamped value at all. Both corrections are
      60              :  * k-epsilon only, so this reproduces that branch of turb_update_nu_t exactly
      61              :  * and the single clamp then lands where the docs say it does -- after the
      62              :  * correction, not before and after. */
      63         1296 : static double turb_nu_t_raw(const flow_field* field, size_t n) {
      64         1296 :     const double k_c   = fmax(field->turb_k[n], 0.0);
      65         1296 :     const double eps_c = fmax(field->turb_eps[n], TURB_EPS_MIN);
      66         1296 :     return TURB_C_MU * k_c * k_c / eps_c;
      67              : }
      68              : 
      69              : 
      70              : /* ==========================================================================
      71              :  * Optional eddy-viscosity corrections: algebraic, or learned
      72              :  *
      73              :  * Two alternatives on one seam, and the algebraic one is the incumbent: a
      74              :  * power law in the dimensionless strain rate, which is a C_mu that varies with
      75              :  * the local strain. Per the design note's governing rule -- ML earns its place
      76              :  * only where no analytic answer exists -- a learned closure has to beat it on a
      77              :  * held-out Reynolds number to be worth shipping. Setting both is refused.
      78              :  *
      79              :  * Either way the correction is applied ON TOP of an active closure, never
      80              :  * instead of one: the features are built from k and epsilon, which only exist
      81              :  * when a transport model is running.
      82              :  *
      83              :  * Feature set, chosen by the locality study in
      84              :  * docs/technical-notes/ml-integration-design.md:
      85              :  *
      86              :  *   ln S*     = ln(|S| k / eps)     dimensionless strain rate
      87              :  *   ln Re_t   = ln(k^2 / (nu eps))  turbulent Reynolds number
      88              :  *   ln y+     = ln(y u_tau / nu)    approximated here by ln(nu_t/nu)
      89              :  *
      90              :  * Those were measured to generalise across Reynolds number better than the
      91              :  * non-local coordinate y/delta, which is what makes a local closure viable at
      92              :  * all. Note that ln Re_t and ln(nu_t/nu) are nearly collinear for k-epsilon
      93              :  * (nu_t/nu = C_mu Re_t by construction; measured correlation 0.93), so they
      94              :  * carry less independent information than their count suggests.
      95              :  *
      96              :  * Safety is structural, not hoped for -- but note what it does and does not
      97              :  * promise. The correction is MULTIPLICATIVE and the DNS data asks for beta < 1
      98              :  * in the outer layer, so this removes eddy viscosity as well as adding it. It
      99              :  * is not a dissipation-only correction, and the claim that it can only
     100              :  * over-diffuse does not hold:
     101              :  *   - beta is clamped to [TURB_CLOSURE_BETA_MIN, TURB_CLOSURE_BETA_MAX], so a
     102              :  *     wrong model can scale nu_t by at most 10x either way, never to zero and
     103              :  *     never negative;
     104              :  *   - the existing realizability clamp still runs afterwards, bounding the
     105              :  *     upper side a second time;
     106              :  *   - a non-finite prediction fails the step with CFD_ERROR_DIVERGED rather
     107              :  *     than seeding NaN into the momentum equation.
     108              :  * A reduced nu_t means less damping, so stability is bounded by the floor
     109              :  * rather than argued away: at beta = BETA_MIN the momentum equation sees at
     110              :  * worst the laminar-viscosity-dominated limit it already handles when the
     111              :  * turbulence model is off.
     112              :  *
     113              :  * Scope, for whoever trains the model: turbulence_apply_bcs() runs after this
     114              :  * and overwrites nu_t at wall nodes and at the first interior node next to a
     115              :  * no-slip wall with the wall-shear-matching value. The correction therefore
     116              :  * cannot move those points, which is consistent with the design note's caveat
     117              :  * that they measure the wall treatment rather than the transport equations.
     118              :  * ========================================================================== */
     119              : 
     120              : /**
     121              :  * Strain-rate magnitude |S| = sqrt(2 S_ij S_ij) at cell n, from central
     122              :  * differences.
     123              :  *
     124              :  * Boundary nodes reuse the nearest interior value rather than a one-sided
     125              :  * stencil, since the wall function governs them anyway. Shared by both
     126              :  * corrections so they cannot drift apart in how they see the flow.
     127              :  */
     128         1377 : static double turb_strain_magnitude(const flow_field* field, const grid* grid, size_t n) {
     129         1377 :     const size_t nx = field->nx, ny = field->ny;
     130         1377 :     const double dx = grid->dx ? grid->dx[0] : 1.0;
     131         1377 :     const double dy = grid->dy ? grid->dy[0] : 1.0;
     132              : 
     133         1377 :     size_t i = n % nx;
     134         1377 :     size_t j = (n / nx) % ny;
     135         1377 :     size_t ic = i == 0 ? 1 : (i == nx - 1 ? nx - 2 : i);
     136         1377 :     size_t jc = j == 0 ? 1 : (j == ny - 1 ? ny - 2 : j);
     137         1377 :     size_t c = (n / (nx * ny)) * nx * ny + jc * nx + ic;
     138              : 
     139         1377 :     double dudy = (field->u[c + nx] - field->u[c - nx]) / (2.0 * dy);
     140         1377 :     double dvdx = (field->v[c + 1] - field->v[c - 1]) / (2.0 * dx);
     141         1377 :     double dudx = (field->u[c + 1] - field->u[c - 1]) / (2.0 * dx);
     142         1377 :     double dvdy = (field->v[c + nx] - field->v[c - nx]) / (2.0 * dy);
     143         1377 :     double s12 = 0.5 * (dudy + dvdx);
     144         1377 :     return sqrt(2.0 * (dudx * dudx + dvdy * dvdy + 2.0 * s12 * s12));
     145              : }
     146              : 
     147              : /** Dimensionless strain rate S* = |S| k / epsilon at cell n. */
     148         1377 : static double turb_s_star(const flow_field* field, const grid* grid, size_t n) {
     149         1377 :     const double k_c = fmax(field->turb_k[n], TURB_K_MIN);
     150         1377 :     const double eps_c = fmax(field->turb_eps[n], TURB_EPS_MIN);
     151         1377 :     return turb_strain_magnitude(field, grid, n) * k_c / eps_c;
     152              : }
     153              : 
     154              : /**
     155              :  * Per-cell features for one tile of cells [base, base + count).
     156              :  *
     157              :  * Split out from the apply loop so the two array walks stay readable while the
     158              :  * grid is traversed in tiles; see TURB_CLOSURE_TILE for why it is tiled.
     159              :  */
     160           91 : static void turb_closure_features(const flow_field* field, const grid* grid,
     161              :                                   const ns_solver_params_t* params,
     162              :                                   size_t base, size_t count, double* feats) {
     163          982 :     for (size_t t = 0; t < count; t++) {
     164          891 :         const size_t n = base + t;
     165          891 :         const double nu = local_nu(params, field, n);
     166          891 :         const double k_c = fmax(field->turb_k[n], TURB_K_MIN);
     167          891 :         const double eps_c = fmax(field->turb_eps[n], TURB_EPS_MIN);
     168              : 
     169          891 :         double s_star = turb_s_star(field, grid, n);
     170          891 :         double re_t = k_c * k_c / (nu * eps_c);
     171          891 :         double nut_p = field->nu_t[n] / nu;
     172              : 
     173          891 :         double* f = feats + t * TURB_CLOSURE_FEATURES;
     174          891 :         f[0] = log(fmax(s_star, 1e-30));
     175          891 :         f[1] = log(fmax(re_t, 1e-30));
     176          891 :         f[2] = log(fmax(nut_p, 1e-30));
     177              :     }
     178           91 : }
     179              : 
     180              : /**
     181              :  * Algebraic correction: nu_t *= clamp(A * (S*)^B).
     182              :  *
     183              :  * Equivalent to a C_mu that varies with the local strain rate, since
     184              :  * nu_t = C_mu k^2 / eps. Coefficients and their provenance are at
     185              :  * TURB_ALG_BETA_A in the internal header.
     186              :  */
     187            6 : static void turb_apply_algebraic_correction(flow_field* field, const grid* grid,
     188              :                                             const ns_solver_params_t* params) {
     189            6 :     const size_t total = field->nx * field->ny * field->nz;
     190          492 :     for (size_t n = 0; n < total; n++) {
     191          486 :         const double s_star = fmax(turb_s_star(field, grid, n), 1e-30);
     192          486 :         double b = TURB_ALG_BETA_A * pow(s_star, TURB_ALG_BETA_B);
     193          486 :         b = fmin(fmax(b, TURB_CLOSURE_BETA_MIN), TURB_CLOSURE_BETA_MAX);
     194          486 :         const double nu = local_nu(params, field, n);
     195          486 :         field->nu_t[n] = fmin(turb_nu_t_raw(field, n) * b, TURB_NU_T_MAX_FACTOR * nu);
     196              :     }
     197            6 : }
     198              : 
     199          162 : static int is_nonnegative_finite(double v) {
     200          157 :     return isfinite(v) && v >= 0.0;
     201              : }
     202              : 
     203              : /* The model-independent rules for one segment; see turbulence_bc_add_segment.
     204              :  * allow_detached accepts a segment whose profile a checkpoint could not store
     205              :  * (turb_segment_profile_detached), which only solver init may do. */
     206          124 : static cfd_status_t validate_segment(const ns_turbulence_bc_segment_t* seg,
     207              :                                      int allow_detached) {
     208          124 :     const char* reason = NULL;
     209          124 :     if (seg->edge != BC_EDGE_LEFT && seg->edge != BC_EDGE_RIGHT &&
     210           24 :         seg->edge != BC_EDGE_BOTTOM && seg->edge != BC_EDGE_TOP) {
     211              :         reason = "turbulence BC segment: edge must be BC_EDGE_LEFT, _RIGHT, _BOTTOM or _TOP";
     212          120 :     } else if (!(seg->start >= 0.0 && seg->start < seg->end && seg->end <= 1.0)) {
     213              :         reason = "turbulence BC segment: range must satisfy 0 <= start < end <= 1";
     214          105 :     } else if (seg->type != BC_TYPE_NEUMANN && seg->type != BC_TYPE_DIRICHLET &&
     215              :                seg->type != BC_TYPE_NOSLIP) {
     216              :         reason = "turbulence BC segment: type must be NEUMANN, DIRICHLET or NOSLIP "
     217              :                  "(PERIODIC has no meaning on part of a face)";
     218          101 :     } else if (turb_segment_profile_detached(seg)) {
     219            7 :         if (!allow_detached) {
     220              :             reason = "turbulence BC segment: its profile was not stored in the checkpoint "
     221              :                      "it was loaded from; re-attach segments[n].profile before stepping";
     222              :         }
     223           94 :     } else if (seg->type == BC_TYPE_DIRICHLET && !seg->profile &&
     224           84 :                (!is_nonnegative_finite(seg->k) || !is_nonnegative_finite(seg->eps) ||
     225           38 :                 !is_nonnegative_finite(seg->nu_tilde))) {
     226              :         reason = "turbulence BC segment: DIRICHLET values must be finite and >= 0";
     227              :     }
     228              :     if (reason) {
     229           35 :         cfd_set_error(CFD_ERROR_INVALID, reason);
     230           35 :         return CFD_ERROR_INVALID;
     231              :     }
     232              :     return CFD_SUCCESS;
     233              : }
     234              : 
     235         3865 : cfd_status_t turb_check_segments(const ns_solver_params_t* params, int allow_detached) {
     236         3865 :     const ns_turbulence_bc_config_t* tbc = &params->turb_bc;
     237         3865 :     if (tbc->n_segments > NS_TURB_BC_MAX_SEGMENTS) {
     238            2 :         cfd_set_error(CFD_ERROR_INVALID,
     239              :                       "turbulence_solver: turb_bc.n_segments exceeds "
     240              :                       "NS_TURB_BC_MAX_SEGMENTS");
     241            2 :         return CFD_ERROR_INVALID;
     242              :     }
     243         3863 :     const int is_ke = (params->turb_model == TURB_MODEL_K_EPSILON);
     244         3908 :     for (size_t n = 0; n < tbc->n_segments; n++) {
     245           69 :         const ns_turbulence_bc_segment_t* seg = &tbc->segments[n];
     246           69 :         cfd_status_t status = validate_segment(seg, allow_detached);
     247           69 :         if (status != CFD_SUCCESS) {
     248           23 :             return status;
     249              :         }
     250           46 :         if (is_ke && seg->type == BC_TYPE_DIRICHLET && !seg->profile &&
     251           46 :             !turb_segment_profile_detached(seg) && !(seg->eps > 0.0)) {
     252            1 :             cfd_set_error(CFD_ERROR_INVALID,
     253              :                           "turbulence_solver: a k-epsilon DIRICHLET segment needs "
     254              :                           "eps > 0 or a profile");
     255            1 :             return CFD_ERROR_INVALID;
     256              :         }
     257              :     }
     258              :     return CFD_SUCCESS;
     259              : }
     260              : 
     261        28601 : cfd_status_t turb_check_closure_config(const ns_solver_params_t* params) {
     262        28601 :     if (!params) {
     263              :         return CFD_SUCCESS;
     264              :     }
     265        28601 :     if (params->turb_nut_correction != NS_NUT_CORRECTION_NONE &&
     266              :         params->turb_nut_correction != NS_NUT_CORRECTION_S_STAR) {
     267            2 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown ns_solver_params_t.turb_nut_correction");
     268            2 :         return CFD_ERROR_INVALID;
     269              :     }
     270              :     /* Two multipliers on nu_t would compound, and the result would be neither
     271              :      * the fitted algebraic correction nor the trained one. Pick one. */
     272        28599 :     if (params->turb_closure && params->turb_nut_correction != NS_NUT_CORRECTION_NONE) {
     273            2 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     274              :                       "params.turb_closure and params.turb_nut_correction are "
     275              :                       "alternatives: set one, not both");
     276            2 :         return CFD_ERROR_UNSUPPORTED;
     277              :     }
     278        28597 :     if (!params->turb_closure && params->turb_nut_correction == NS_NUT_CORRECTION_NONE) {
     279              :         return CFD_SUCCESS; /* feature off */
     280              :     }
     281              :     /* SA carries no k/epsilon, so S* and its companions are undefined for it,
     282              :      * and with no model at all there is nothing to correct. Refused rather than
     283              :      * ignored: a caller who configured a correction asked for it to run. */
     284           45 :     if (params->turb_model != TURB_MODEL_K_EPSILON) {
     285            7 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     286              :                       "an eddy-viscosity correction requires TURB_MODEL_K_EPSILON: its "
     287              :                       "features are built from k and epsilon, which no other model carries");
     288            7 :         return CFD_ERROR_UNSUPPORTED;
     289              :     }
     290           38 :     if (!params->turb_closure) {
     291              :         return CFD_SUCCESS; /* algebraic correction needs no model */
     292              :     }
     293              : 
     294           25 :     const cfd_nn_model_t* model = cfd_nn_context_model(params->turb_closure);
     295           25 :     if (!model) {
     296            0 :         cfd_set_error(CFD_ERROR_INVALID, "params.turb_closure carries no model");
     297            0 :         return CFD_ERROR_INVALID;
     298              :     }
     299           48 :     if (cfd_nn_model_inputs(model) != TURB_CLOSURE_FEATURES ||
     300           23 :         cfd_nn_model_outputs(model) != TURB_CLOSURE_OUTPUTS) {
     301            2 :         cfd_set_error(CFD_ERROR_INVALID,
     302              :                       "params.turb_closure model shape must be 3 inputs -> 1 output "
     303              :                       "(ln S*, ln Re_t, ln nu_t/nu -> beta)");
     304            2 :         return CFD_ERROR_INVALID;
     305              :     }
     306           23 :     if (cfd_nn_context_capacity(params->turb_closure) == 0) {
     307            0 :         cfd_set_error(CFD_ERROR_INVALID, "params.turb_closure has zero batch capacity");
     308            0 :         return CFD_ERROR_INVALID;
     309              :     }
     310              :     return CFD_SUCCESS;
     311              : }
     312              : 
     313         1870 : cfd_status_t turb_apply_nu_t_correction(flow_field* field, const grid* grid,
     314              :                                         const ns_solver_params_t* params) {
     315         1870 :     if (!params || (!params->turb_closure &&
     316         1859 :                     params->turb_nut_correction == NS_NUT_CORRECTION_NONE)) {
     317              :         return CFD_SUCCESS; /* feature off: bit-identical to the un-corrected path */
     318              :     }
     319              : 
     320           17 :     cfd_status_t status = turb_check_closure_config(params);
     321           17 :     if (status != CFD_SUCCESS) {
     322              :         return status;
     323              :     }
     324           17 :     if (!field || !grid || !field->nu_t || !field->turb_k || !field->turb_eps) {
     325            0 :         cfd_set_error(CFD_ERROR_INVALID,
     326              :                       "turb_apply_nu_t_correction: missing field, grid or k-epsilon state");
     327            0 :         return CFD_ERROR_INVALID;
     328              :     }
     329              : 
     330           17 :     const size_t nx = field->nx, ny = field->ny;
     331           17 :     const size_t total = nx * ny * field->nz;
     332           17 :     if (total == 0) {
     333              :         return CFD_SUCCESS;
     334              :     }
     335              :     /* The central-difference features need one interior neighbour each way.
     336              :      * The step validator already enforces this; a direct caller may not have. */
     337           17 :     if (nx < 3 || ny < 3) {
     338            0 :         cfd_set_error(CFD_ERROR_INVALID,
     339              :                       "turb_apply_nu_t_correction requires nx >= 3 and ny >= 3");
     340            0 :         return CFD_ERROR_INVALID;
     341              :     }
     342              : 
     343           17 :     if (params->turb_nut_correction == NS_NUT_CORRECTION_S_STAR) {
     344            6 :         turb_apply_algebraic_correction(field, grid, params);
     345            6 :         return CFD_SUCCESS;
     346              :     }
     347              : 
     348              :     /* Tiled so the scratch is a fixed stack allocation rather than a per-step
     349              :      * malloc, and so a context smaller than the grid still works -- it just
     350              :      * makes the tiles smaller. */
     351           11 :     size_t tile = cfd_nn_context_capacity(params->turb_closure);
     352           11 :     if (tile > TURB_CLOSURE_TILE) {
     353              :         tile = TURB_CLOSURE_TILE;
     354              :     }
     355           11 :     double feats[TURB_CLOSURE_TILE * TURB_CLOSURE_FEATURES];
     356           11 :     double beta[TURB_CLOSURE_TILE];
     357              : 
     358          101 :     for (size_t base = 0; base < total; base += tile) {
     359           91 :         const size_t count = (total - base < tile) ? (total - base) : tile;
     360              : 
     361           91 :         turb_closure_features(field, grid, params, base, count, feats);
     362              : 
     363           91 :         status = cfd_nn_predict_batch(params->turb_closure, count, feats,
     364              :                                       count * TURB_CLOSURE_FEATURES, beta, count);
     365           91 :         if (status != CFD_SUCCESS) {
     366            1 :             cfd_set_error(status,
     367              :                           "learned eddy-viscosity closure: inference failed; nu_t is "
     368              :                           "left as the k-epsilon model produced it and the step fails");
     369            1 :             return status;
     370              :         }
     371              : 
     372          900 :         for (size_t t = 0; t < count; t++) {
     373          810 :             const size_t n = base + t;
     374          810 :             const double b = fmin(fmax(beta[t], TURB_CLOSURE_BETA_MIN), TURB_CLOSURE_BETA_MAX);
     375          810 :             const double nu = local_nu(params, field, n);
     376          810 :             field->nu_t[n] =
     377          810 :                 fmin(turb_nu_t_raw(field, n) * b, TURB_NU_T_MAX_FACTOR * nu);
     378              :         }
     379              :     }
     380              :     return CFD_SUCCESS;
     381              : }
     382              : 
     383              : /* Type of the last segment on `edge` whose range strictly contains normalized
     384              :  * position t, or face_type. Used for wall distance, where t is an interval
     385              :  * midpoint and never sits on a bound, so the node-level slack does not apply. */
     386           11 : static bc_type_t segment_type_at(const ns_turbulence_bc_config_t* tbc, bc_edge_t edge,
     387              :                                  bc_type_t face_type, double t) {
     388           17 :     for (size_t n = tbc->n_segments; n-- > 0;) {
     389           11 :         const ns_turbulence_bc_segment_t* seg = &tbc->segments[n];
     390           11 :         if (seg->edge == edge && t >= seg->start && t <= seg->end) {
     391            5 :             return seg->type;
     392              :         }
     393              :     }
     394              :     return face_type;
     395              : }
     396              : 
     397              : /*
     398              :  * Fold one face's wall into the running minimum distance *d.
     399              :  *
     400              :  * normal: distance from the point to the face's line. along: the point's
     401              :  * coordinate along the face, which spans [lo, hi].
     402              :  *
     403              :  * Without segments on this face the face is a wall or not, and the distance is
     404              :  * `normal` exactly, as it always was. With segments, the face is cut at every
     405              :  * segment bound; each piece is a wall when its midpoint resolves to NOSLIP, and
     406              :  * the distance to a wall piece is the distance to that line segment. Position
     407              :  * maps to coordinate linearly, which is exact on the uniform grids the
     408              :  * turbulence models require.
     409              :  */
     410       134412 : static void face_wall_distance(const ns_turbulence_bc_config_t* tbc, bc_edge_t edge,
     411              :                                bc_type_t face_type, double normal, double along,
     412              :                                double lo, double hi, double* d, int* found) {
     413       134412 :     double cuts[2 + 2 * NS_TURB_BC_MAX_SEGMENTS];
     414       134412 :     size_t n_cuts = 0;
     415       134412 :     cuts[n_cuts++] = 0.0;
     416       134412 :     cuts[n_cuts++] = 1.0;
     417       134432 :     for (size_t n = 0; n < tbc->n_segments; n++) {
     418           20 :         if (tbc->segments[n].edge == edge) {
     419            5 :             cuts[n_cuts++] = tbc->segments[n].start;
     420            5 :             cuts[n_cuts++] = tbc->segments[n].end;
     421              :         }
     422              :     }
     423              : 
     424       134412 :     if (n_cuts == 2) {
     425       134407 :         if (face_type == BC_TYPE_NOSLIP) {
     426        56945 :             *d = *found ? fmin(*d, normal) : normal;
     427        56945 :             *found = 1;
     428              :         }
     429       134407 :         return;
     430              :     }
     431              : 
     432              :     /* Insertion sort: at most 2 + 2 * NS_TURB_BC_MAX_SEGMENTS values. */
     433           20 :     for (size_t a = 1; a < n_cuts; a++) {
     434           15 :         double v = cuts[a];
     435           15 :         size_t b = a;
     436           22 :         while (b > 0 && cuts[b - 1] > v) {
     437            7 :             cuts[b] = cuts[b - 1];
     438            7 :             b--;
     439              :         }
     440           15 :         cuts[b] = v;
     441              :     }
     442              : 
     443            5 :     const double span = hi - lo;
     444           20 :     for (size_t a = 0; a + 1 < n_cuts; a++) {
     445           15 :         if (!(cuts[a + 1] > cuts[a])) {
     446            4 :             continue;
     447              :         }
     448           11 :         double mid = 0.5 * (cuts[a] + cuts[a + 1]);
     449           22 :         if (segment_type_at(tbc, edge, face_type, mid) != BC_TYPE_NOSLIP) {
     450            7 :             continue;
     451              :         }
     452            4 :         double p_lo = lo + cuts[a] * span;
     453            4 :         double p_hi = lo + cuts[a + 1] * span;
     454            4 :         double off = 0.0;
     455            4 :         if (along < p_lo) {
     456            0 :             off = p_lo - along;
     457            4 :         } else if (along > p_hi) {
     458            2 :             off = along - p_hi;
     459              :         }
     460            2 :         double c = (off > 0.0) ? hypot(normal, off) : normal;
     461            4 :         *d = *found ? fmin(*d, c) : c;
     462            4 :         *found = 1;
     463              :     }
     464              : }
     465              : 
     466        33603 : double turb_wall_distance(const grid* grid, const ns_turbulence_bc_config_t* tbc,
     467              :                           size_t i, size_t j, int* has_wall) {
     468        33603 :     double d = 0.0;
     469        33603 :     int found = 0;
     470        33603 :     const double x = grid->x[i];
     471        33603 :     const double y = grid->y[j];
     472        33603 :     const double x0 = grid->x[0];
     473        33603 :     const double x1 = grid->x[grid->nx - 1];
     474        33603 :     const double y0 = grid->y[0];
     475        33603 :     const double y1 = grid->y[grid->ny - 1];
     476              : 
     477        33603 :     face_wall_distance(tbc, BC_EDGE_LEFT, tbc->left, x - x0, y, y0, y1, &d, &found);
     478        33603 :     face_wall_distance(tbc, BC_EDGE_RIGHT, tbc->right, x1 - x, y, y0, y1, &d, &found);
     479        33603 :     face_wall_distance(tbc, BC_EDGE_BOTTOM, tbc->bottom, y - y0, x, x0, x1, &d, &found);
     480        33603 :     face_wall_distance(tbc, BC_EDGE_TOP, tbc->top, y1 - y, x, x0, x1, &d, &found);
     481              : 
     482        33603 :     *has_wall = found;
     483        33603 :     return d;
     484              : }
     485              : 
     486              : /* sum_{n >= n0} x^n / n!, the tail of e^x after its first n0 terms. Summed as
     487              :  * a series for x <= 1, where e^x minus the partial sum would cancel and leave
     488              :  * Spalding's sublayer correction as rounding noise. */
     489         7152 : static double exp_tail(double x, int n0) {
     490         7152 :     if (x > 1.0) {
     491              :         double partial = 1.0;
     492              :         double t = 1.0;
     493        24899 :         for (int n = 1; n < n0; n++) {
     494        17785 :             t *= x / n;
     495        17785 :             partial += t;
     496              :         }
     497         7114 :         return exp(x) - partial;
     498              :     }
     499              :     double t = 1.0;
     500          171 :     for (int n = 1; n <= n0; n++) {
     501          133 :         t *= x / n;
     502              :     }
     503              :     double sum = 0.0;
     504          798 :     for (int n = n0; n < n0 + 20; n++) {
     505          760 :         sum += t;
     506          760 :         t *= x / (n + 1);
     507              :     }
     508              :     return sum;
     509              : }
     510              : 
     511              : /*
     512              :  * Spalding's law of the wall, one smooth y+(u+) through all three layers:
     513              :  *   y+ = u+ + e^{-kappa B} [e^{kappa u+} - 1 - kappa u+ - (kappa u+)^2/2 - (kappa u+)^3/6]
     514              :  * Linear (y+ -> u+) in the viscous sublayer, logarithmic (u+ -> ln(y+)/kappa + B)
     515              :  * deep in the log layer, blended through the buffer layer.
     516              :  *
     517              :  * With u+ = u_p/u_tau and y+ = u_tau*y_p/nu, their product is the known wall
     518              :  * Reynolds number Re_p = u_p*y_p/nu, so solve for u+ alone:
     519              :  *   G(u+) = ln(u+) + ln(y+(u+)) - ln(Re_p) = 0.
     520              :  * G increases with u+, so the root is unique. Since y+ >= u+, sqrt(Re_p) (the
     521              :  * linear-law answer) bounds it above; Newton is safeguarded by bisection
     522              :  * inside that bracket.
     523              :  */
     524          725 : static double wall_u_tau_spalding(double u_p, double y_p, double nu) {
     525          725 :     const double c = exp(-WALL_KAPPA * WALL_B);
     526          725 :     const double log_re = log(u_p) + log(y_p) - log(nu);
     527              : 
     528              :     /* The cap keeps e^{kappa u+} finite; u+ reaches it only for Re_p ~ 1e300. */
     529          725 :     double lo = 0.0;
     530          725 :     double hi = fmin(exp(0.5 * log_re), 700.0 / WALL_KAPPA);
     531              :     /* Log-law estimate: close wherever the linear-law bound is not. */
     532          725 :     double up = fmin(hi, WALL_B + log_re / WALL_KAPPA);
     533          725 :     if (!(up > 0.0)) {
     534            8 :         up = hi;
     535              :     }
     536              : 
     537         3576 :     for (int it = 0; it < 100; it++) {
     538         3576 :         const double ku = WALL_KAPPA * up;
     539         3576 :         const double yplus = up + c * exp_tail(ku, 4);
     540         3576 :         const double dyplus = 1.0 + c * WALL_KAPPA * exp_tail(ku, 3);
     541         3576 :         const double g = log(up) + log(yplus) - log_re;
     542         3576 :         if (g == 0.0) {
     543              :             break;
     544              :         }
     545         3148 :         if (g > 0.0) {
     546              :             hi = up;
     547              :         } else {
     548          169 :             lo = up;
     549              :         }
     550         3148 :         double next = up - g / (1.0 / up + dyplus / yplus);
     551         3148 :         if (!(next > lo && next <= hi)) {
     552            0 :             next = 0.5 * (lo + hi);
     553              :         }
     554         3148 :         const int converged = fabs(next - up) <= 1e-14 * up;
     555         3148 :         up = next;
     556         3148 :         if (converged) {
     557              :             break;
     558              :         }
     559              :     }
     560          725 :     return u_p / up;
     561              : }
     562              : 
     563              : /*
     564              :  * y+ where the linear law u+ = y+ meets the log law u+ = ln(y+)/kappa + B:
     565              :  * 11.06 at kappa = 0.41, B = 5.2. Solved rather than hard-coded so it follows
     566              :  * the constants; a switch placed anywhere else (the former 11.63) makes u_tau
     567              :  * jump, 3.3% there. f(y) = y - ln(y)/kappa - B has a second root below y = 1;
     568              :  * Newton from 11 converges to this one in a few steps.
     569              :  */
     570        11222 : static double wall_yplus_crossover(void) {
     571        11222 :     double y = 11.0;
     572        44888 :     for (int it = 0; it < 20; it++) {
     573        44888 :         double next = y - (y - log(y) / WALL_KAPPA - WALL_B) / (1.0 - 1.0 / (WALL_KAPPA * y));
     574        44888 :         const int converged = fabs(next - y) <= 1e-14 * y;
     575        44888 :         y = next;
     576        44888 :         if (converged) {
     577              :             break;
     578              :         }
     579              :     }
     580        11222 :     return y;
     581              : }
     582              : 
     583              : /*
     584              :  * Linear law below the crossover, log law above it. With u+ = u_p/u_tau and
     585              :  * y+ = u_tau*y_p/nu, u+ * y+ = Re_p = u_p*y_p/nu, so the switch is
     586              :  * Re_p <= y+_c^2, known before u_tau is. There the linear answer
     587              :  * sqrt(nu*u_p/y_p) puts u+ = y+ = y+_c on both laws, so u_tau is continuous.
     588              :  * Above it, Newton on ut*(ln(ut*y_p/nu)/kappa + B) = u_p from the linear value.
     589              :  */
     590        11222 : static double wall_u_tau_log(double u_p, double y_p, double nu) {
     591        11222 :     const double yc = wall_yplus_crossover();
     592        11222 :     double ut = sqrt(nu * u_p / y_p);
     593        11222 :     if (u_p * y_p / nu <= yc * yc) {
     594              :         return ut;
     595              :     }
     596        47909 :     for (int it = 0; it < 50; it++) {
     597        47909 :         const double yplus = ut * y_p / nu;
     598        47909 :         const double f = ut * (log(yplus) / WALL_KAPPA + WALL_B) - u_p;
     599        47909 :         const double fp = (log(yplus) + 1.0) / WALL_KAPPA + WALL_B;
     600        47909 :         double next = ut - f / fp;
     601        47909 :         if (next < 1e-12) {
     602            0 :             next = 1e-12;
     603              :         }
     604        47909 :         const int converged = fabs(next - ut) <= 1e-14 * ut;
     605        47909 :         ut = next;
     606        47909 :         if (converged) {
     607              :             break;
     608              :         }
     609              :     }
     610              :     return ut;
     611              : }
     612              : 
     613        11954 : double turbulence_wall_u_tau(ns_wall_law_t law, double u_p, double y_p, double nu) {
     614        11954 :     if (u_p <= 0.0 || y_p <= 0.0 || nu <= 0.0) {
     615              :         return 0.0;
     616              :     }
     617        11948 :     switch (law) {
     618        11222 :         case NS_WALL_LAW_LOG:
     619        11222 :             return wall_u_tau_log(u_p, y_p, nu);
     620          725 :         case NS_WALL_LAW_SPALDING:
     621          725 :             return wall_u_tau_spalding(u_p, y_p, nu);
     622              :     }
     623              :     return 0.0;
     624              : }
     625              : 
     626              : /* Validate uniform spacing (the transport stencils assume it, like energy). */
     627         1870 : static cfd_status_t validate_uniform_spacing(const grid* grid, size_t nx, size_t ny) {
     628         1870 :     const double dx0 = grid->dx[0];
     629         1870 :     const double tol_x = 1e-12 * fmax(1.0, fabs(dx0));
     630        15256 :     for (size_t i = 1; i < nx - 1; i++) {
     631        13386 :         if (fabs(grid->dx[i] - dx0) > tol_x) {
     632            0 :             cfd_set_error(CFD_ERROR_UNSUPPORTED,
     633              :                           "turbulence_solver: non-uniform dx not supported");
     634            0 :             return CFD_ERROR_UNSUPPORTED;
     635              :         }
     636              :     }
     637         1870 :     const double dy0 = grid->dy[0];
     638         1870 :     const double tol_y = 1e-12 * fmax(1.0, fabs(dy0));
     639        15256 :     for (size_t j = 1; j < ny - 1; j++) {
     640        13386 :         if (fabs(grid->dy[j] - dy0) > tol_y) {
     641            0 :             cfd_set_error(CFD_ERROR_UNSUPPORTED,
     642              :                           "turbulence_solver: non-uniform dy not supported");
     643            0 :             return CFD_ERROR_UNSUPPORTED;
     644              :         }
     645              :     }
     646              :     return CFD_SUCCESS;
     647              : }
     648              : 
     649              : /* Shared validation for step and BC application. */
     650         3797 : static cfd_status_t validate_turbulence_args(const flow_field* field, const grid* grid,
     651              :                                              const ns_solver_params_t* params) {
     652         3797 :     if (!field || !grid || !params) {
     653            0 :         cfd_set_error(CFD_ERROR_INVALID,
     654              :                       "turbulence_solver: field, grid, and params must be non-NULL");
     655            0 :         return CFD_ERROR_INVALID;
     656              :     }
     657         3797 :     if (!field->turb_k || !field->turb_eps || !field->turb_nu_tilde || !field->nu_t) {
     658            0 :         cfd_set_error(CFD_ERROR_INVALID,
     659              :                       "turbulence_solver: missing turbulence fields");
     660            0 :         return CFD_ERROR_INVALID;
     661              :     }
     662         3797 :     if (params->turb_model != TURB_MODEL_K_EPSILON &&
     663              :         params->turb_model != TURB_MODEL_SPALART_ALLMARAS) {
     664            0 :         cfd_set_error(CFD_ERROR_INVALID,
     665              :                       "turbulence_solver: unknown turbulence model");
     666            0 :         return CFD_ERROR_INVALID;
     667              :     }
     668              :     /* nu = mu/rho appears in denominators (SA chi, wall functions); mu <= 0
     669              :      * would produce Inf/NaN rather than a diagnosable error. */
     670         3797 :     if (params->mu <= 0.0) {
     671            0 :         cfd_set_error(CFD_ERROR_INVALID,
     672              :                       "turbulence_solver: mu must be positive when a "
     673              :                       "turbulence model is active");
     674            0 :         return CFD_ERROR_INVALID;
     675              :     }
     676         3797 :     if (field->nz > 1) {
     677            0 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     678              :                       "turbulence_solver: 3D turbulence not supported");
     679            0 :         return CFD_ERROR_UNSUPPORTED;
     680              :     }
     681         3797 :     if (!grid->dx || !grid->dy || field->nx < 3 || field->ny < 3) {
     682            0 :         cfd_set_error(CFD_ERROR_INVALID,
     683              :                       "turbulence_solver: grid too small or missing dx/dy");
     684            0 :         return CFD_ERROR_INVALID;
     685              :     }
     686              :     /* Shared by the step and the BCs, not left to the BCs: the transport step
     687              :      * reads the segments too (SA wall distance) and runs before the BCs do. */
     688         3797 :     return turb_check_segments(params, 0);
     689              : }
     690              : 
     691         1874 : cfd_status_t turb_validate_step_args(const flow_field* field, const grid* grid,
     692              :                                      const ns_solver_params_t* params) {
     693         1874 :     cfd_status_t status = validate_turbulence_args(field, grid, params);
     694         1874 :     if (status != CFD_SUCCESS) {
     695              :         return status;
     696              :     }
     697         1870 :     return validate_uniform_spacing(grid, field->nx, field->ny);
     698              : }
     699              : 
     700        26853 : cfd_status_t turbulence_step_explicit_with_workspace(
     701              :     flow_field* field, const grid* grid,
     702              :     const ns_solver_params_t* params,
     703              :     double dt, double time,
     704              :     double* workspace, size_t workspace_size) {
     705        26853 :     (void)time;
     706              : 
     707        26853 :     if (!params) {
     708            0 :         cfd_set_error(CFD_ERROR_INVALID, "turbulence_solver: params must be non-NULL");
     709            0 :         return CFD_ERROR_INVALID;
     710              :     }
     711              :     /* Checked before the disabled-model exit below: a correction configured
     712              :      * against no turbulence model is refused here exactly as it is at solver
     713              :      * init, rather than silently skipped because the step has nothing to do. */
     714        26853 :     cfd_status_t status = turb_check_closure_config(params);
     715        26853 :     if (status != CFD_SUCCESS) {
     716              :         return status;
     717              :     }
     718              :     /* Turbulence disabled: a legitimate no-op. */
     719        26847 :     if (params->turb_model == TURB_MODEL_NONE) {
     720              :         return CFD_SUCCESS;
     721              :     }
     722              : 
     723         1874 :     status = turb_validate_step_args(field, grid, params);
     724         1874 :     if (status != CFD_SUCCESS) {
     725              :         return status;
     726              :     }
     727              : 
     728         1870 :     size_t total = field->nx * field->ny * field->nz;
     729              : 
     730              :     /* Use caller's workspace or allocate internally */
     731         1870 :     int owns_buffer = 0;
     732         1870 :     double* buf;
     733         1870 :     if (workspace && workspace_size >= TURB_WORKSPACE_SIZE(total)) {
     734              :         buf = workspace;
     735              :     } else {
     736         1829 :         buf = (double*)cfd_calloc(TURB_WORKSPACE_SIZE(total), sizeof(double));
     737         1829 :         if (!buf) {
     738              :             return CFD_ERROR_NOMEM;
     739              :         }
     740              :         owns_buffer = 1;
     741              :     }
     742              : 
     743         1870 :     if (params->turb_model == TURB_MODEL_K_EPSILON) {
     744         1248 :         double* k_new = buf;
     745         1248 :         double* eps_new = buf + total;
     746         1248 :         memcpy(k_new, field->turb_k, total * sizeof(double));
     747         1248 :         memcpy(eps_new, field->turb_eps, total * sizeof(double));
     748              : 
     749         1248 :         turb_kepsilon_step_scalar(field, grid, params, dt, k_new, eps_new);
     750              : 
     751       106044 :         for (size_t n = 0; n < total; n++) {
     752       104796 :             if (!isfinite(k_new[n]) || !isfinite(eps_new[n])) {
     753            0 :                 cfd_set_error(CFD_ERROR_DIVERGED,
     754              :                               "NaN/Inf detected in turbulence_step_explicit (k-epsilon)");
     755            0 :                 if (owns_buffer) cfd_free(buf);
     756            0 :                 return CFD_ERROR_DIVERGED;
     757              :             }
     758              :         }
     759         1248 :         memcpy(field->turb_k, k_new, total * sizeof(double));
     760         1248 :         memcpy(field->turb_eps, eps_new, total * sizeof(double));
     761              :     } else {
     762          622 :         double* nt_new = buf;
     763          622 :         memcpy(nt_new, field->turb_nu_tilde, total * sizeof(double));
     764              : 
     765          622 :         turb_sa_step_scalar(field, grid, params, dt, nt_new);
     766              : 
     767        54712 :         for (size_t n = 0; n < total; n++) {
     768        54090 :             if (!isfinite(nt_new[n])) {
     769            0 :                 cfd_set_error(CFD_ERROR_DIVERGED,
     770              :                               "NaN/Inf detected in turbulence_step_explicit (SA)");
     771            0 :                 if (owns_buffer) cfd_free(buf);
     772            0 :                 return CFD_ERROR_DIVERGED;
     773              :             }
     774              :         }
     775          622 :         memcpy(field->turb_nu_tilde, nt_new, total * sizeof(double));
     776              :     }
     777              : 
     778         1870 :     turb_update_nu_t(field, params);
     779         1870 :     cfd_status_t closure_status = turb_apply_nu_t_correction(field, grid, params);
     780              : 
     781         1870 :     if (owns_buffer) cfd_free(buf);
     782              :     return closure_status;
     783              : }
     784              : 
     785         1840 : cfd_status_t turbulence_step_explicit(flow_field* field, const grid* grid,
     786              :                                       const ns_solver_params_t* params,
     787              :                                       double dt, double time) {
     788         1840 :     return turbulence_step_explicit_with_workspace(field, grid, params,
     789              :                                                    dt, time, NULL, 0);
     790              : }
     791              : 
     792              : /* A face may only request a turbulence BC type the solver implements. */
     793              : static int is_supported_turb_bc(bc_type_t type) {
     794              :     return type == BC_TYPE_PERIODIC || type == BC_TYPE_NEUMANN ||
     795              :            type == BC_TYPE_DIRICHLET || type == BC_TYPE_NOSLIP;
     796              : }
     797              : 
     798              : /*
     799              :  * Wall function at one wall node, u_tau from the law in params->turb_bc.wall_law.
     800              :  *
     801              :  * idx_w: wall node, idx_p: first interior node at distance y_p, u_p: wall-
     802              :  * parallel speed at idx_p. Sets equilibrium turbulence values at the first
     803              :  * interior node (fixed-value wall-function variant):
     804              :  *   k_p  = u_tau^2 / sqrt(C_mu)      eps_p = u_tau^3 / (kappa*y_p)
     805              :  *   nt_p = kappa*u_tau*y_p
     806              :  * and imposes the wall-law momentum sink through the wall-face viscosity: the
     807              :  * discrete wall shear is (nu + 0.5*(nu_t_w + nu_t_p)) * u_p/y_p, so storing
     808              :  *   nu_t_w = 0,   nu_t_p = max(2*(u_tau^2*y_p/u_p - nu), 0)
     809              :  * makes it exactly u_tau^2. The equilibrium eddy viscosity kappa*u_tau*y_p is
     810              :  * deliberately NOT stored at idx_p: the coarse one-sided gradient u_p/y_p
     811              :  * cannot represent the log profile's curvature, and pairing it with the
     812              :  * physical nu_t would overpredict the wall shear several-fold. Both wall laws
     813              :  * have y+ >= u+, so u_tau^2*y_p/u_p = nu*y+/u+ >= nu and nu_t_p is never
     814              :  * negative. In the viscous sublayer it is exactly 0 on the log law's linear
     815              :  * branch and vanishes as (kappa*u+)^4 on Spalding's (laminar shear).
     816              :  */
     817        10522 : static void apply_wall_function_node(flow_field* field,
     818              :                                      const ns_solver_params_t* params,
     819              :                                      size_t idx_w, size_t idx_p,
     820              :                                      double y_p, double u_p) {
     821        10522 :     double nu = local_nu(params, field, idx_p);
     822        10522 :     double ut = turbulence_wall_u_tau(params->turb_bc.wall_law, u_p, y_p, nu);
     823              : 
     824        10522 :     if (params->turb_model == TURB_MODEL_K_EPSILON) {
     825          790 :         field->turb_k[idx_p] = fmax(ut * ut / sqrt(TURB_C_MU), TURB_K_MIN);
     826          790 :         field->turb_eps[idx_p] = fmax(ut * ut * ut / (WALL_KAPPA * y_p), TURB_EPS_MIN);
     827          790 :         field->turb_k[idx_w] = 0.0;
     828          790 :         field->turb_eps[idx_w] = field->turb_eps[idx_p];
     829              :     } else {
     830         9732 :         field->turb_nu_tilde[idx_p] = WALL_KAPPA * ut * y_p;
     831         9732 :         field->turb_nu_tilde[idx_w] = 0.0;
     832              :     }
     833              : 
     834              :     /* Wall-shear-matching viscosity (see function comment), subject to the
     835              :      * same realizability bound as turb_update_nu_t: on very coarse grids or
     836              :      * near-zero u_p the matching formula can blow up and destabilize the
     837              :      * momentum step / time-step estimation. */
     838        10522 :     if (u_p > 1e-12) {
     839        10522 :         double nu_wall_eff = ut * ut * y_p / u_p;
     840        10522 :         field->nu_t[idx_p] = fmin(fmax(2.0 * (nu_wall_eff - nu), 0.0),
     841              :                                   TURB_NU_T_MAX_FACTOR * nu);
     842              :     } else {
     843            0 :         field->nu_t[idx_p] = 0.0;
     844              :     }
     845        10522 :     field->nu_t[idx_w] = 0.0;
     846        10522 : }
     847              : 
     848              : /* Apply one BC type to one scalar array cell (periodic/neumann/dirichlet). */
     849       162723 : static void apply_scalar_face_bc(double* arr, bc_type_t type, size_t idx,
     850              :                                  size_t idx_interior, size_t idx_periodic,
     851              :                                  double dirichlet_value) {
     852       162723 :     if (type == BC_TYPE_DIRICHLET) {
     853          296 :         arr[idx] = dirichlet_value;
     854       103608 :     } else if (type == BC_TYPE_NEUMANN) {
     855         4427 :         arr[idx] = arr[idx_interior];
     856       158000 :     } else if (type == BC_TYPE_PERIODIC) {
     857       158000 :         arr[idx] = arr[idx_periodic];
     858              :     }
     859              :     /* BC_TYPE_NOSLIP handled by the wall-function path, not here. */
     860              : }
     861              : 
     862              : /* Set nu_t at a Dirichlet boundary node consistently with the fixed values. */
     863          191 : static void set_dirichlet_nu_t(flow_field* field, const ns_solver_params_t* params,
     864              :                                size_t idx) {
     865          191 :     double nu = local_nu(params, field, idx);
     866          191 :     double nu_t;
     867          191 :     if (params->turb_model == TURB_MODEL_K_EPSILON) {
     868          105 :         double k_c = fmax(field->turb_k[idx], 0.0);
     869          105 :         double eps_c = fmax(field->turb_eps[idx], TURB_EPS_MIN);
     870          105 :         nu_t = TURB_C_MU * k_c * k_c / eps_c;
     871              :     } else {
     872           86 :         double nt = fmax(field->turb_nu_tilde[idx], 0.0);
     873           86 :         nu_t = nt * sa_fv1(nt / nu);
     874              :     }
     875          191 :     field->nu_t[idx] = fmin(nu_t, TURB_NU_T_MAX_FACTOR * nu);
     876          191 : }
     877              : 
     878              : /* The BC one boundary node receives: its type and, for DIRICHLET, its values. */
     879              : typedef struct {
     880              :     bc_type_t type;
     881              :     double k;
     882              :     double eps;
     883              :     double nu_tilde;
     884              : } turb_node_bc_t;
     885              : 
     886              : /*
     887              :  * Resolve the BC at normalized position t on `edge`: the last segment covering
     888              :  * t, or the face type and face values. A profile is evaluated here and its
     889              :  * output checked, since a negative k or a zero epsilon would otherwise enter
     890              :  * the transport equations as if it were data.
     891              :  */
     892         1254 : static cfd_status_t resolve_node_bc(const ns_turbulence_bc_config_t* tbc, bc_edge_t edge,
     893              :                                     const turb_node_bc_t* face, int is_ke, double t,
     894              :                                     turb_node_bc_t* out) {
     895         1254 :     *out = *face;
     896         2266 :     for (size_t n = tbc->n_segments; n-- > 0;) {
     897         1287 :         const ns_turbulence_bc_segment_t* seg = &tbc->segments[n];
     898         1287 :         double position;
     899         1287 :         if (seg->edge != edge || !bc_edge_range_position(t, seg->start, seg->end, &position)) {
     900         1012 :             continue;
     901              :         }
     902          275 :         out->type = seg->type;
     903          275 :         if (seg->type != BC_TYPE_DIRICHLET) {
     904          275 :             return CFD_SUCCESS;
     905              :         }
     906          131 :         if (!seg->profile) {
     907           91 :             out->k = seg->k;
     908           91 :             out->eps = seg->eps;
     909           91 :             out->nu_tilde = seg->nu_tilde;
     910           91 :             return CFD_SUCCESS;
     911              :         }
     912           40 :         out->k = out->eps = out->nu_tilde = NAN;
     913           40 :         seg->profile(position, &out->k, &out->eps, &out->nu_tilde, seg->profile_user_data);
     914           50 :         const int ok = is_ke ? (is_nonnegative_finite(out->k) && isfinite(out->eps) &&
     915              :                                 out->eps > 0.0)
     916          315 :                              : is_nonnegative_finite(out->nu_tilde);
     917              :         if (!ok) {
     918            4 :             cfd_set_error(CFD_ERROR_INVALID,
     919              :                           "turbulence_apply_bcs: a segment profile returned a negative or "
     920              :                           "non-finite value (or eps <= 0 under k-epsilon)");
     921            4 :             return CFD_ERROR_INVALID;
     922              :         }
     923              :         return CFD_SUCCESS;
     924              :     }
     925              :     return CFD_SUCCESS;
     926              : }
     927              : 
     928              : /* Boundary node s of a face, its first interior neighbour, and its periodic
     929              :  * partner on the opposite face. */
     930        69532 : static void face_node_indices(bc_edge_t edge, size_t nx, size_t ny, size_t s,
     931              :                               size_t* idx, size_t* idx_int, size_t* idx_per) {
     932        69532 :     switch (edge) {
     933        17383 :         case BC_EDGE_LEFT:
     934        17383 :             *idx = s * nx;
     935        17383 :             *idx_int = *idx + 1;
     936        17383 :             *idx_per = s * nx + (nx - 2);
     937        17383 :             break;
     938        17383 :         case BC_EDGE_RIGHT:
     939        17383 :             *idx = s * nx + (nx - 1);
     940        17383 :             *idx_int = *idx - 1;
     941        17383 :             *idx_per = s * nx + 1;
     942        17383 :             break;
     943        17383 :         case BC_EDGE_BOTTOM:
     944        17383 :             *idx = s;
     945        17383 :             *idx_int = s + nx;
     946        17383 :             *idx_per = (ny - 2) * nx + s;
     947        17383 :             break;
     948        17383 :         default: /* BC_EDGE_TOP */
     949        17383 :             *idx = (ny - 1) * nx + s;
     950        17383 :             *idx_int = *idx - nx;
     951        17383 :             *idx_per = nx + s;
     952        17383 :             break;
     953              :     }
     954        69532 : }
     955              : 
     956              : /* Apply a resolved BC at one boundary node. y_p and u_tan (the wall-parallel
     957              :  * speed at idx_int) are read only by the wall function. */
     958        69532 : static void apply_node_bc(flow_field* field, const ns_solver_params_t* params,
     959              :                           const turb_node_bc_t* bc, int is_ke, size_t idx, size_t idx_int,
     960              :                           size_t idx_per, double y_p, double u_tan) {
     961        69532 :     if (bc->type == BC_TYPE_NOSLIP) {
     962        10522 :         apply_wall_function_node(field, params, idx, idx_int, y_p, u_tan);
     963        10522 :         return;
     964              :     }
     965        59010 :     if (is_ke) {
     966        44894 :         apply_scalar_face_bc(field->turb_k, bc->type, idx, idx_int, idx_per, bc->k);
     967        44894 :         apply_scalar_face_bc(field->turb_eps, bc->type, idx, idx_int, idx_per, bc->eps);
     968              :     } else {
     969        73126 :         apply_scalar_face_bc(field->turb_nu_tilde, bc->type, idx, idx_int, idx_per,
     970        14116 :                              bc->nu_tilde);
     971              :     }
     972        59010 :     if (bc->type == BC_TYPE_DIRICHLET) {
     973          191 :         set_dirichlet_nu_t(field, params, idx);
     974              :     } else {
     975        58819 :         apply_scalar_face_bc(field->nu_t, bc->type, idx, idx_int, idx_per, 0.0);
     976              :     }
     977              : }
     978              : 
     979              : /* Faces in application order: left and right first, then bottom and top, which
     980              :  * overwrite the corners. */
     981              : static const bc_edge_t face_order[4] = {BC_EDGE_LEFT, BC_EDGE_RIGHT, BC_EDGE_BOTTOM,
     982              :                                           BC_EDGE_TOP};
     983              : 
     984        15350 : static size_t face_node_count(bc_edge_t edge, size_t nx, size_t ny) {
     985        15350 :     return (edge == BC_EDGE_LEFT || edge == BC_EDGE_RIGHT) ? ny : nx;
     986              : }
     987              : 
     988              : /*
     989              :  * Resolve every boundary node of every face, in face_order, into nodes[]
     990              :  * (2 * (nx + ny) entries). This is where profiles are called and their output
     991              :  * checked, so a refusal happens before any field is written.
     992              :  */
     993           37 : static cfd_status_t resolve_all_faces(const ns_turbulence_bc_config_t* tbc, int is_ke,
     994              :                                       size_t nx, size_t ny, const turb_node_bc_t faces[4],
     995              :                                       turb_node_bc_t* nodes) {
     996           37 :     size_t offset = 0;
     997          175 :     for (int f = 0; f < 4; f++) {
     998          142 :         const size_t count = face_node_count(face_order[f], nx, ny);
     999         1392 :         for (size_t s = 0; s < count; s++) {
    1000         1254 :             cfd_status_t status = resolve_node_bc(tbc, face_order[f], &faces[f], is_ke,
    1001              :                                                   bc_edge_node_t(s, count),
    1002         1254 :                                                   &nodes[offset + s]);
    1003         1254 :             if (status != CFD_SUCCESS) {
    1004            4 :                 return status;
    1005              :             }
    1006              :         }
    1007          138 :         offset += count;
    1008              :     }
    1009              :     return CFD_SUCCESS;
    1010              : }
    1011              : 
    1012              : /* Apply one face node by node: node s takes nodes[s], or the face's own BC when
    1013              :  * nodes is NULL (no segments). Every node reads only its own interior
    1014              :  * neighbour, so the order along the face does not matter. */
    1015         7604 : static void apply_face_bcs(flow_field* field, const grid* grid,
    1016              :                            const ns_solver_params_t* params, bc_edge_t edge,
    1017              :                            const turb_node_bc_t* face, const turb_node_bc_t* nodes) {
    1018         7604 :     const size_t nx = field->nx;
    1019         7604 :     const size_t ny = field->ny;
    1020         7604 :     const int along_y = (edge == BC_EDGE_LEFT || edge == BC_EDGE_RIGHT);
    1021         7604 :     const size_t count = face_node_count(edge, nx, ny);
    1022         7604 :     const int is_ke = (params->turb_model == TURB_MODEL_K_EPSILON);
    1023              : 
    1024         7604 :     double y_p;
    1025         7604 :     switch (edge) {
    1026         1901 :         case BC_EDGE_LEFT: y_p = grid->x[1] - grid->x[0]; break;
    1027         1901 :         case BC_EDGE_RIGHT: y_p = grid->x[nx - 1] - grid->x[nx - 2]; break;
    1028         1901 :         case BC_EDGE_BOTTOM: y_p = grid->y[1] - grid->y[0]; break;
    1029         1901 :         default: y_p = grid->y[ny - 1] - grid->y[ny - 2]; break;
    1030              :     }
    1031              : 
    1032        77136 :     for (size_t s = 0; s < count; s++) {
    1033        69532 :         size_t idx, idx_int, idx_per;
    1034        69532 :         face_node_indices(edge, nx, ny, s, &idx, &idx_int, &idx_per);
    1035        69532 :         const double u_tan = along_y ? fabs(field->v[idx_int]) : fabs(field->u[idx_int]);
    1036        69532 :         apply_node_bc(field, params, nodes ? &nodes[s] : face, is_ke, idx, idx_int, idx_per,
    1037              :                       y_p, u_tan);
    1038              :     }
    1039         7604 : }
    1040              : 
    1041        28082 : cfd_status_t turbulence_apply_bcs(flow_field* field, const grid* grid,
    1042              :                                   const ns_solver_params_t* params) {
    1043        28082 :     if (!params) {
    1044            0 :         cfd_set_error(CFD_ERROR_INVALID,
    1045              :                       "turbulence_apply_bcs: params must be non-NULL");
    1046            0 :         return CFD_ERROR_INVALID;
    1047              :     }
    1048        28082 :     if (params->turb_model == TURB_MODEL_NONE) {
    1049              :         return CFD_SUCCESS;
    1050              :     }
    1051              : 
    1052         1923 :     cfd_status_t status = validate_turbulence_args(field, grid, params);
    1053         1923 :     if (status != CFD_SUCCESS) {
    1054              :         return status;
    1055              :     }
    1056              : 
    1057         1906 :     const ns_turbulence_bc_config_t* tbc = &params->turb_bc;
    1058              : 
    1059         1906 :     if (!is_supported_turb_bc(tbc->left) || !is_supported_turb_bc(tbc->right) ||
    1060         1906 :         !is_supported_turb_bc(tbc->bottom) || !is_supported_turb_bc(tbc->top) ||
    1061         1906 :         (tbc->wall_law != NS_WALL_LAW_LOG && tbc->wall_law != NS_WALL_LAW_SPALDING)) {
    1062            1 :         cfd_set_error(CFD_ERROR_INVALID,
    1063              :                       "turbulence_apply_bcs: unsupported turbulence BC type on a face "
    1064              :                       "(only PERIODIC, NEUMANN, DIRICHLET, NOSLIP are valid) or unknown "
    1065              :                       "turb_bc.wall_law");
    1066            1 :         return CFD_ERROR_INVALID;
    1067              :     }
    1068              : 
    1069              :     /* In face_order */
    1070         1905 :     const turb_node_bc_t faces[4] = {
    1071         1905 :         {tbc->left, tbc->k_values.left, tbc->eps_values.left, tbc->nu_tilde_values.left},
    1072         1905 :         {tbc->right, tbc->k_values.right, tbc->eps_values.right, tbc->nu_tilde_values.right},
    1073         1905 :         {tbc->bottom, tbc->k_values.bottom, tbc->eps_values.bottom,
    1074         1905 :          tbc->nu_tilde_values.bottom},
    1075         1905 :         {tbc->top, tbc->k_values.top, tbc->eps_values.top, tbc->nu_tilde_values.top},
    1076              :     };
    1077         1905 :     const size_t nx = field->nx;
    1078         1905 :     const size_t ny = field->ny;
    1079              : 
    1080              :     /* With segments, every node is resolved first -- profiles called, their
    1081              :      * output checked -- and only then is any field written, so a refusal leaves
    1082              :      * the fields as they were (the segments themselves were checked with the
    1083              :      * other arguments). One small allocation per call, 2 * (nx + ny) nodes, and
    1084              :      * none without segments. */
    1085         1905 :     turb_node_bc_t* nodes = NULL;
    1086         1905 :     if (tbc->n_segments > 0) {
    1087           37 :         nodes = (turb_node_bc_t*)cfd_calloc(2 * (nx + ny), sizeof(*nodes));
    1088           37 :         if (!nodes) {
    1089              :             return CFD_ERROR_NOMEM;
    1090              :         }
    1091           37 :         status = resolve_all_faces(tbc, params->turb_model == TURB_MODEL_K_EPSILON, nx, ny,
    1092              :                                    faces, nodes);
    1093           37 :         if (status != CFD_SUCCESS) {
    1094            4 :             cfd_free(nodes);
    1095            4 :             return status;
    1096              :         }
    1097              :     }
    1098              : 
    1099         1901 :     size_t offset = 0;
    1100         9505 :     for (int f = 0; f < 4; f++) {
    1101         7736 :         apply_face_bcs(field, grid, params, face_order[f], &faces[f],
    1102          132 :                        nodes ? &nodes[offset] : NULL);
    1103        11406 :         offset += face_node_count(face_order[f], nx, ny);
    1104              :     }
    1105         1901 :     cfd_free(nodes);
    1106         1901 :     return CFD_SUCCESS;
    1107              : }
    1108              : 
    1109           58 : cfd_status_t turbulence_bc_add_segment(ns_turbulence_bc_config_t* bc,
    1110              :                                        const ns_turbulence_bc_segment_t* segment) {
    1111           58 :     if (!bc || !segment) {
    1112            2 :         cfd_set_error(CFD_ERROR_INVALID,
    1113              :                       "turbulence_bc_add_segment: bc and segment must be non-NULL");
    1114            2 :         return CFD_ERROR_INVALID;
    1115              :     }
    1116           56 :     if (bc->n_segments >= NS_TURB_BC_MAX_SEGMENTS) {
    1117            1 :         cfd_set_error(CFD_ERROR_INVALID,
    1118              :                       "turbulence_bc_add_segment: no room; NS_TURB_BC_MAX_SEGMENTS "
    1119              :                       "segments are already set");
    1120            1 :         return CFD_ERROR_INVALID;
    1121              :     }
    1122           55 :     cfd_status_t status = validate_segment(segment, 0);
    1123           55 :     if (status != CFD_SUCCESS) {
    1124              :         return status;
    1125              :     }
    1126           43 :     bc->segments[bc->n_segments++] = *segment;
    1127           43 :     return CFD_SUCCESS;
    1128              : }
    1129              : 
    1130           44 : cfd_status_t turbulence_init_uniform(flow_field* field,
    1131              :                                      const ns_solver_params_t* params,
    1132              :                                      double k0, double eps0, double nu_tilde0) {
    1133           44 :     if (!field || !params) {
    1134            0 :         cfd_set_error(CFD_ERROR_INVALID,
    1135              :                       "turbulence_init_uniform: field and params must be non-NULL");
    1136            0 :         return CFD_ERROR_INVALID;
    1137              :     }
    1138           44 :     if (params->turb_model == TURB_MODEL_NONE) {
    1139              :         return CFD_SUCCESS;
    1140              :     }
    1141           44 :     if (!field->turb_k || !field->turb_eps || !field->turb_nu_tilde || !field->nu_t) {
    1142            0 :         cfd_set_error(CFD_ERROR_INVALID,
    1143              :                       "turbulence_init_uniform: missing turbulence fields");
    1144            0 :         return CFD_ERROR_INVALID;
    1145              :     }
    1146              : 
    1147           44 :     size_t total = field->nx * field->ny * field->nz;
    1148              : 
    1149           44 :     if (params->turb_model == TURB_MODEL_K_EPSILON) {
    1150           36 :         if (k0 < 0.0 || eps0 <= 0.0) {
    1151            0 :             cfd_set_error(CFD_ERROR_INVALID,
    1152              :                           "turbulence_init_uniform: k0 must be >= 0 and eps0 > 0");
    1153            0 :             return CFD_ERROR_INVALID;
    1154              :         }
    1155         3335 :         for (size_t n = 0; n < total; n++) {
    1156         3299 :             field->turb_k[n] = k0;
    1157         3299 :             field->turb_eps[n] = eps0;
    1158              :         }
    1159              :     } else {
    1160            8 :         if (nu_tilde0 < 0.0) {
    1161            0 :             cfd_set_error(CFD_ERROR_INVALID,
    1162              :                           "turbulence_init_uniform: nu_tilde0 must be >= 0");
    1163            0 :             return CFD_ERROR_INVALID;
    1164              :         }
    1165         1039 :         for (size_t n = 0; n < total; n++) {
    1166         1031 :             field->turb_nu_tilde[n] = nu_tilde0;
    1167              :         }
    1168              :     }
    1169              : 
    1170              :     /* No learned correction here: this is initialization, and the features it
    1171              :      * consumes (a strain rate, a turbulent Reynolds number) are meaningless
    1172              :      * before the flow has developed. The correction belongs to the per-step
    1173              :      * path only. */
    1174           44 :     turb_update_nu_t(field, params);
    1175           44 :     return CFD_SUCCESS;
    1176              : }
        

Generated by: LCOV version 2.0-1