Line data Source code
1 : /**
2 : * @file energy_solver.c
3 : * @brief Scalar CPU implementation of the energy equation solver
4 : *
5 : * Solves: dT/dt + u*nabla(T) = alpha * nabla^2(T) + Q
6 : * using explicit Euler time integration, central differences for diffusion, and
7 : * central or first-order upwind differences for advection
8 : * (params->convection_scheme).
9 : *
10 : * Branch-free 3D: when nz==1, stride_z=0 and inv_2dz/inv_dz2=0.0 cause all
11 : * z-terms to vanish, producing identical results to a 2D code path.
12 : */
13 :
14 : #include "cfd/solvers/energy_solver.h"
15 : #include "../energy_solver_internal.h"
16 :
17 : #include "cfd/core/indexing.h"
18 : #include "cfd/core/memory.h"
19 : #include "cfd/math/stencils.h"
20 :
21 : #include <math.h>
22 : #include <string.h>
23 :
24 25294 : cfd_status_t energy_step_explicit_with_workspace(
25 : flow_field* field, const grid* grid,
26 : const ns_solver_params_t* params,
27 : double dt, double time,
28 : double* T_workspace, size_t workspace_size) {
29 25294 : if (!field || !grid || !params) {
30 0 : cfd_set_error(CFD_ERROR_INVALID,
31 : "energy_solver: field, grid, and params must be non-NULL");
32 0 : return CFD_ERROR_INVALID;
33 : }
34 25294 : if (!field->T) {
35 0 : cfd_set_error(CFD_ERROR_INVALID,
36 : "energy_solver: missing temperature field");
37 0 : return CFD_ERROR_INVALID;
38 : }
39 :
40 : /* Skip when energy equation is disabled */
41 25294 : if (params->alpha <= 0.0) {
42 : return CFD_SUCCESS;
43 : }
44 :
45 8074 : size_t nx = field->nx;
46 8074 : size_t ny = field->ny;
47 8074 : size_t nz = field->nz;
48 :
49 8074 : if (!grid->dx || !grid->dy || nx < 3 || ny < 3) {
50 0 : cfd_set_error(CFD_ERROR_INVALID,
51 : "energy_solver: grid too small or missing dx/dy");
52 0 : return CFD_ERROR_INVALID;
53 : }
54 8074 : size_t plane = nx * ny;
55 8074 : size_t total = plane * nz;
56 8074 : double alpha = params->alpha;
57 :
58 : /* Validate uniform spacing (central-difference stencil assumes it) */
59 8074 : const double dx0 = grid->dx[0];
60 8074 : const double dy0 = grid->dy[0];
61 : {
62 8074 : const double tol_x = 1e-12 * fmax(1.0, fabs(dx0));
63 312000 : for (size_t i = 1; i < nx - 1; i++) {
64 303926 : if (fabs(grid->dx[i] - dx0) > tol_x) {
65 0 : cfd_set_error(CFD_ERROR_UNSUPPORTED,
66 : "energy_solver: non-uniform dx not supported");
67 0 : return CFD_ERROR_UNSUPPORTED;
68 : }
69 : }
70 8074 : const double tol_y = 1e-12 * fmax(1.0, fabs(dy0));
71 307320 : for (size_t j = 1; j < ny - 1; j++) {
72 299246 : if (fabs(grid->dy[j] - dy0) > tol_y) {
73 0 : cfd_set_error(CFD_ERROR_UNSUPPORTED,
74 : "energy_solver: non-uniform dy not supported");
75 0 : return CFD_ERROR_UNSUPPORTED;
76 : }
77 : }
78 : }
79 8074 : if (nz > 1) {
80 0 : if (!grid->dz) {
81 0 : cfd_set_error(CFD_ERROR_INVALID,
82 : "energy_solver: missing dz for 3D energy solve");
83 0 : return CFD_ERROR_INVALID;
84 : }
85 0 : const double dz0 = grid->dz[0];
86 0 : const double tol_z = 1e-12 * fmax(1.0, fabs(dz0));
87 0 : for (size_t k = 1; k < nz - 1; k++) {
88 0 : if (fabs(grid->dz[k] - dz0) > tol_z) {
89 0 : cfd_set_error(CFD_ERROR_UNSUPPORTED,
90 : "energy_solver: non-uniform dz not supported");
91 0 : return CFD_ERROR_UNSUPPORTED;
92 : }
93 : }
94 : }
95 :
96 : /* Precomputed constants for uniform-grid stencil */
97 8074 : double inv_2dx = 1.0 / (2.0 * dx0);
98 8074 : double inv_2dy = 1.0 / (2.0 * dy0);
99 8074 : double inv_dx2 = 1.0 / (dx0 * dx0);
100 8074 : double inv_dy2 = 1.0 / (dy0 * dy0);
101 :
102 : /* Branch-free 3D constants */
103 8074 : size_t stride_z = (nz > 1) ? plane : 0;
104 8074 : size_t k_start = (nz > 1) ? 1 : 0;
105 8074 : size_t k_end = (nz > 1) ? (nz - 1) : 1;
106 8074 : double inv_2dz = (nz > 1 && grid->dz) ? 1.0 / (2.0 * grid->dz[0]) : 0.0;
107 0 : double inv_dz2 = (nz > 1 && grid->dz) ? 1.0 / (grid->dz[0] * grid->dz[0]) : 0.0;
108 8074 : double inv_dz = 2.0 * inv_2dz;
109 8074 : const int upwind = (params->convection_scheme == NS_CONVECTION_SCHEME_UPWIND);
110 :
111 : /* Use caller's workspace or allocate internally */
112 8074 : int owns_buffer = 0;
113 8074 : double* T_new;
114 8074 : if (T_workspace && workspace_size >= total) {
115 : T_new = T_workspace;
116 : } else {
117 280 : T_new = (double*)cfd_calloc(total, sizeof(double));
118 280 : if (!T_new) {
119 : return CFD_ERROR_NOMEM;
120 : }
121 : owns_buffer = 1;
122 : }
123 8074 : memcpy(T_new, field->T, total * sizeof(double));
124 :
125 16148 : for (size_t k = k_start; k < k_end; k++) {
126 307320 : for (size_t j = 1; j < ny - 1; j++) {
127 11864320 : for (size_t i = 1; i < nx - 1; i++) {
128 11565074 : size_t idx = k * stride_z + IDX_2D(i, j, nx);
129 :
130 11565074 : double T_c = field->T[idx];
131 11565074 : double u_c = field->u[idx];
132 11565074 : double v_c = field->v[idx];
133 11565074 : double w_c = field->w[idx];
134 :
135 : /* Advection: u * dT/dx + v * dT/dy + w * dT/dz, with central or
136 : * first-order upwind derivatives */
137 11565074 : double dT_dx, dT_dy, dT_dz;
138 11565074 : if (upwind) {
139 11540 : dT_dx = stencil_upwind_deriv_x(field->T[idx + 1], T_c, field->T[idx - 1],
140 : dx0, u_c);
141 11540 : dT_dy = stencil_upwind_deriv_y(field->T[idx + nx], T_c, field->T[idx - nx],
142 : dy0, v_c);
143 11540 : dT_dz = stencil_upwind_diff(field->T[idx + stride_z], T_c,
144 11540 : field->T[idx - stride_z], w_c) * inv_dz;
145 : } else {
146 11553534 : dT_dx = (field->T[idx + 1] - field->T[idx - 1]) * inv_2dx;
147 11553534 : dT_dy = (field->T[idx + nx] - field->T[idx - nx]) * inv_2dy;
148 11553534 : dT_dz = (field->T[idx + stride_z] - field->T[idx - stride_z]) * inv_2dz;
149 : }
150 :
151 11565074 : double advection = u_c * dT_dx + v_c * dT_dy + w_c * dT_dz;
152 :
153 : /* Diffusion: alpha * (d2T/dx2 + d2T/dy2 + d2T/dz2) */
154 11565074 : double d2T_dx2 = (field->T[idx + 1] - 2.0 * T_c + field->T[idx - 1]) * inv_dx2;
155 11565074 : double d2T_dy2 = (field->T[idx + nx] - 2.0 * T_c + field->T[idx - nx]) * inv_dy2;
156 11565074 : double d2T_dz2 = (field->T[idx + stride_z] - 2.0 * T_c +
157 11565074 : field->T[idx - stride_z]) * inv_dz2;
158 :
159 11565074 : double diffusion = alpha * (d2T_dx2 + d2T_dy2 + d2T_dz2);
160 :
161 : /* Heat source term */
162 11565074 : double Q = 0.0;
163 11565074 : if (params->heat_source_func) {
164 11250 : double x = grid->x[i];
165 11250 : double y = grid->y[j];
166 11250 : double z = (nz > 1 && grid->z) ? grid->z[k] : 0.0;
167 11250 : Q = params->heat_source_func(x, y, z, time,
168 11250 : params->heat_source_context);
169 : }
170 :
171 : /* Explicit Euler update */
172 11565074 : double dT = dt * (-advection + diffusion + Q);
173 11565074 : T_new[idx] = T_c + dT;
174 : }
175 : }
176 : }
177 :
178 : /* Check for NaN/Inf */
179 12811788 : for (size_t n = 0; n < total; n++) {
180 12803714 : if (!isfinite(T_new[n])) {
181 0 : cfd_set_error(CFD_ERROR_DIVERGED,
182 : "NaN/Inf detected in energy_step_explicit");
183 0 : if (owns_buffer) cfd_free(T_new);
184 0 : return CFD_ERROR_DIVERGED;
185 : }
186 : }
187 :
188 8074 : memcpy(field->T, T_new, total * sizeof(double));
189 8074 : if (owns_buffer) cfd_free(T_new);
190 :
191 : return CFD_SUCCESS;
192 : }
193 :
194 281 : cfd_status_t energy_step_explicit(flow_field* field, const grid* grid,
195 : const ns_solver_params_t* params,
196 : double dt, double time) {
197 281 : return energy_step_explicit_with_workspace(field, grid, params,
198 : dt, time, NULL, 0);
199 : }
200 :
201 161191124 : void energy_compute_buoyancy(double T_local, const ns_solver_params_t* params,
202 : double* source_u, double* source_v,
203 : double* source_w) {
204 161191124 : if (params->beta == 0.0) {
205 : return;
206 : }
207 :
208 11428796 : double dT = T_local - params->T_ref;
209 11428796 : *source_u += -params->beta * dT * params->gravity[0];
210 11428796 : *source_v += -params->beta * dT * params->gravity[1];
211 11428796 : *source_w += -params->beta * dT * params->gravity[2];
212 : }
213 :
214 : /* A face may only request a thermal BC type the energy solver implements. */
215 : static int is_supported_thermal_bc(bc_type_t type) {
216 : return type == BC_TYPE_PERIODIC || type == BC_TYPE_NEUMANN ||
217 : type == BC_TYPE_DIRICHLET;
218 : }
219 :
220 26207 : cfd_status_t energy_apply_thermal_bcs(flow_field* field,
221 : const ns_solver_params_t* params) {
222 26207 : if (!field || !params || !field->T) {
223 2 : cfd_set_error(CFD_ERROR_INVALID,
224 : "energy_apply_thermal_bcs: field, params, and T must be non-NULL");
225 2 : return CFD_ERROR_INVALID;
226 : }
227 : /* alpha <= 0 means the energy equation is disabled: a legitimate no-op. */
228 26205 : if (params->alpha <= 0.0) return CFD_SUCCESS;
229 :
230 7919 : const ns_thermal_bc_config_t* tbc = ¶ms->thermal_bc;
231 :
232 7919 : size_t nx = field->nx;
233 7919 : size_t ny = field->ny;
234 7919 : size_t nz = field->nz;
235 7919 : size_t plane = nx * ny;
236 :
237 : /* Reject unsupported per-face BC types so misconfiguration (e.g. an
238 : * accidental BC_TYPE_NOSLIP/INLET) fails loudly instead of silently
239 : * leaving that face unchanged. Front/back only apply in 3D. */
240 7919 : if (!is_supported_thermal_bc(tbc->left) || !is_supported_thermal_bc(tbc->right) ||
241 7918 : !is_supported_thermal_bc(tbc->bottom) || !is_supported_thermal_bc(tbc->top) ||
242 1 : (nz > 1 && (!is_supported_thermal_bc(tbc->front) ||
243 1 : !is_supported_thermal_bc(tbc->back)))) {
244 1 : cfd_set_error(CFD_ERROR_INVALID,
245 : "energy_apply_thermal_bcs: unsupported thermal BC type on a face "
246 : "(only PERIODIC, NEUMANN, DIRICHLET are valid)");
247 1 : return CFD_ERROR_INVALID;
248 : }
249 :
250 : /* A requested BC must fit the grid: Neumann needs >= 2 cells, Periodic >= 3. */
251 7918 : if (((tbc->left == BC_TYPE_NEUMANN || tbc->right == BC_TYPE_NEUMANN) && nx < 2) ||
252 7918 : ((tbc->bottom == BC_TYPE_NEUMANN || tbc->top == BC_TYPE_NEUMANN) && ny < 2) ||
253 7918 : ((tbc->left == BC_TYPE_PERIODIC || tbc->right == BC_TYPE_PERIODIC) && nx < 3) ||
254 7918 : ((tbc->bottom == BC_TYPE_PERIODIC || tbc->top == BC_TYPE_PERIODIC) && ny < 3) ||
255 7918 : (nz > 1 && (tbc->back == BC_TYPE_NEUMANN || tbc->front == BC_TYPE_NEUMANN) && nz < 2) ||
256 1 : (nz > 1 && (tbc->back == BC_TYPE_PERIODIC || tbc->front == BC_TYPE_PERIODIC) && nz < 3)) {
257 0 : cfd_set_error(CFD_ERROR_INVALID,
258 : "energy_apply_thermal_bcs: grid too small for the requested thermal BC type");
259 0 : return CFD_ERROR_INVALID;
260 : }
261 :
262 : /* Left face (i=0) */
263 15840 : for (size_t k = 0; k < nz; k++) {
264 7922 : size_t base = k * plane;
265 319656 : for (size_t j = 0; j < ny; j++) {
266 311734 : size_t idx = base + j * nx;
267 311734 : if (tbc->left == BC_TYPE_DIRICHLET)
268 311690 : field->T[idx] = tbc->dirichlet_values.left;
269 44 : else if (tbc->left == BC_TYPE_NEUMANN)
270 0 : field->T[idx] = field->T[idx + 1];
271 44 : else if (tbc->left == BC_TYPE_PERIODIC)
272 44 : field->T[idx] = field->T[base + j * nx + (nx - 2)];
273 : }
274 : }
275 :
276 : /* Right face (i=nx-1) */
277 15840 : for (size_t k = 0; k < nz; k++) {
278 7922 : size_t base = k * plane;
279 319656 : for (size_t j = 0; j < ny; j++) {
280 311734 : size_t idx = base + j * nx + (nx - 1);
281 311734 : if (tbc->right == BC_TYPE_DIRICHLET)
282 311685 : field->T[idx] = tbc->dirichlet_values.right;
283 49 : else if (tbc->right == BC_TYPE_NEUMANN)
284 0 : field->T[idx] = field->T[idx - 1];
285 49 : else if (tbc->right == BC_TYPE_PERIODIC)
286 49 : field->T[idx] = field->T[base + j * nx + 1];
287 : }
288 : }
289 :
290 : /* Bottom face (j=0) — runs after left/right, overwrites shared corners */
291 15840 : for (size_t k = 0; k < nz; k++) {
292 7922 : size_t base = k * plane;
293 319656 : for (size_t i = 0; i < nx; i++) {
294 311734 : size_t idx = base + i;
295 311734 : if (tbc->bottom == BC_TYPE_DIRICHLET)
296 35 : field->T[idx] = tbc->dirichlet_values.bottom;
297 311699 : else if (tbc->bottom == BC_TYPE_NEUMANN)
298 311685 : field->T[idx] = field->T[idx + nx];
299 14 : else if (tbc->bottom == BC_TYPE_PERIODIC)
300 14 : field->T[idx] = field->T[base + (ny - 2) * nx + i];
301 : }
302 : }
303 :
304 : /* Top face (j=ny-1) */
305 15840 : for (size_t k = 0; k < nz; k++) {
306 7922 : size_t base = k * plane;
307 319656 : for (size_t i = 0; i < nx; i++) {
308 311734 : size_t idx = base + (ny - 1) * nx + i;
309 311734 : if (tbc->top == BC_TYPE_DIRICHLET)
310 35 : field->T[idx] = tbc->dirichlet_values.top;
311 311699 : else if (tbc->top == BC_TYPE_NEUMANN)
312 311685 : field->T[idx] = field->T[idx - nx];
313 14 : else if (tbc->top == BC_TYPE_PERIODIC)
314 14 : field->T[idx] = field->T[base + nx + i];
315 : }
316 : }
317 :
318 : /* Back face (k=0) — only when nz > 1 */
319 7918 : if (nz > 1) {
320 8 : for (size_t j = 0; j < ny; j++) {
321 56 : for (size_t i = 0; i < nx; i++) {
322 49 : size_t idx = j * nx + i;
323 49 : if (tbc->back == BC_TYPE_DIRICHLET)
324 49 : field->T[idx] = tbc->dirichlet_values.back;
325 0 : else if (tbc->back == BC_TYPE_NEUMANN)
326 0 : field->T[idx] = field->T[plane + idx];
327 0 : else if (tbc->back == BC_TYPE_PERIODIC)
328 0 : field->T[idx] = field->T[(nz - 2) * plane + idx];
329 : }
330 : }
331 : }
332 :
333 : /* Front face (k=nz-1) — only when nz > 1 */
334 1 : if (nz > 1) {
335 1 : size_t front_base = (nz - 1) * plane;
336 8 : for (size_t j = 0; j < ny; j++) {
337 56 : for (size_t i = 0; i < nx; i++) {
338 49 : size_t off = j * nx + i;
339 49 : if (tbc->front == BC_TYPE_DIRICHLET)
340 0 : field->T[front_base + off] = tbc->dirichlet_values.front;
341 49 : else if (tbc->front == BC_TYPE_NEUMANN)
342 49 : field->T[front_base + off] = field->T[(nz - 2) * plane + off];
343 0 : else if (tbc->front == BC_TYPE_PERIODIC)
344 0 : field->T[front_base + off] = field->T[plane + off];
345 : }
346 : }
347 : }
348 :
349 : return CFD_SUCCESS;
350 : }
|