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

            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 */
        

Generated by: LCOV version 2.0-1