LCOV - code coverage report
Current view: top level - solvers/linear/multigrid_template - linear_solver_multigrid_template.h (source / functions) Coverage Total Hit
Test: coverage.info Lines: 96.6 % 205 198
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 26 26

            Line data    Source code
       1              : /**
       2              :  * @file linear_solver_multigrid_template.h
       3              :  * @brief Geometric multigrid algorithm shared by the multigrid backends
       4              :  *
       5              :  * V/W/F(FMG) cycles with Red-Black Gauss-Seidel (default) or weighted Jacobi
       6              :  * smoothing, full-weighting restriction and bilinear/trilinear prolongation.
       7              :  * Grid dimensions must be 2^k+1 per active dimension.
       8              :  *
       9              :  * Boundary-condition modes (params.multigrid.bc):
      10              :  * - MG_BC_NEUMANN (default): zero-gradient BCs matching the other Poisson
      11              :  *   solvers. The system is singular (constant nullspace); restricted RHS
      12              :  *   vectors are projected to zero interior mean, coarse corrections are
      13              :  *   mean-subtracted, and the solution converges up to an additive constant.
      14              :  * - MG_BC_DIRICHLET: caller-supplied boundary values of x are held fixed on
      15              :  *   the finest grid; coarse-level corrections use homogeneous zero boundaries.
      16              :  *
      17              :  * Level 0 (finest) borrows the caller's x/rhs arrays; coarser levels own
      18              :  * their buffers. The public x_temp argument is unused (like CG); the Jacobi
      19              :  * smoother allocates its own per-level temporaries.
      20              :  *
      21              :  * This header is the only copy of the algorithm: per-level BCs, the smoother
      22              :  * sweep loop, level transfers, the V/W cycle, FMG, init/destroy, iterate,
      23              :  * solve, apply_bc and the factory. Each backend includes it once, after
      24              :  * defining its grid primitives, so backends differ only in those primitives:
      25              :  *   cpu/linear_solver_multigrid.c       scalar
      26              :  *   omp/linear_solver_multigrid_omp.c   OpenMP
      27              :  * Control flow, level bookkeeping, whole-buffer memsets, the Neumann interior
      28              :  * mean (mg_interior_mean) and the convergence residual are serial in every
      29              :  * backend, so element-wise primitives reproduce the scalar result exactly.
      30              :  *
      31              :  * REQUIRED MACROS (every MGT_* macro is #undef'd at the end of this header):
      32              :  *   MGT_SUFFIX         symbol suffix (scalar, ...); the factory is
      33              :  *                      create_multigrid_<MGT_SUFFIX>_solver
      34              :  *   MGT_SOLVER_NAME    POISSON_SOLVER_TYPE_MG_* name string
      35              :  *   MGT_DESCRIPTION    description string
      36              :  *   MGT_BACKEND        POISSON_BACKEND_* value
      37              :  *
      38              :  * REQUIRED PRIMITIVES (each macro names a function; interior points only
      39              :  * unless noted; transfer contracts in multigrid_internal.h):
      40              :  *   void MGT_BC_NEUMANN_PLANE(plane, nx, ny)          zero-gradient BCs on one
      41              :  *                                                     nx x ny plane (all edges)
      42              :  *   void MGT_RBGS_SWEEP(L, x, rhs)                    one red then one black
      43              :  *                                                     Gauss-Seidel pass, no BCs
      44              :  *   void MGT_JACOBI_SWEEP(L, x, x_temp, rhs)          one MG_JACOBI_OMEGA-weighted
      45              :  *                                                     Jacobi pass into x_temp, then
      46              :  *                                                     interior copy back, no BCs
      47              :  *   void MGT_RESIDUAL(L, x, rhs, r)                   r = rhs - nabla^2 x
      48              :  *   void MGT_RESTRICT_2D(fine, coarse, nxf, nyf, nxc, nyc, fold_neumann)
      49              :  *   void MGT_RESTRICT_3D(fine, coarse, nxf, nyf, nzf, nxc, nyc, nzc, fold_neumann)
      50              :  *   void MGT_PROLONGATE_ADD_2D(coarse, fine, nxc, nyc, nxf, nyf)
      51              :  *   void MGT_PROLONGATE_ADD_3D(coarse, fine, nxc, nyc, nzc, nxf, nyf, nzf)
      52              :  *   void MGT_SUBTRACT_INTERIOR_MEAN(f, nx, ny, nz)
      53              :  *   void MGT_ZERO_INTERIOR(L, x)                      interior of x = 0
      54              :  */
      55              : 
      56              : #include "../linear_solver_internal.h"
      57              : #include "../multigrid_internal.h"
      58              : 
      59              : #include "cfd/core/memory.h"
      60              : 
      61              : #include <string.h>
      62              : 
      63              : #if !defined(MGT_SUFFIX) || !defined(MGT_SOLVER_NAME) || \
      64              :     !defined(MGT_DESCRIPTION) || !defined(MGT_BACKEND)
      65              : #error "Multigrid configuration macros must be defined before including linear_solver_multigrid_template.h"
      66              : #endif
      67              : 
      68              : #if !defined(MGT_BC_NEUMANN_PLANE) || !defined(MGT_RBGS_SWEEP) ||          \
      69              :     !defined(MGT_JACOBI_SWEEP) || !defined(MGT_RESIDUAL) ||                \
      70              :     !defined(MGT_RESTRICT_2D) || !defined(MGT_RESTRICT_3D) ||              \
      71              :     !defined(MGT_PROLONGATE_ADD_2D) || !defined(MGT_PROLONGATE_ADD_3D) ||  \
      72              :     !defined(MGT_SUBTRACT_INTERIOR_MEAN) || !defined(MGT_ZERO_INTERIOR)
      73              : #error "Multigrid primitive macros must be defined before including linear_solver_multigrid_template.h"
      74              : #endif
      75              : 
      76              : /* ============================================================================
      77              :  * TOKEN PASTING
      78              :  * ============================================================================ */
      79              : 
      80              : #define MGT_CONCAT_IMPL(a, b) a##_##b
      81              : #define MGT_CONCAT(a, b) MGT_CONCAT_IMPL(a, b)
      82              : #define MGT_FUNC(name) MGT_CONCAT(name, MGT_SUFFIX)
      83              : 
      84              : #define MGT_FACTORY_IMPL(suffix) create_multigrid_##suffix##_solver
      85              : #define MGT_FACTORY(suffix) MGT_FACTORY_IMPL(suffix)
      86              : 
      87              : /* ============================================================================
      88              :  * BOUNDARY CONDITIONS
      89              :  * ============================================================================ */
      90              : 
      91              : /**
      92              :  * Apply the BC mode to a field at one level.
      93              :  *
      94              :  * Neumann: mirror of poisson_solver_apply_bc()'s default (z-plane copies plus
      95              :  * per-plane zero-gradient), but with this level's dimensions.
      96              :  * Dirichlet: no-op — boundary values are never touched anywhere in MG, so
      97              :  * finest-level data stays fixed and coarse corrections stay zero.
      98              :  */
      99       655817 : static void MGT_FUNC(mg_apply_bc_level)(const mg_level_t* L, mg_bc_type_t bc,
     100              :                                         double* x) {
     101       655817 :     if (bc == MG_BC_DIRICHLET) {
     102              :         return;
     103              :     }
     104              : 
     105       175370 :     size_t nx = L->nx;
     106       175370 :     size_t ny = L->ny;
     107       175370 :     size_t nz = L->nz;
     108       175370 :     size_t plane_size = nx * ny;
     109              : 
     110       175370 :     if (nz > 1) {
     111        30598 :         memcpy(x, x + plane_size, plane_size * sizeof(double));
     112        30598 :         memcpy(x + (nz - 1) * plane_size,
     113        30598 :                x + (nz - 2) * plane_size,
     114              :                plane_size * sizeof(double));
     115              :     }
     116              : 
     117       485228 :     for (size_t k = 0; k < nz; k++) {
     118       309858 :         MGT_BC_NEUMANN_PLANE(x + k * plane_size, nx, ny);
     119              :     }
     120              : }
     121              : 
     122              : /* ============================================================================
     123              :  * SMOOTHERS
     124              :  * ============================================================================ */
     125              : 
     126              : /**
     127              :  * Run `sweeps` smoother passes, applying BCs after each pass.
     128              :  *
     129              :  * Red-Black Gauss-Seidel uses omega = 1: over-relaxation degrades the
     130              :  * high-frequency smoothing factor, so plain GS is correct inside multigrid.
     131              :  * Weighted Jacobi uses omega = 2/3 (optimal high-frequency damping) and copies
     132              :  * interior points only back into x, preserving Dirichlet boundary values.
     133              :  */
     134        57584 : static void MGT_FUNC(mg_smooth)(const mg_context_t* ctx, const mg_level_t* L,
     135              :                                 double* x, const double* rhs, int sweeps) {
     136       683826 :     for (int sweep = 0; sweep < sweeps; sweep++) {
     137       626242 :         if (ctx->smoother_type == MG_SMOOTHER_JACOBI) {
     138       460896 :             MGT_JACOBI_SWEEP(L, x, L->x_temp, rhs);
     139              :         } else {
     140       165346 :             MGT_RBGS_SWEEP(L, x, rhs);
     141              :         }
     142              : 
     143       626242 :         MGT_FUNC(mg_apply_bc_level)(L, ctx->bc_mode, x);
     144              :     }
     145        57584 : }
     146              : 
     147              : /* ============================================================================
     148              :  * GRID TRANSFERS
     149              :  * ============================================================================ */
     150              : 
     151              : /**
     152              :  * Restrict a fine-level field into a coarse-level (MG-owned) RHS buffer.
     153              :  * In Neumann mode the coarse RHS is projected to zero interior mean — the
     154              :  * singular mirror-BC operator only admits solutions for compatible RHS.
     155              :  */
     156        23615 : static void MGT_FUNC(mg_restrict_level)(const mg_context_t* ctx,
     157              :                                         const mg_level_t* Lf, const mg_level_t* Lc,
     158              :                                         const double* fine, double* coarse) {
     159        23615 :     int fold = (ctx->bc_mode == MG_BC_NEUMANN);
     160              : 
     161        23615 :     if (Lf->nz > 1) {
     162         1932 :         MGT_RESTRICT_3D(fine, coarse, Lf->nx, Lf->ny, Lf->nz,
     163         1932 :                         Lc->nx, Lc->ny, Lc->nz, fold);
     164              :     } else {
     165        21683 :         MGT_RESTRICT_2D(fine, coarse, Lf->nx, Lf->ny, Lc->nx, Lc->ny, fold);
     166              :     }
     167              : 
     168        23615 :     if (ctx->bc_mode == MG_BC_NEUMANN) {
     169         5824 :         MGT_SUBTRACT_INTERIOR_MEAN(coarse, Lc->nx, Lc->ny, Lc->nz);
     170              :     }
     171        23615 : }
     172              : 
     173        23615 : static void MGT_FUNC(mg_prolongate_level)(const mg_level_t* Lc, const mg_level_t* Lf,
     174              :                                           const double* coarse, double* fine) {
     175        23615 :     if (Lf->nz > 1) {
     176         1932 :         MGT_PROLONGATE_ADD_3D(coarse, fine, Lc->nx, Lc->ny, Lc->nz,
     177         1932 :                               Lf->nx, Lf->ny, Lf->nz);
     178              :     } else {
     179        21683 :         MGT_PROLONGATE_ADD_2D(coarse, fine, Lc->nx, Lc->ny, Lf->nx, Lf->ny);
     180              :     }
     181        23615 : }
     182              : 
     183              : /* ============================================================================
     184              :  * CYCLES
     185              :  * ============================================================================ */
     186              : 
     187              : /**
     188              :  * Coarsest-grid solve: over-smoothing. A 3x3 Dirichlet grid (one unknown) is
     189              :  * solved exactly by the first sweep; Neumann coarsest grids (>= 5x5, RHS
     190              :  * already mean-projected) converge geometrically in a few dozen sweeps at
     191              :  * negligible cost.
     192              :  */
     193        10650 : static void MGT_FUNC(mg_coarse_solve)(const mg_context_t* ctx, const mg_level_t* L,
     194              :                                       double* x, const double* rhs) {
     195        10650 :     MGT_FUNC(mg_smooth)(ctx, L, x, rhs, ctx->coarse_max_iter);
     196              : }
     197              : 
     198              : /** Recursive V/W cycle. Level 0 is called with the caller's arrays. */
     199        34061 : static void MGT_FUNC(mg_cycle)(mg_context_t* ctx, int level, double* x,
     200              :                                const double* rhs) {
     201        34061 :     mg_level_t* L = &ctx->levels[level];
     202              : 
     203        34061 :     if (level == ctx->num_levels - 1) {
     204        10594 :         MGT_FUNC(mg_coarse_solve)(ctx, L, x, rhs);
     205        10594 :         return;
     206              :     }
     207              : 
     208        23467 :     mg_level_t* Lc = &ctx->levels[level + 1];
     209              : 
     210              :     /* Pre-smooth, then form and restrict the residual */
     211        23467 :     MGT_FUNC(mg_smooth)(ctx, L, x, rhs, ctx->nu1);
     212        23467 :     MGT_RESIDUAL(L, x, rhs, L->residual);
     213        23467 :     MGT_FUNC(mg_restrict_level)(ctx, L, Lc, L->residual, Lc->rhs);
     214              : 
     215              :     /* Coarse-grid correction with zero initial guess. W-cycle: the second
     216              :      * visit continues refining the same correction. */
     217        23467 :     memset(Lc->x, 0, Lc->total * sizeof(double));
     218        23467 :     int num_visits = (ctx->cycle_type == MG_CYCLE_W) ? 2 : 1;
     219        52553 :     for (int v = 0; v < num_visits; v++) {
     220        29086 :         MGT_FUNC(mg_cycle)(ctx, level + 1, Lc->x, Lc->rhs);
     221              :     }
     222              : 
     223        23467 :     if (ctx->bc_mode == MG_BC_NEUMANN) {
     224              :         /* Constants are in the operator's nullspace: removing the mean keeps
     225              :          * the fine solution from drifting. Mirror the boundary so
     226              :          * prolongation interpolates consistent ghost values. */
     227         5776 :         MGT_SUBTRACT_INTERIOR_MEAN(Lc->x, Lc->nx, Lc->ny, Lc->nz);
     228         5776 :         MGT_FUNC(mg_apply_bc_level)(Lc, ctx->bc_mode, Lc->x);
     229              :     }
     230              : 
     231        23467 :     MGT_FUNC(mg_prolongate_level)(Lc, L, Lc->x, x);
     232        23467 :     MGT_FUNC(mg_apply_bc_level)(L, ctx->bc_mode, x);
     233              : 
     234        23467 :     MGT_FUNC(mg_smooth)(ctx, L, x, rhs, ctx->nu2);
     235              : }
     236              : 
     237              : /**
     238              :  * FMG (full multigrid) nested iteration: restrict the original RHS through
     239              :  * all levels, solve on the coarsest, then work upward prolongating the
     240              :  * solution as the initial guess and running one V-cycle per level. Replaces
     241              :  * the caller's initial guess (interior only; boundary data preserved).
     242              :  *
     243              :  * Ascent ordering is load-bearing: levels[l+1].x must be consumed before
     244              :  * mg_cycle(l) overwrites levels[l+1].{x,rhs} with residual-correction data.
     245              :  */
     246           56 : static void MGT_FUNC(mg_fmg)(mg_context_t* ctx, double* x, const double* rhs) {
     247           56 :     int nl = ctx->num_levels;
     248           56 :     mg_level_t* levels = ctx->levels;
     249              : 
     250           56 :     if (nl == 1) {
     251            0 :         MGT_FUNC(mg_cycle)(ctx, 0, x, rhs);
     252            0 :         return;
     253              :     }
     254              : 
     255              :     /* Descent: levels[l].rhs = restricted original b for l >= 1 */
     256           56 :     MGT_FUNC(mg_restrict_level)(ctx, &levels[0], &levels[1], rhs, levels[1].rhs);
     257          148 :     for (int l = 1; l <= nl - 2; l++) {
     258           92 :         MGT_FUNC(mg_restrict_level)(ctx, &levels[l], &levels[l + 1],
     259           92 :                                     levels[l].rhs, levels[l + 1].rhs);
     260              :     }
     261              : 
     262              :     /* Coarsest solve */
     263           56 :     memset(levels[nl - 1].x, 0, levels[nl - 1].total * sizeof(double));
     264          112 :     MGT_FUNC(mg_coarse_solve)(ctx, &levels[nl - 1], levels[nl - 1].x,
     265           56 :                               levels[nl - 1].rhs);
     266              : 
     267              :     /* Ascent through MG-owned levels */
     268          148 :     for (int l = nl - 2; l >= 1; l--) {
     269           92 :         MGT_FUNC(mg_apply_bc_level)(&levels[l + 1], ctx->bc_mode, levels[l + 1].x);
     270           92 :         memset(levels[l].x, 0, levels[l].total * sizeof(double));
     271           92 :         MGT_FUNC(mg_prolongate_level)(&levels[l + 1], &levels[l],
     272           92 :                                       levels[l + 1].x, levels[l].x);
     273           92 :         MGT_FUNC(mg_apply_bc_level)(&levels[l], ctx->bc_mode, levels[l].x);
     274           92 :         MGT_FUNC(mg_cycle)(ctx, l, levels[l].x, levels[l].rhs);
     275              :     }
     276              : 
     277              :     /* Finest level: zero the interior of the caller's x (boundary data must
     278              :      * survive in Dirichlet mode), prolongate the level-1 solution in, and
     279              :      * finish with one V-cycle */
     280           56 :     MGT_FUNC(mg_apply_bc_level)(&levels[1], ctx->bc_mode, levels[1].x);
     281           56 :     MGT_ZERO_INTERIOR(&levels[0], x);
     282           56 :     MGT_FUNC(mg_prolongate_level)(&levels[1], &levels[0], levels[1].x, x);
     283           56 :     MGT_FUNC(mg_apply_bc_level)(&levels[0], ctx->bc_mode, x);
     284           56 :     MGT_FUNC(mg_cycle)(ctx, 0, x, rhs);
     285              : }
     286              : 
     287              : /* ============================================================================
     288              :  * LIFECYCLE
     289              :  * ============================================================================ */
     290              : 
     291          352 : static void MGT_FUNC(mg_free_levels)(mg_context_t* ctx) {
     292          352 :     if (!ctx->levels) {
     293              :         return;
     294              :     }
     295         1699 :     for (int l = 0; l < ctx->num_levels; l++) {
     296         1347 :         cfd_free(ctx->levels[l].x);
     297         1347 :         cfd_free(ctx->levels[l].x_temp);
     298         1347 :         cfd_free(ctx->levels[l].rhs);
     299         1347 :         cfd_free(ctx->levels[l].residual);
     300              :     }
     301          352 :     cfd_free(ctx->levels);
     302          352 :     ctx->levels = NULL;
     303          352 :     ctx->num_levels = 0;
     304              : }
     305              : 
     306          735 : static void MGT_FUNC(mg_destroy)(poisson_solver_t* solver) {
     307          735 :     if (solver && solver->context) {
     308          352 :         mg_context_t* ctx = (mg_context_t*)solver->context;
     309          352 :         MGT_FUNC(mg_free_levels)(ctx);
     310          352 :         cfd_free(ctx);
     311          352 :         solver->context = NULL;
     312              :     }
     313          735 : }
     314              : 
     315          372 : static cfd_status_t MGT_FUNC(mg_init)(
     316              :     poisson_solver_t* solver,
     317              :     size_t nx, size_t ny, size_t nz,
     318              :     double dx, double dy, double dz,
     319              :     const poisson_solver_params_t* params)
     320              : {
     321              :     /* Parallel backends loop over int row/column bounds, which
     322              :      * poisson_solver_size_to_int empties above INT_MAX (a zero residual would
     323              :      * then read as convergence), and level buffers must not wrap size_t:
     324              :      * reject oversized grids before allocating. This runs before the shape
     325              :      * check so every oversized grid reports CFD_ERROR_LIMIT_EXCEEDED. */
     326          372 :     size_t n = 0;
     327          372 :     cfd_status_t size_status = poisson_solver_validate_grid_size(nx, ny, nz, 1, &n);
     328          372 :     if (size_status != CFD_SUCCESS) {
     329              :         return size_status;
     330              :     }
     331              : 
     332              :     /* Geometric coarsening requires 2^k+1 points per active dimension */
     333         1082 :     if (!mg_is_pow2_plus1(nx) || !mg_is_pow2_plus1(ny) ||
     334          121 :         (nz > 1 && !mg_is_pow2_plus1(nz))) {
     335              :         return CFD_ERROR_INVALID;
     336              :     }
     337              : 
     338          352 :     if ((int)params->multigrid.cycle < MG_CYCLE_V ||
     339          352 :         (int)params->multigrid.cycle > MG_CYCLE_F ||
     340          352 :         (int)params->multigrid.smoother < MG_SMOOTHER_REDBLACK_GS ||
     341          352 :         (int)params->multigrid.smoother > MG_SMOOTHER_JACOBI ||
     342          352 :         (int)params->multigrid.bc < MG_BC_NEUMANN ||
     343          352 :         (int)params->multigrid.bc > MG_BC_DIRICHLET ||
     344          352 :         params->multigrid.pre_smooth < 0 || params->multigrid.post_smooth < 0 ||
     345          352 :         params->multigrid.coarse_max_iter < 0 || params->multigrid.max_levels < 0) {
     346              :         return CFD_ERROR_INVALID;
     347              :     }
     348              : 
     349              :     /* Re-init support: drop any previous hierarchy */
     350          352 :     MGT_FUNC(mg_destroy)(solver);
     351              : 
     352          352 :     mg_context_t* ctx = (mg_context_t*)cfd_calloc(1, sizeof(mg_context_t));
     353          352 :     if (!ctx) {
     354              :         return CFD_ERROR_NOMEM;
     355              :     }
     356              : 
     357          352 :     ctx->cycle_type = params->multigrid.cycle;
     358          352 :     ctx->smoother_type = params->multigrid.smoother;
     359          352 :     ctx->bc_mode = params->multigrid.bc;
     360          704 :     ctx->nu1 = (params->multigrid.pre_smooth > 0)
     361          352 :         ? params->multigrid.pre_smooth : MG_DEFAULT_PRE_SMOOTH;
     362          704 :     ctx->nu2 = (params->multigrid.post_smooth > 0)
     363          352 :         ? params->multigrid.post_smooth : MG_DEFAULT_POST_SMOOTH;
     364          704 :     ctx->coarse_max_iter = (params->multigrid.coarse_max_iter > 0)
     365          352 :         ? params->multigrid.coarse_max_iter : MG_DEFAULT_COARSE_MAX_ITER;
     366              : 
     367              :     /* Count levels: coarsen all active dimensions simultaneously while every
     368              :      * next dimension stays at or above the BC-mode floor */
     369          704 :     size_t min_coarse = (ctx->bc_mode == MG_BC_NEUMANN)
     370          352 :         ? MG_MIN_COARSE_DIM_NEUMANN : MG_MIN_COARSE_DIM_DIRICHLET;
     371          352 :     int num_levels = 1;
     372              :     {
     373          352 :         size_t cx = nx, cy = ny, cz = nz;
     374         1347 :         while (params->multigrid.max_levels == 0 ||
     375              :                num_levels < params->multigrid.max_levels) {
     376         1337 :             size_t nx2 = (cx - 1) / 2 + 1;
     377         1337 :             size_t ny2 = (cy - 1) / 2 + 1;
     378         1337 :             size_t nz2 = (nz > 1) ? (cz - 1) / 2 + 1 : 1;
     379         1337 :             if (nx2 < min_coarse || ny2 < min_coarse ||
     380         1008 :                 (nz > 1 && nz2 < min_coarse)) {
     381              :                 break;
     382              :             }
     383          995 :             cx = nx2;
     384          995 :             cy = ny2;
     385          995 :             cz = nz2;
     386          995 :             num_levels++;
     387              :         }
     388              :     }
     389          352 :     ctx->num_levels = num_levels;
     390              : 
     391          352 :     ctx->levels = (mg_level_t*)cfd_calloc((size_t)num_levels,
     392              :                                           sizeof(mg_level_t));
     393          352 :     if (!ctx->levels) {
     394            0 :         cfd_free(ctx);
     395            0 :         return CFD_ERROR_NOMEM;
     396              :     }
     397              : 
     398         1699 :     for (int l = 0; l < num_levels; l++) {
     399         1347 :         mg_level_t* L = &ctx->levels[l];
     400         1347 :         double scale = (double)((size_t)1 << l);
     401              : 
     402         1347 :         L->nx = ((nx - 1) >> l) + 1;
     403         1347 :         L->ny = ((ny - 1) >> l) + 1;
     404         1347 :         L->nz = (nz > 1) ? ((nz - 1) >> l) + 1 : 1;
     405         1347 :         L->total = L->nx * L->ny * L->nz;
     406         1347 :         L->dx2 = (dx * scale) * (dx * scale);
     407         1347 :         L->dy2 = (dy * scale) * (dy * scale);
     408         1347 :         L->inv_dz2 = poisson_solver_compute_inv_dz2(dz * scale);
     409         1347 :         poisson_solver_compute_3d_bounds(L->nz, L->nx, L->ny,
     410              :                                          &L->stride_z, &L->k_start, &L->k_end);
     411         1347 :         L->inv_factor = 1.0 / (2.0 / L->dx2 + 2.0 / L->dy2 + 2.0 * L->inv_dz2);
     412              : 
     413              :         /* Level 0 borrows the caller's x/rhs; the coarsest level needs no
     414              :          * residual buffer */
     415         1347 :         int need_owned = (l >= 1);
     416         1347 :         int need_residual = (l <= num_levels - 2);
     417         1347 :         int need_temp = (ctx->smoother_type == MG_SMOOTHER_JACOBI);
     418              : 
     419         1347 :         if ((need_owned &&
     420          995 :              (!(L->x = (double*)cfd_calloc(L->total, sizeof(double))) ||
     421         1347 :               !(L->rhs = (double*)cfd_calloc(L->total, sizeof(double))))) ||
     422          995 :             (need_residual &&
     423         1347 :              !(L->residual = (double*)cfd_calloc(L->total, sizeof(double)))) ||
     424          560 :             (need_temp &&
     425          560 :              !(L->x_temp = (double*)cfd_calloc(L->total, sizeof(double))))) {
     426            0 :             MGT_FUNC(mg_free_levels)(ctx);
     427            0 :             cfd_free(ctx);
     428            0 :             return CFD_ERROR_NOMEM;
     429              :         }
     430              :     }
     431              : 
     432          352 :     ctx->fmg_pending = (ctx->cycle_type == MG_CYCLE_F);
     433          352 :     ctx->initialized = 1;
     434          352 :     solver->context = ctx;
     435          352 :     return CFD_SUCCESS;
     436              : }
     437              : 
     438              : /* ============================================================================
     439              :  * SOLVE / ITERATE / APPLY_BC
     440              :  * ============================================================================ */
     441              : 
     442         4883 : static cfd_status_t MGT_FUNC(mg_iterate)(
     443              :     poisson_solver_t* solver,
     444              :     double* x,
     445              :     double* x_temp,
     446              :     const double* rhs,
     447              :     double* residual)
     448              : {
     449         4883 :     (void)x_temp;  /* MG allocates its own temporaries */
     450              : 
     451         4883 :     mg_context_t* ctx = (mg_context_t*)solver->context;
     452         4883 :     if (!ctx || !ctx->initialized) {
     453              :         return CFD_ERROR_INVALID;
     454              :     }
     455              : 
     456         4883 :     if (ctx->fmg_pending) {
     457           56 :         MGT_FUNC(mg_fmg)(ctx, x, rhs);
     458           56 :         ctx->fmg_pending = 0;
     459              :     } else {
     460         4827 :         MGT_FUNC(mg_cycle)(ctx, 0, x, rhs);
     461              :     }
     462              : 
     463         4883 :     if (residual) {
     464         2620 :         *residual = poisson_solver_compute_residual(solver, x, rhs);
     465              :     }
     466              : 
     467              :     return CFD_SUCCESS;
     468              : }
     469              : 
     470              : /**
     471              :  * Custom solve wrapper: the FMG flag must reset at the start of every solve,
     472              :  * and iterate() has no solve-start hook. Delegates to the common loop (each
     473              :  * "iteration" is one cycle).
     474              :  */
     475          302 : static cfd_status_t MGT_FUNC(mg_solve)(
     476              :     poisson_solver_t* solver,
     477              :     double* x,
     478              :     double* x_temp,
     479              :     const double* rhs,
     480              :     poisson_solver_stats_t* stats)
     481              : {
     482          302 :     mg_context_t* ctx = (mg_context_t*)solver->context;
     483          302 :     if (!ctx || !ctx->initialized) {
     484              :         return CFD_ERROR_INVALID;
     485              :     }
     486              : 
     487          302 :     ctx->fmg_pending = (ctx->cycle_type == MG_CYCLE_F);
     488          302 :     return poisson_solver_solve_common(solver, x, x_temp, rhs, stats);
     489              : }
     490              : 
     491              : /**
     492              :  * Installed as internal_apply_bc, not apply_bc: multigrid needs its own routine
     493              :  * because the public default is zero-gradient, which would corrupt a field held
     494              :  * in MG_BC_DIRICHLET mode -- but the caller-facing slot has to stay free, or
     495              :  * assigning to it (the documented way to prescribe walls) silently replaces this
     496              :  * and the cycle, which applies its boundaries internally, ignores the
     497              :  * replacement entirely.
     498              :  *
     499              :  * The cycle never reaches this function; it calls mg_apply_bc_level directly.
     500              :  * This exists so an external poisson_solver_apply_bc() on a multigrid solver
     501              :  * applies the walls that solver actually uses.
     502              :  */
     503           36 : static void MGT_FUNC(mg_apply_bc)(poisson_solver_t* solver, double* x) {
     504           36 :     mg_context_t* ctx = (mg_context_t*)solver->context;
     505           36 :     if (!ctx || !ctx->initialized) {
     506              :         return;
     507              :     }
     508           36 :     MGT_FUNC(mg_apply_bc_level)(&ctx->levels[0], ctx->bc_mode, x);
     509              : }
     510              : 
     511              : /* ============================================================================
     512              :  * FACTORY FUNCTION
     513              :  * ============================================================================ */
     514              : 
     515          383 : poisson_solver_t* MGT_FACTORY(MGT_SUFFIX)(void) {
     516          383 :     poisson_solver_t* solver =
     517          383 :         (poisson_solver_t*)cfd_calloc(1, sizeof(poisson_solver_t));
     518          383 :     if (!solver) {
     519              :         return NULL;
     520              :     }
     521              : 
     522          383 :     solver->name = MGT_SOLVER_NAME;
     523          383 :     solver->description = MGT_DESCRIPTION;
     524          383 :     solver->method = POISSON_METHOD_MULTIGRID;
     525          383 :     solver->backend = MGT_BACKEND;
     526          383 :     solver->params = poisson_solver_params_default();
     527              : 
     528          383 :     solver->init = MGT_FUNC(mg_init);
     529          383 :     solver->destroy = MGT_FUNC(mg_destroy);
     530          383 :     solver->solve = MGT_FUNC(mg_solve);      /* Resets FMG state, then common loop */
     531          383 :     solver->iterate = MGT_FUNC(mg_iterate);  /* One V/W cycle (or the FMG pass) */
     532          383 :     solver->internal_apply_bc = MGT_FUNC(mg_apply_bc);
     533              : 
     534          383 :     return solver;
     535              : }
     536              : 
     537              : /* ============================================================================
     538              :  * CLEANUP MACROS
     539              :  * ============================================================================ */
     540              : 
     541              : #undef MGT_FACTORY
     542              : #undef MGT_FACTORY_IMPL
     543              : #undef MGT_FUNC
     544              : #undef MGT_CONCAT
     545              : #undef MGT_CONCAT_IMPL
     546              : 
     547              : #undef MGT_SUFFIX
     548              : #undef MGT_SOLVER_NAME
     549              : #undef MGT_DESCRIPTION
     550              : #undef MGT_BACKEND
     551              : #undef MGT_BC_NEUMANN_PLANE
     552              : #undef MGT_RBGS_SWEEP
     553              : #undef MGT_JACOBI_SWEEP
     554              : #undef MGT_RESIDUAL
     555              : #undef MGT_RESTRICT_2D
     556              : #undef MGT_RESTRICT_3D
     557              : #undef MGT_PROLONGATE_ADD_2D
     558              : #undef MGT_PROLONGATE_ADD_3D
     559              : #undef MGT_SUBTRACT_INTERIOR_MEAN
     560              : #undef MGT_ZERO_INTERIOR
        

Generated by: LCOV version 2.0-1