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 = ¶ms->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 = ¶ms->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 : }
|