LCOV - code coverage report
Current view: top level - solvers/navier_stokes - ns_convection_internal.h (source / functions) Coverage Total Hit
Test: coverage.info Lines: 94.9 % 78 74
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 8 8

            Line data    Source code
       1              : /**
       2              :  * @file ns_convection_internal.h
       3              :  * @brief Convection-scheme validation and scalar upwind kernels shared by the
       4              :  *        Navier-Stokes solvers.
       5              :  *
       6              :  * Every solver keeps its own central convective derivatives. When
       7              :  * `params->convection_scheme` is NS_CONVECTION_SCHEME_UPWIND it overwrites them
       8              :  * with the first-order upwind derivatives below, so the central path is left
       9              :  * exactly as it was. Divergence and pressure gradients stay central either way.
      10              :  */
      11              : #ifndef CFD_NS_CONVECTION_INTERNAL_H
      12              : #define CFD_NS_CONVECTION_INTERNAL_H
      13              : 
      14              : #include "../turbulence/turbulence_solver_internal.h"
      15              : 
      16              : #include "cfd/core/cfd_status.h"
      17              : #include "cfd/math/stencils.h"
      18              : #include "cfd/solvers/navier_stokes_solver.h"
      19              : 
      20              : #include <math.h>
      21              : #include <stddef.h>
      22              : 
      23              : /**
      24              :  * Validate the convection scheme at solver init.
      25              :  *
      26              :  * @param params                   Solver parameters (NULL means defaults)
      27              :  * @param backend_supports_upwind  Nonzero if the backend implements upwind
      28              :  * @return CFD_SUCCESS, CFD_ERROR_INVALID for an unknown scheme, or
      29              :  *         CFD_ERROR_UNSUPPORTED for upwind on a backend without it
      30              :  */
      31          613 : static inline cfd_status_t ns_check_convection_scheme(const ns_solver_params_t* params,
      32              :                                                       int backend_supports_upwind) {
      33          613 :     if (!params || params->convection_scheme == NS_CONVECTION_SCHEME_CENTRAL) {
      34              :         return CFD_SUCCESS;
      35              :     }
      36           93 :     if (params->convection_scheme != NS_CONVECTION_SCHEME_UPWIND) {
      37           12 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown convection scheme");
      38           12 :         return CFD_ERROR_INVALID;
      39              :     }
      40           81 :     if (!backend_supports_upwind) {
      41            0 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
      42              :                       "Upwind convection is only supported by the scalar, OpenMP and AVX2 solvers");
      43            0 :         return CFD_ERROR_UNSUPPORTED;
      44              :     }
      45              :     return CFD_SUCCESS;
      46              : }
      47              : 
      48              : /**
      49              :  * Validate the pressure walls at solver init.
      50              :  *
      51              :  * Default (all zero-gradient) walls are what every projection solver has always
      52              :  * used and always pass. A solver that cannot honour a prescribed face must say
      53              :  * so rather than solve the zero-gradient problem instead of the caller's -- and
      54              :  * that includes the time integrators, which solve no Poisson equation at all, so
      55              :  * a pressure BC configured on one would silently do nothing.
      56              :  *
      57              :  * @param params                      Solver parameters (NULL means defaults)
      58              :  * @param backend_supports_per_face   Nonzero if this solver honours params.pressure_bc
      59              :  * @return CFD_SUCCESS, CFD_ERROR_INVALID for a value outside poisson_wall_t, or
      60              :  *         CFD_ERROR_UNSUPPORTED
      61              :  */
      62          512 : static inline cfd_status_t ns_check_pressure_bc(const ns_solver_params_t* params,
      63              :                                                 int backend_supports_per_face) {
      64          512 :     if (!params) {
      65              :         return CFD_SUCCESS;
      66              :     }
      67          512 :     const poisson_walls_t* w = &params->pressure_bc;
      68              :     /* Range-checked first, as the two validators beside this one do: an
      69              :      * out-of-enum face is a caller error, not a backend limitation, and
      70              :      * reporting it as UNSUPPORTED sends the caller to try another backend that
      71              :      * will refuse the same garbage. A checkpoint reader casts these straight
      72              :      * from the file, so the value is not always one the compiler chose. */
      73          512 :     if (!poisson_walls_are_legal(w)) {
      74            8 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown poisson_wall_t in params.pressure_bc");
      75            8 :         return CFD_ERROR_INVALID;
      76              :     }
      77          504 :     if (poisson_walls_are_default(w)) {
      78              :         return CFD_SUCCESS;
      79              :     }
      80            8 :     if (!backend_supports_per_face) {
      81            6 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
      82              :                       "params.pressure_bc is honoured by the scalar, OpenMP and AVX2 "
      83              :                       "projection solvers only");
      84            6 :         return CFD_ERROR_UNSUPPORTED;
      85              :     }
      86              :     return CFD_SUCCESS;
      87              : }
      88              : 
      89              : /**
      90              :  * Validate the pressure-solver selection at solver init.
      91              :  *
      92              :  * The analogue of ns_check_pressure_bc, and missing until now, which is why
      93              :  * NS_PRESSURE_SOLVER_MULTIGRID on rk4 or explicit_euler was accepted and did
      94              :  * nothing: those solvers run no Poisson solve at all.
      95              :  *
      96              :  * @param params                          Solver parameters (NULL means defaults)
      97              :  * @param backend_supports_pressure_solver Nonzero if this solver runs a pressure
      98              :  *                                        solve it can choose the method for
      99              :  * @return CFD_SUCCESS, CFD_ERROR_INVALID for an unknown value, or
     100              :  *         CFD_ERROR_UNSUPPORTED
     101              :  */
     102          498 : static inline cfd_status_t ns_check_pressure_solver(const ns_solver_params_t* params,
     103              :                                                     int backend_supports_pressure_solver) {
     104          498 :     if (!params || params->pressure_solver == NS_PRESSURE_SOLVER_DEFAULT) {
     105              :         return CFD_SUCCESS;
     106              :     }
     107           34 :     if (params->pressure_solver != NS_PRESSURE_SOLVER_MULTIGRID &&
     108              :         params->pressure_solver != NS_PRESSURE_SOLVER_PCG_MG) {
     109            1 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown ns_solver_params_t.pressure_solver");
     110            1 :         return CFD_ERROR_INVALID;
     111              :     }
     112           33 :     if (!backend_supports_pressure_solver) {
     113           12 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     114              :                       "params.pressure_solver is honoured by the scalar and OpenMP "
     115              :                       "projection solvers only");
     116           12 :         return CFD_ERROR_UNSUPPORTED;
     117              :     }
     118              :     return CFD_SUCCESS;
     119              : }
     120              : 
     121              : /**
     122              :  * Validate the viscous-scheme selection.
     123              :  *
     124              :  * Called from the solver_init / solver_step / solver_solve wrappers with the
     125              :  * solver's capability flags rather than from each backend's init: one check then
     126              :  * covers every solver, the CUDA ones included, and also catches a scheme set on
     127              :  * params after init, which would otherwise run explicit silently at a dt the
     128              :  * caller chose because it no longer had to be.
     129              :  *
     130              :  * @param params                   Solver parameters (NULL means defaults)
     131              :  * @param supports_implicit        Nonzero if the solver has
     132              :  *                                 NS_SOLVER_CAP_IMPLICIT_VISCOUS
     133              :  * @return CFD_SUCCESS, CFD_ERROR_INVALID for an unknown value, or
     134              :  *         CFD_ERROR_UNSUPPORTED
     135              :  */
     136        17827 : static inline cfd_status_t ns_check_viscous_scheme(const ns_solver_params_t* params,
     137              :                                                    int supports_implicit) {
     138        17827 :     if (!params || params->viscous_scheme == NS_VISCOUS_SCHEME_EXPLICIT) {
     139              :         return CFD_SUCCESS;
     140              :     }
     141          856 :     if (params->viscous_scheme != NS_VISCOUS_SCHEME_BACKWARD_EULER &&
     142              :         params->viscous_scheme != NS_VISCOUS_SCHEME_CRANK_NICOLSON) {
     143           12 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown ns_solver_params_t.viscous_scheme");
     144           12 :         return CFD_ERROR_INVALID;
     145              :     }
     146          844 :     if (!supports_implicit) {
     147           32 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     148              :                       "An implicit params.viscous_scheme is honoured by the scalar and "
     149              :                       "OpenMP projection solvers only");
     150           32 :         return CFD_ERROR_UNSUPPORTED;
     151              :     }
     152              :     return CFD_SUCCESS;
     153              : }
     154              : 
     155              : /**
     156              :  * Validate the time step.
     157              :  *
     158              :  * Every step and solve entry point takes dt from params, and none can do
     159              :  * anything sensible with one that is not finite and positive: zero stalls the
     160              :  * clock (and the projection's rho/dt pressure scaling divides by it), a negative
     161              :  * step runs time backwards, and NaN poisons the field. Called from the
     162              :  * solver_step / solver_solve dispatchers and from each exported GPU entry point,
     163              :  * which bypass them.
     164              :  *
     165              :  * @param params  Solver parameters (NULL is left to the caller's own check)
     166              :  * @return CFD_SUCCESS, or CFD_ERROR_INVALID
     167              :  */
     168        17170 : static inline cfd_status_t ns_check_dt(const ns_solver_params_t* params) {
     169        17170 :     if (params && !(isfinite(params->dt) && params->dt > 0.0)) {
     170           72 :         cfd_set_error(CFD_ERROR_INVALID, "params.dt must be finite and positive");
     171           72 :         return CFD_ERROR_INVALID;
     172              :     }
     173              :     return CFD_SUCCESS;
     174              : }
     175              : 
     176              : /**
     177              :  * Validate the turbulence model at solver init.
     178              :  *
     179              :  * The GPU backends have no RANS kernels and were rejecting this per step, from
     180              :  * inside solve_projection_method_gpu and its siblings. That is late: a caller
     181              :  * gets the refusal after init has reported success, which is the one place they
     182              :  * could still have chosen a different backend.
     183              :  *
     184              :  * @param params                       Solver parameters (NULL means defaults)
     185              :  * @param backend_supports_turbulence  Nonzero if this backend implements RANS
     186              :  * @return CFD_SUCCESS, CFD_ERROR_INVALID for an unknown model or a turbulence BC
     187              :  *         segment turb_check_segments() refuses, or CFD_ERROR_UNSUPPORTED
     188              :  */
     189          545 : static inline cfd_status_t ns_check_turbulence_model(const ns_solver_params_t* params,
     190              :                                                      int backend_supports_turbulence) {
     191          545 :     if (!params) {
     192              :         return CFD_SUCCESS;
     193              :     }
     194              :     /* Before the TURB_MODEL_NONE exit: a closure set with no turbulence model
     195              :      * is exactly the configuration that used to run as a silent no-op. */
     196          545 :     cfd_status_t closure_status = turb_check_closure_config(params);
     197          545 :     if (closure_status != CFD_SUCCESS) {
     198              :         return closure_status;
     199              :     }
     200          538 :     if (params->turb_model == TURB_MODEL_NONE) {
     201              :         return CFD_SUCCESS;
     202              :     }
     203           25 :     if (params->turb_model != TURB_MODEL_K_EPSILON &&
     204              :         params->turb_model != TURB_MODEL_SPALART_ALLMARAS) {
     205            1 :         cfd_set_error(CFD_ERROR_INVALID, "Unknown ns_solver_params_t.turb_model");
     206            1 :         return CFD_ERROR_INVALID;
     207              :     }
     208           24 :     if (!backend_supports_turbulence) {
     209            0 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     210              :                       "RANS turbulence models are implemented on the scalar, OpenMP and "
     211              :                       "AVX2 solvers only; the GPU backends have no RANS kernels");
     212            0 :         return CFD_ERROR_UNSUPPORTED;
     213              :     }
     214              :     /* At init as well as per step: a bad segment found by the first step's
     215              :      * turbulence validation is found after the velocity has already advanced.
     216              :      * A segment whose profile a checkpoint could not store is accepted here --
     217              :      * load_simulation_from_checkpoint() initializes the solver before its caller
     218              :      * can re-attach the profile -- and refused by ns_check_turbulence_segments()
     219              :      * on every step until it is. */
     220           24 :     return turb_check_segments(params, 1);
     221              : }
     222              : 
     223              : /**
     224              :  * Per-step check of the turbulence BC segments, for the solver_step() and
     225              :  * solver_solve() dispatchers: everything solver init accepted may have changed
     226              :  * since, and a segment whose profile has not been re-attached after a checkpoint
     227              :  * load must be refused before any field moves, not when the turbulence step
     228              :  * runs after the velocity has already advanced.
     229              :  *
     230              :  * @return CFD_SUCCESS (always, without turbulence) or CFD_ERROR_INVALID
     231              :  */
     232        17098 : static inline cfd_status_t ns_check_turbulence_segments(const ns_solver_params_t* params) {
     233        17098 :     if (!params || params->turb_model == TURB_MODEL_NONE) {
     234              :         return CFD_SUCCESS;
     235              :     }
     236           44 :     return turb_check_segments(params, 0);
     237              : }
     238              : 
     239              : /** Convective first derivatives of (u, v, w) at one grid point */
     240              : typedef struct {
     241              :     double du_dx, du_dy, du_dz;
     242              :     double dv_dx, dv_dy, dv_dz;
     243              :     double dw_dx, dw_dy, dw_dz;
     244              : } ns_conv_derivs_t;
     245              : 
     246              : /**
     247              :  * First-order upwind convective derivatives of (u, v, w) at point idx, each
     248              :  * advected by the point velocity (u[idx], v[idx], w[idx]).
     249              :  *
     250              :  * @param il,ir,jd,ju,kd,ku  Neighbor indices (ghost-cell or periodic, as the
     251              :  *                           calling kernel uses for its central stencil)
     252              :  * @param dx,dy              Grid spacing at the point (must be > 0)
     253              :  * @param inv_dz             1/dz, or 0.0 when the z-axis is inactive
     254              :  */
     255       168876 : static inline void ns_upwind_conv_derivs(const double* u, const double* v, const double* w,
     256              :                                          size_t idx, size_t il, size_t ir,
     257              :                                          size_t jd, size_t ju, size_t kd, size_t ku,
     258              :                                          double dx, double dy, double inv_dz,
     259              :                                          ns_conv_derivs_t* cd) {
     260       168876 :     const double u_c = u[idx];
     261       168876 :     const double v_c = v[idx];
     262       168876 :     const double w_c = w[idx];
     263              : 
     264       168876 :     cd->du_dx = stencil_upwind_deriv_x(u[ir], u_c, u[il], dx, u_c);
     265       168876 :     cd->du_dy = stencil_upwind_deriv_y(u[ju], u_c, u[jd], dy, v_c);
     266       168876 :     cd->du_dz = stencil_upwind_diff(u[ku], u_c, u[kd], w_c) * inv_dz;
     267              : 
     268       168876 :     cd->dv_dx = stencil_upwind_deriv_x(v[ir], v_c, v[il], dx, u_c);
     269       168876 :     cd->dv_dy = stencil_upwind_deriv_y(v[ju], v_c, v[jd], dy, v_c);
     270       168876 :     cd->dv_dz = stencil_upwind_diff(v[ku], v_c, v[kd], w_c) * inv_dz;
     271              : 
     272       168876 :     cd->dw_dx = stencil_upwind_deriv_x(w[ir], w_c, w[il], dx, u_c);
     273       168876 :     cd->dw_dy = stencil_upwind_deriv_y(w[ju], w_c, w[jd], dy, v_c);
     274       168876 :     cd->dw_dz = stencil_upwind_diff(w[ku], w_c, w[kd], w_c) * inv_dz;
     275       168876 : }
     276              : 
     277              : /** Clamp every convective derivative to [-limit, limit] */
     278       143256 : static inline void ns_clamp_conv_derivs(ns_conv_derivs_t* cd, double limit) {
     279       143256 :     cd->du_dx = fmax(-limit, fmin(limit, cd->du_dx));
     280       143256 :     cd->du_dy = fmax(-limit, fmin(limit, cd->du_dy));
     281       143256 :     cd->du_dz = fmax(-limit, fmin(limit, cd->du_dz));
     282       143256 :     cd->dv_dx = fmax(-limit, fmin(limit, cd->dv_dx));
     283       143256 :     cd->dv_dy = fmax(-limit, fmin(limit, cd->dv_dy));
     284       143256 :     cd->dv_dz = fmax(-limit, fmin(limit, cd->dv_dz));
     285       143256 :     cd->dw_dx = fmax(-limit, fmin(limit, cd->dw_dx));
     286       143256 :     cd->dw_dy = fmax(-limit, fmin(limit, cd->dw_dy));
     287       143256 :     cd->dw_dz = fmax(-limit, fmin(limit, cd->dw_dz));
     288       143256 : }
     289              : 
     290              : #endif /* CFD_NS_CONVECTION_INTERNAL_H */
        

Generated by: LCOV version 2.0-1