LCOV - code coverage report
Current view: top level - solvers/navier_stokes - ns_pressure_internal.h (source / functions) Coverage Total Hit
Test: coverage.info Lines: 81.6 % 76 62
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 3 3

            Line data    Source code
       1              : /**
       2              :  * @file ns_pressure_internal.h
       3              :  * @brief The pressure Poisson solver a projection solver owns.
       4              :  *
       5              :  * A projection step solves the pressure Poisson equation once per inner
       6              :  * iteration. Building a solver for that each time would rebuild a whole
       7              :  * multigrid hierarchy per step, so each projection solver owns one across its
       8              :  * lifetime, created at init and destroyed with the solver.
       9              :  *
      10              :  * Both functions live here rather than in each backend because the mapping from
      11              :  * ns_solver_params_t to a Poisson configuration is the same question every
      12              :  * projection backend asks, and three copies of it drifted apart once already.
      13              :  */
      14              : #ifndef CFD_NS_PRESSURE_INTERNAL_H
      15              : #define CFD_NS_PRESSURE_INTERNAL_H
      16              : 
      17              : #include "cfd/core/cfd_status.h"
      18              : #include "cfd/core/logging.h"
      19              : #include "cfd/solvers/navier_stokes_solver.h"
      20              : #include "cfd/solvers/poisson_solver.h"
      21              : 
      22              : #include "../linear/multigrid_internal.h"  /* mg_is_pow2_plus1 */
      23              : 
      24              : #include <string.h>
      25              : 
      26              : /**
      27              :  * The Poisson configuration a projection solver should use.
      28              :  *
      29              :  * `backend` is the backend that projection runs on: the OpenMP projection must
      30              :  * get OpenMP multigrid and never the scalar one, which is why the caller passes
      31              :  * it rather than letting AUTO decide.
      32              :  *
      33              :  * Returns CFD_ERROR_INVALID for an unknown pressure_solver value.
      34              :  */
      35        13649 : static inline cfd_status_t ns_pressure_config(const ns_solver_params_t* params,
      36              :                                               poisson_solver_backend_t backend,
      37              :                                               poisson_solver_config_t* out) {
      38        40841 :     ns_pressure_solver_t choice =
      39        13649 :         params ? params->pressure_solver : NS_PRESSURE_SOLVER_DEFAULT;
      40              : 
      41        13649 :     switch (choice) {
      42        13543 :         case NS_PRESSURE_SOLVER_DEFAULT:
      43        13543 :             *out = poisson_solver_config_preset(POISSON_PRESET_DEFAULT);
      44        13543 :             break;
      45           56 :         case NS_PRESSURE_SOLVER_MULTIGRID:
      46           56 :             *out = poisson_solver_config_preset(POISSON_PRESET_MULTIGRID);
      47           56 :             break;
      48           50 :         case NS_PRESSURE_SOLVER_PCG_MG:
      49           50 :             *out = poisson_solver_config_preset(POISSON_PRESET_MULTIGRID_PCG);
      50           50 :             break;
      51            0 :         default:
      52            0 :             cfd_set_error(CFD_ERROR_INVALID, "Unknown ns_solver_params_t.pressure_solver");
      53            0 :             return CFD_ERROR_INVALID;
      54              :     }
      55              : 
      56        13649 :     out->backend = backend;
      57        13649 :     if (params) {
      58        13649 :         out->params.walls = params->pressure_bc;
      59              :     }
      60              :     return CFD_SUCCESS;
      61              : }
      62              : 
      63              : /**
      64              :  * Make *slot a solver matching cfg on this grid, building or rebuilding it.
      65              :  *
      66              :  * Not specific to the pressure solve: the implicit viscous solver a projection
      67              :  * owns (ns_viscous_internal.h) is kept by the same rule, and its Helmholtz shift
      68              :  * depends on dt, so a caller that changes dt rebuilds it here.
      69              :  *
      70              :  * Rebuilds when the method, backend, parameters or grid differ from what the
      71              :  * existing instance was built for, rather than assuming any of them is fixed:
      72              :  * pressure_solver is read from params on every step today, and a caller may
      73              :  * resize between steps. All are rare, so a rebuild is the right cost, but
      74              :  * silently solving with the previous configuration would not be.
      75              :  *
      76              :  * Returns the init status, so an MG mode on a grid that is not 2^k+1 fails at
      77              :  * solver init -- where the caller can still choose something else -- rather than
      78              :  * on the first step. That particular rejection is reported as UNSUPPORTED rather
      79              :  * than INVALID, because the grid is fine and only this mode cannot run on it.
      80              :  */
      81        14457 : static inline cfd_status_t ns_pressure_ensure(poisson_solver_t** slot,
      82              :                                               const poisson_solver_config_t* cfg,
      83              :                                               const grid* g) {
      84        14457 :     if (!slot || !cfg || !g) {
      85              :         return CFD_ERROR_INVALID;
      86              :     }
      87              : 
      88        14457 :     size_t nx = g->nx;
      89        14457 :     size_t ny = g->ny;
      90        14457 :     size_t nz = g->nz;
      91        14457 :     double dx = g->dx[0];
      92        14457 :     double dy = g->dy[0];
      93        14457 :     double dz = (nz > 1 && g->dz) ? g->dz[0] : 0.0;
      94              : 
      95              :     /* Screened here so the remap below stays unambiguous: poisson_solver_init
      96              :      * reports a degenerate grid with CFD_ERROR_INVALID too, and that is a caller
      97              :      * error rather than an unsupported configuration. */
      98        14457 :     if (nx < 3 || ny < 3 || (nz > 1 && nz < 3)) {
      99            4 :         cfd_set_error(CFD_ERROR_INVALID,
     100              :             "The pressure solve needs at least 3 points per active dimension");
     101            4 :         return CFD_ERROR_INVALID;
     102              :     }
     103              : 
     104        14453 :     poisson_solver_t* existing = *slot;
     105        14453 :     if (existing) {
     106        14291 :         int same_grid = existing->nx == nx && existing->ny == ny && existing->nz == nz
     107        28582 :                      && existing->dx == dx && existing->dy == dy && existing->dz == dz;
     108              :         /* The backend belongs in this test as much as the method does: reusing a
     109              :          * scalar solver for a request that named OpenMP would serialize the
     110              :          * pressure solve of a parallel projection, which is the cross-backend
     111              :          * fallback the error-handling rules forbid outright. AUTO matches
     112              :          * whatever is cached, because poisson_solver_create resolves it the same
     113              :          * way every time and so would hand back the backend already held. */
     114        28582 :         int same_backend = cfg->backend == POISSON_BACKEND_AUTO
     115        14291 :                         || existing->backend == cfg->backend;
     116        28582 :         int same_config = existing->method == cfg->method
     117        14291 :                        && same_backend
     118        28582 :                        && memcmp(&existing->params, &cfg->params, sizeof cfg->params) == 0;
     119        14291 :         if (same_grid && same_config) {
     120              :             return CFD_SUCCESS;
     121              :         }
     122           10 :         CFD_LOG_DEBUG("projection", "owned Poisson solver rebuilt: %s",
     123              :                       same_grid ? "configuration changed" : "grid changed");
     124           10 :         poisson_solver_destroy(existing);
     125           10 :         *slot = NULL;
     126              :     }
     127              : 
     128              :     /* Cleared so that the status read back below is this call's and not whatever
     129              :      * the thread failed at last -- cfd_get_last_status() is sticky and never
     130              :      * clears itself, so an earlier unrelated failure (a probe for an
     131              :      * unavailable backend, say) would otherwise be reported as this one's
     132              :      * reason. poisson_solve() clears for exactly this reason before the same
     133              :      * read. */
     134          172 :     cfd_clear_error();
     135              : 
     136          172 :     poisson_solver_t* solver = poisson_solver_create(cfg->method, cfg->backend);
     137          172 :     if (!solver) {
     138              :         /* Report what the factory reported. Collapsing everything to
     139              :          * UNSUPPORTED would tell a caller to try another backend when the real
     140              :          * problem was an allocation failure, and the next backend would fail
     141              :          * the same way. A factory that set nothing still must not read back as
     142              :          * success. */
     143            0 :         cfd_status_t reason = cfd_get_last_status();
     144            0 :         if (reason == CFD_SUCCESS) {
     145            0 :             cfd_set_error(CFD_ERROR_UNSUPPORTED,
     146              :                 "The pressure solver could not be created for this method and backend");
     147            0 :             reason = CFD_ERROR_UNSUPPORTED;
     148              :         }
     149            0 :         return reason;
     150              :     }
     151              : 
     152              :     /* A multigrid hierarchy needs 2^k+1 points per active dimension. Tested here
     153              :      * rather than inferred from the init status: that grid shape is the caller's
     154              :      * to fix by choosing another pressure mode, so it is reported as UNSUPPORTED
     155              :      * rather than INVALID, but poisson_solver_init returns INVALID for a dozen
     156              :      * unrelated reasons now -- a prescribed z-face on a 2D grid, a non-finite
     157              :      * wall value, a parameter group the method does not read. Mapping all of
     158              :      * them to this message sent callers to resize a grid that was never the
     159              :      * problem. Everything else passes through with the message init set. */
     160          172 :     int uses_hierarchy = cfg->method == POISSON_METHOD_MULTIGRID
     161          172 :                       || cfg->params.krylov.preconditioner == POISSON_PRECOND_MULTIGRID;
     162              :     if (uses_hierarchy
     163           30 :         && (!mg_is_pow2_plus1(nx) || !mg_is_pow2_plus1(ny)
     164           13 :             || (nz > 1 && !mg_is_pow2_plus1(nz)))) {
     165            4 :         poisson_solver_destroy(solver);
     166            4 :         cfd_set_error(CFD_ERROR_UNSUPPORTED,
     167              :             "The multigrid pressure modes require 2^k+1 points per active dimension");
     168            4 :         return CFD_ERROR_UNSUPPORTED;
     169              :     }
     170              : 
     171          168 :     cfd_status_t status =
     172          168 :         poisson_solver_init(solver, nx, ny, nz, dx, dy, dz, &cfg->params);
     173          168 :     if (status != CFD_SUCCESS) {
     174            0 :         poisson_solver_destroy(solver);
     175            0 :         return status;
     176              :     }
     177              : 
     178          168 :     *slot = solver;
     179          168 :     return CFD_SUCCESS;
     180              : }
     181              : 
     182              : /**
     183              :  * Check that an owned pressure solver matches the buffers about to be swept.
     184              :  *
     185              :  * ns_pressure_ensure() sizes the solver from the grid, while a projection
     186              :  * backend's rhs, p_new and u_new are sized from whatever it was built for --
     187              :  * the field it is stepping, or the grid its context was created for. The two
     188              :  * are separate caller-owned objects and nothing upstream ties them together, so
     189              :  * a caller stepping with a mismatched pair would have the solver's kernels
     190              :  * sweep to solver->nx-1 and run off the end of all three buffers.
     191              :  *
     192              :  * Each backend passes the dimensions its own buffers were sized from, which is
     193              :  * the one part of this check that legitimately differs between them; the rule
     194              :  * and the diagnostic do not, and were copied into three files before this.
     195              :  */
     196        14289 : static inline cfd_status_t ns_pressure_check_shape(const poisson_solver_t* pressure,
     197              :                                                    size_t nx, size_t ny, size_t nz) {
     198        14289 :     if (!pressure) {
     199              :         /* Set rather than left to the caller's last failure: cfd_get_last_status()
     200              :          * is sticky, so a silent return here reports whatever the thread failed at
     201              :          * previously -- the same hazard ns_pressure_ensure() clears for above. */
     202            0 :         cfd_set_error(CFD_ERROR_INVALID,
     203              :             "The projection solver has no pressure solver; it was not initialized, "
     204              :             "or a previous init failed and its status was discarded.");
     205            0 :         return CFD_ERROR_INVALID;
     206              :     }
     207        14289 :     if (pressure->nx != nx || pressure->ny != ny || pressure->nz != nz) {
     208            0 :         cfd_set_error(CFD_ERROR_INVALID,
     209              :             "The pressure solver was built for different dimensions than this solver's "
     210              :             "buffers were sized for; re-init the solver for the grid it is stepping.");
     211            0 :         return CFD_ERROR_INVALID;
     212              :     }
     213              :     return CFD_SUCCESS;
     214              : }
     215              : 
     216              : /** Destroy an owned pressure solver and clear the slot. NULL-safe. */
     217          268 : static inline void ns_pressure_release(poisson_solver_t** slot) {
     218        13097 :     if (slot && *slot) {
     219          158 :         poisson_solver_destroy(*slot);
     220          158 :         *slot = NULL;
     221              :     }
     222              : }
     223              : 
     224              : #endif /* CFD_NS_PRESSURE_INTERNAL_H */
        

Generated by: LCOV version 2.0-1