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
|