LCOV - code coverage report
Current view: top level - solvers/energy/cpu - energy_solver.c (source / functions) Coverage Total Hit
Test: coverage.info Lines: 81.9 % 188 154
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 4 4

            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 = &params->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              : }
        

Generated by: LCOV version 2.0-1