Line data Source code
1 : /**
2 : * @file multigrid_internal.h
3 : * @brief Internal data structures and grid-transfer operators for geometric multigrid
4 : *
5 : * Not part of the public API. The algorithm itself lives in
6 : * multigrid_template/linear_solver_multigrid_template.h. The scalar transfer
7 : * operators live in cpu/multigrid_transfer.c with external linkage but are not
8 : * exported from the shared library (no CFD_LIBRARY_EXPORT, hidden visibility):
9 : * the operator unit test links them from the static library, or compiles the
10 : * translation unit directly in shared builds. The restriction weight rule and
11 : * the interior mean are static inline here so every backend shares one copy.
12 : */
13 :
14 : #ifndef CFD_MULTIGRID_INTERNAL_H
15 : #define CFD_MULTIGRID_INTERNAL_H
16 :
17 : #include "cfd/core/indexing.h"
18 : #include "cfd/solvers/poisson_solver.h"
19 :
20 : #include <stdbool.h>
21 : #include <stddef.h>
22 :
23 : #ifdef __cplusplus
24 : extern "C" {
25 : #endif
26 :
27 : /* Defaults resolved at init when the corresponding param is 0 */
28 : #define MG_DEFAULT_PRE_SMOOTH 2
29 : #define MG_DEFAULT_POST_SMOOTH 2
30 : #define MG_DEFAULT_COARSE_MAX_ITER 50
31 :
32 : /* Coarsest-grid size floor per BC mode: a 3x3 Neumann grid's single interior
33 : * point has an identically zero mirror-BC operator (all stencil neighbors
34 : * mirror the center), so Neumann coarsening stops at 5. A 3x3 Dirichlet grid
35 : * is solved exactly by one Gauss-Seidel sweep. */
36 : #define MG_MIN_COARSE_DIM_DIRICHLET 3
37 : #define MG_MIN_COARSE_DIM_NEUMANN 5
38 :
39 : /* Weighted Jacobi smoother relaxation: optimal high-frequency damping */
40 : #define MG_JACOBI_OMEGA (2.0 / 3.0)
41 :
42 : /* Minimum points one OpenMP multigrid region must cover to use the thread team.
43 : * Each OMP primitive opens a region per plane and compares its own work with this
44 : * value: the interior points of the plane it writes, or the 2(nx+ny) copies of
45 : * the Neumann boundary pass. Starting and joining a team costs as much as sweeping
46 : * tens of thousands of points, so smaller loops (the coarser levels, small grids)
47 : * run serially (omp/linear_solver_multigrid_omp.c). test_omp_consistency keeps
48 : * configurations above it. */
49 : #define MG_OMP_MIN_POINTS 32768
50 :
51 : /**
52 : * Per-level grid data for the multigrid hierarchy.
53 : *
54 : * Level 0 (finest) borrows the caller's x/rhs arrays, so its x and rhs
55 : * pointers stay NULL; coarser levels own their buffers.
56 : */
57 : typedef struct {
58 : size_t nx, ny, nz; /* Grid dimensions at this level (nz==1 for 2D) */
59 : size_t total; /* nx * ny * nz */
60 : size_t stride_z; /* nx*ny for 3D, 0 for 2D (branch-free stencils) */
61 : size_t k_start, k_end; /* z loop bounds ([1,nz-1) for 3D, [0,1) for 2D) */
62 : double dx2, dy2; /* Squared grid spacings at this level */
63 : double inv_dz2; /* 1/dz^2 at this level (0.0 for 2D) */
64 : double inv_factor; /* 1/(2/dx2 + 2/dy2 + 2*inv_dz2): smoother diagonal inverse */
65 : double* x; /* Correction vector (levels >= 1; NULL at level 0) */
66 : double* x_temp; /* Jacobi smoother buffer (NULL unless Jacobi smoother) */
67 : double* rhs; /* Restricted residual / restricted b (levels >= 1; NULL at level 0) */
68 : double* residual; /* Residual buffer (all levels except coarsest) */
69 : } mg_level_t;
70 :
71 : /**
72 : * Multigrid solver context (stored in poisson_solver_t.context)
73 : */
74 : typedef struct {
75 : int num_levels; /* >= 1; [0] = finest, [num_levels-1] = coarsest */
76 : mg_level_t* levels;
77 :
78 : /* Resolved parameters (defaults already applied) */
79 : mg_cycle_type_t cycle_type;
80 : mg_smoother_type_t smoother_type;
81 : mg_bc_type_t bc_mode;
82 : int nu1, nu2; /* Pre/post smoothing sweeps */
83 : int coarse_max_iter; /* Smoother sweeps on the coarsest grid */
84 :
85 : int fmg_pending; /* 1: next iterate() performs the FMG nested iteration */
86 : int initialized;
87 : } mg_context_t;
88 :
89 : /** n is of the form 2^k+1 (k>=1): n-1 is a power of two */
90 888 : static inline bool mg_is_pow2_plus1(size_t n) {
91 888 : return (n >= 3) && (((n - 1) & (n - 2)) == 0);
92 : }
93 :
94 : /* ============================================================================
95 : * GRID-TRANSFER OPERATORS (cpu/multigrid_transfer.c)
96 : *
97 : * Scalar reference operators. The OpenMP backend keeps row-parallel static
98 : * counterparts with the same arithmetic in omp/linear_solver_multigrid_omp.c;
99 : * both use mg_weights_1d and mg_interior_mean below, so the two backends
100 : * cannot diverge in the fold rule or the mean.
101 : *
102 : * External linkage, intentionally NOT CFD_LIBRARY_EXPORT (hidden outside a
103 : * shared library build).
104 : * All write coarse/fine INTERIOR points only. Restriction never reads fine
105 : * boundary values (coarse-interior stencils stay within the fine interior);
106 : * prolongation reads coarse boundary values, which the caller must have set
107 : * consistently with the BC mode (zero for Dirichlet corrections, mirrored
108 : * for Neumann).
109 : *
110 : * fold_neumann: with zero-gradient BCs the boundary vertex is slaved to its
111 : * interior neighbor (mirror plane at the half-cell), so prolongation reads
112 : * mirrored ghosts. The adjoint of that folded prolongation doubles the
113 : * toward-boundary weight at boundary-adjacent coarse points. Pass 1 in
114 : * Neumann mode to keep restriction the exact adjoint (up to the standard
115 : * 1/4 (2D) or 1/8 (3D) factor); pass 0 for Dirichlet.
116 : * ============================================================================ */
117 :
118 : /**
119 : * Per-dimension 1D restriction weights at a coarse index: (1,2,1) in the
120 : * interior. With fold_neumann, the toward-boundary weight doubles at
121 : * boundary-adjacent coarse points (I==1 and/or I==n_coarse-2) — the exact
122 : * adjoint of prolongation through mirrored (zero-gradient) ghost values.
123 : */
124 14058959 : static inline void mg_weights_1d(size_t idx, size_t n_coarse, int fold_neumann,
125 : double w[3]) {
126 14058959 : w[0] = (fold_neumann && idx == 1) ? 2.0 : 1.0;
127 14058959 : w[1] = 2.0;
128 28053187 : w[2] = (fold_neumann && idx == n_coarse - 2) ? 2.0 : 1.0;
129 : }
130 :
131 : /** Full-weighting restriction, 2D (4-2-1)/16 stencil; coarse interior only */
132 : void mg_restrict_2d(const double* fine, double* coarse,
133 : size_t nxf, size_t nyf, size_t nxc, size_t nyc,
134 : int fold_neumann);
135 :
136 : /** Full-weighting restriction, 3D 27-point (8-4-2-1)/64 stencil */
137 : void mg_restrict_3d(const double* fine, double* coarse,
138 : size_t nxf, size_t nyf, size_t nzf,
139 : size_t nxc, size_t nyc, size_t nzc,
140 : int fold_neumann);
141 :
142 : /** Bilinear prolongation, adds into fine interior points only */
143 : void mg_prolongate_add_2d(const double* coarse, double* fine,
144 : size_t nxc, size_t nyc, size_t nxf, size_t nyf);
145 :
146 : /** Trilinear prolongation, adds into fine interior points only */
147 : void mg_prolongate_add_3d(const double* coarse, double* fine,
148 : size_t nxc, size_t nyc, size_t nzc,
149 : size_t nxf, size_t nyf, size_t nzf);
150 :
151 : /**
152 : * Mean of f over interior points. Serial by design: every backend must
153 : * produce the identical mean, so it is never computed with a parallel
154 : * reduction.
155 : */
156 25241 : static inline double mg_interior_mean(const double* f, size_t nx, size_t ny,
157 : size_t nz) {
158 25241 : size_t stride_z = (nz > 1) ? nx * ny : 0;
159 25241 : size_t k_start = (nz > 1) ? 1 : 0;
160 25241 : size_t k_end = (nz > 1) ? nz - 1 : 1;
161 :
162 25241 : double sum = 0.0;
163 25241 : size_t count = 0;
164 53356 : for (size_t k = k_start; k < k_end; k++) {
165 632061 : for (size_t j = 1; j < ny - 1; j++) {
166 26530914 : for (size_t i = 1; i < nx - 1; i++) {
167 25926968 : sum += f[k * stride_z + IDX_2D(i, j, nx)];
168 25926968 : count++;
169 : }
170 : }
171 : }
172 25241 : return (count > 0) ? sum / (double)count : 0.0;
173 : }
174 :
175 : /** Subtract the interior mean from interior points (boundary untouched) */
176 : void mg_subtract_interior_mean(double* f, size_t nx, size_t ny, size_t nz);
177 :
178 : #ifdef CFD_ENABLE_OPENMP
179 : /**
180 : * Row-parallel counterpart (omp/linear_solver_multigrid_omp.c). The mean stays
181 : * serial, so the result matches mg_subtract_interior_mean. The OpenMP projection
182 : * solver calls it before its multigrid pressure solve. External linkage, not
183 : * exported, like the scalar operators above.
184 : */
185 : void mg_subtract_interior_mean_omp(double* f, size_t nx, size_t ny, size_t nz);
186 : #endif
187 :
188 : #ifdef __cplusplus
189 : }
190 : #endif
191 :
192 : #endif /* CFD_MULTIGRID_INTERNAL_H */
|