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