LCOV - code coverage report
Current view: top level - io - checkpoint.c (source / functions) Coverage Total Hit
Test: coverage.info Lines: 94.0 % 451 424
Test Date: 2026-10-05 04:47:18 Functions: 100.0 % 19 19

            Line data    Source code
       1              : /**
       2              :  * @file checkpoint.c
       3              :  * @brief Portable binary save/restore of complete simulation state.
       4              :  *
       5              :  * See checkpoint.h for the rationale. The serializer is deliberately
       6              :  * field-by-field with fixed-width little-endian encoding (no raw struct dumps),
       7              :  * so a file written on one platform reads identically on another. A small
       8              :  * latching I/O helper (chk_io) centralizes byte-order encoding, short-read /
       9              :  * short-write detection, and the running CRC32 so the high-level reader/writer
      10              :  * read like a flat description of the format.
      11              :  */
      12              : 
      13              : #include "cfd/io/checkpoint.h"
      14              : 
      15              : #include "cfd/core/cfd_version.h"
      16              : #include "cfd/core/logging.h"
      17              : #include "cfd/core/memory.h"
      18              : 
      19              : #include <math.h>
      20              : #include <stdint.h>
      21              : #include <stdio.h>
      22              : #include <string.h>
      23              : 
      24              : /* ==========================================================================
      25              :  * Format constants
      26              :  * ========================================================================== */
      27              : 
      28              : static const uint8_t CHK_MAGIC[8] = {'C', 'F', 'D', 'C', 'H', 'K', 0, 0};
      29              : 
      30              : #define CHK_ENDIAN_MARKER 0x01020304u  /* decoded LE; foreign-endian files differ */
      31              : #define CHK_FLAG_CHECKSUM 0x0001u      /* header flags bit0: trailing CRC32 present */
      32              : 
      33              : /* Robustness caps for malformed/hostile files (not physical limits). */
      34              : #define CHK_MAX_DIM    (1u << 24)  /* per-axis point count */
      35              : #define CHK_MAX_STRING (1u << 20)  /* length-prefixed string bytes */
      36              : 
      37              : /* ==========================================================================
      38              :  * CRC32 (IEEE 802.3, reflected, poly 0xEDB88320) — table-less and stateless
      39              :  * so it is thread-safe with no static initialization.
      40              :  * ========================================================================== */
      41              : 
      42        55431 : static uint32_t crc32_update(uint32_t crc, const void* data, size_t n) {
      43        55431 :     const uint8_t* p = (const uint8_t*)data;
      44       492294 :     for (size_t i = 0; i < n; i++) {
      45       436863 :         crc ^= p[i];
      46      3931767 :         for (int k = 0; k < 8; k++) {
      47      3494904 :             crc = (crc >> 1) ^ (0xEDB88320u & (0u - (crc & 1u)));
      48              :         }
      49              :     }
      50        55431 :     return crc;
      51              : }
      52              : 
      53              : /* ==========================================================================
      54              :  * Latching little-endian I/O helper
      55              :  * ========================================================================== */
      56              : 
      57              : typedef struct {
      58              :     FILE* fp;
      59              :     cfd_status_t status; /* first error latches; later ops become no-ops */
      60              :     uint32_t crc;        /* running raw CRC (final value is crc ^ 0xFFFFFFFF) */
      61              : } chk_io;
      62              : 
      63        28773 : static void chk_write_bytes(chk_io* io, const void* p, size_t n) {
      64        28773 :     if (io->status != CFD_SUCCESS) {
      65              :         return;
      66              :     }
      67        28773 :     if (n && fwrite(p, 1, n, io->fp) != n) {
      68            0 :         io->status = CFD_ERROR_IO;
      69            0 :         return;
      70              :     }
      71        57546 :     io->crc = crc32_update(io->crc, p, n);
      72              : }
      73              : 
      74        28205 : static void chk_read_bytes(chk_io* io, void* p, size_t n) {
      75        28205 :     if (io->status != CFD_SUCCESS) {
      76              :         return;
      77              :     }
      78        53318 :     if (n && fread(p, 1, n, io->fp) != n) {
      79            1 :         io->status = CFD_ERROR_IO;
      80            1 :         return;
      81              :     }
      82        53316 :     io->crc = crc32_update(io->crc, p, n);
      83              : }
      84              : 
      85              : /* --- fixed-width writers (explicit little-endian) --- */
      86              : 
      87           88 : static void put_u16(chk_io* io, uint16_t v) {
      88           88 :     uint8_t b[2] = {(uint8_t)(v & 0xFFu), (uint8_t)((v >> 8) & 0xFFu)};
      89           88 :     chk_write_bytes(io, b, sizeof(b));
      90              : }
      91              : 
      92          702 : static void put_u32(chk_io* io, uint32_t v) {
      93          702 :     uint8_t b[4];
      94         3510 :     for (int i = 0; i < 4; i++) {
      95         2808 :         b[i] = (uint8_t)((v >> (8 * i)) & 0xFFu);
      96              :     }
      97          702 :     chk_write_bytes(io, b, sizeof(b));
      98          702 : }
      99              : 
     100        27932 : static void put_u64(chk_io* io, uint64_t v) {
     101        27932 :     uint8_t b[8];
     102       251388 :     for (int i = 0; i < 8; i++) {
     103       223456 :         b[i] = (uint8_t)((v >> (8 * i)) & 0xFFu);
     104              :     }
     105        27932 :     chk_write_bytes(io, b, sizeof(b));
     106        27932 : }
     107              : 
     108          570 : static void put_i32(chk_io* io, int32_t v) {
     109          570 :     put_u32(io, (uint32_t)v);
     110              : }
     111              : 
     112        27778 : static void put_f64(chk_io* io, double v) {
     113        27778 :     uint64_t bits;
     114           20 :     memcpy(&bits, &v, sizeof(bits)); /* IEEE-754 bit pattern, alias-safe */
     115        26800 :     put_u64(io, bits);
     116            1 : }
     117              : 
     118          310 : static void put_f64_array(chk_io* io, const double* a, size_t n) {
     119        26871 :     for (size_t i = 0; i < n; i++) {
     120        26561 :         put_f64(io, a[i]);
     121              :     }
     122              : }
     123              : 
     124          110 : static void put_bc_values(chk_io* io, const bc_dirichlet_values_t* v) {
     125          110 :     put_f64(io, v->left);
     126          110 :     put_f64(io, v->right);
     127          110 :     put_f64(io, v->top);
     128          110 :     put_f64(io, v->bottom);
     129          110 :     put_f64(io, v->front);
     130          110 :     put_f64(io, v->back);
     131          110 : }
     132              : 
     133              : /* NULL or empty string both serialize as length 0. */
     134           66 : static void put_string(chk_io* io, const char* s) {
     135           66 :     uint32_t len = s ? (uint32_t)strlen(s) : 0u;
     136           66 :     put_u32(io, len);
     137           66 :     if (len) {
     138           29 :         chk_write_bytes(io, s, len);
     139              :     }
     140           66 : }
     141              : 
     142              : /* --- fixed-width readers (explicit little-endian) --- */
     143              : 
     144           92 : static uint16_t get_u16(chk_io* io) {
     145           92 :     uint8_t b[2] = {0, 0};
     146           92 :     chk_read_bytes(io, b, sizeof(b));
     147           92 :     return (uint16_t)((uint16_t)b[0] | ((uint16_t)b[1] << 8));
     148              : }
     149              : 
     150          735 : static uint32_t get_u32(chk_io* io) {
     151          735 :     uint8_t b[4] = {0};
     152          735 :     chk_read_bytes(io, b, sizeof(b));
     153          735 :     uint32_t v = 0;
     154         3675 :     for (int i = 0; i < 4; i++) {
     155         2940 :         v |= (uint32_t)b[i] << (8 * i);
     156              :     }
     157          735 :     return v;
     158              : }
     159              : 
     160        27327 : static uint64_t get_u64(chk_io* io) {
     161        27327 :     uint8_t b[8] = {0};
     162        27327 :     chk_read_bytes(io, b, sizeof(b));
     163        27327 :     uint64_t v = 0;
     164       245943 :     for (int i = 0; i < 8; i++) {
     165       218616 :         v |= (uint64_t)b[i] << (8 * i);
     166              :     }
     167        27327 :     return v;
     168              : }
     169              : 
     170          597 : static int32_t get_i32(chk_io* io) {
     171          620 :     return (int32_t)get_u32(io);
     172              : }
     173              : 
     174        27166 : static double get_f64(chk_io* io) {
     175        53287 :     uint64_t bits = get_u64(io);
     176        27166 :     double v;
     177        27166 :     memcpy(&v, &bits, sizeof(v));
     178        27166 :     return v;
     179              : }
     180              : 
     181          296 : static void get_f64_array(chk_io* io, double* a, size_t n) {
     182        26187 :     for (size_t i = 0; i < n; i++) {
     183        25891 :         a[i] = get_f64(io);
     184              :     }
     185              : }
     186              : 
     187          115 : static void get_bc_values(chk_io* io, bc_dirichlet_values_t* v) {
     188          115 :     v->left = get_f64(io);
     189          115 :     v->right = get_f64(io);
     190          115 :     v->top = get_f64(io);
     191          115 :     v->bottom = get_f64(io);
     192          115 :     v->front = get_f64(io);
     193          115 :     v->back = get_f64(io);
     194          115 : }
     195              : 
     196              : /* Reads a length-prefixed string. If buf is NULL the bytes are consumed (and
     197              :  * folded into the CRC) but discarded. Sets CFD_ERROR_INVALID if the stored
     198              :  * length is implausible or does not fit in the caller's buffer. */
     199           69 : static void get_string(chk_io* io, char* buf, size_t cap) {
     200           69 :     uint32_t len = get_u32(io);
     201           69 :     if (io->status != CFD_SUCCESS) {
     202            9 :         return;
     203              :     }
     204           60 :     if (len > CHK_MAX_STRING) {
     205            0 :         io->status = CFD_ERROR_INVALID;
     206            0 :         return;
     207              :     }
     208              :     // A caller buffer with zero capacity cannot be filled or NUL-terminated, so
     209              :     // treat it as invalid rather than silently discarding the string bytes.
     210           60 :     if (buf && (cap == 0 || (size_t)len + 1 > cap)) {
     211            0 :         io->status = CFD_ERROR_INVALID;
     212            0 :         return;
     213              :     }
     214              : 
     215              :     uint8_t tmp[256];
     216              :     uint32_t remaining = len;
     217              :     size_t off = 0;
     218           88 :     while (remaining > 0 && io->status == CFD_SUCCESS) {
     219           28 :         size_t chunk = remaining < sizeof(tmp) ? remaining : sizeof(tmp);
     220           28 :         chk_read_bytes(io, tmp, chunk);
     221           28 :         if (io->status != CFD_SUCCESS) {
     222              :             break;
     223              :         }
     224           28 :         if (buf && cap > 0) {
     225           28 :             memcpy(buf + off, tmp, chunk);
     226           28 :             off += chunk;
     227              :         }
     228           28 :         remaining -= (uint32_t)chunk;
     229              :     }
     230           60 :     if (buf && cap > 0 && io->status == CFD_SUCCESS) {
     231           34 :         buf[len] = '\0';
     232              :     }
     233              : }
     234              : 
     235              : /* Trailing CRC32 is written/read raw (NOT folded into the running CRC). */
     236           22 : static void put_u32_raw(chk_io* io, uint32_t v) {
     237           22 :     if (io->status != CFD_SUCCESS) {
     238            0 :         return;
     239              :     }
     240              :     uint8_t b[4];
     241          110 :     for (int i = 0; i < 4; i++) {
     242           88 :         b[i] = (uint8_t)((v >> (8 * i)) & 0xFFu);
     243              :     }
     244           22 :     if (fwrite(b, 1, sizeof(b), io->fp) != sizeof(b)) {
     245            0 :         io->status = CFD_ERROR_IO;
     246              :     }
     247              : }
     248              : 
     249           22 : static uint32_t get_u32_raw(chk_io* io) {
     250           22 :     uint8_t b[4] = {0};
     251           22 :     if (io->status != CFD_SUCCESS) {
     252              :         return 0;
     253              :     }
     254           20 :     if (fread(b, 1, sizeof(b), io->fp) != sizeof(b)) {
     255            0 :         io->status = CFD_ERROR_IO;
     256            0 :         return 0;
     257              :     }
     258              :     uint32_t v = 0;
     259          100 :     for (int i = 0; i < 4; i++) {
     260           80 :         v |= (uint32_t)b[i] << (8 * i);
     261              :     }
     262              :     return v;
     263              : }
     264              : 
     265              : /* ==========================================================================
     266              :  * Section writers (shared layout description used by both write and read)
     267              :  * ========================================================================== */
     268              : 
     269           22 : static void write_header(chk_io* io) {
     270           22 :     chk_write_bytes(io, CHK_MAGIC, sizeof(CHK_MAGIC));
     271           22 :     put_u32(io, CFD_CHECKPOINT_FORMAT_VERSION);
     272           22 :     put_u32(io, CHK_ENDIAN_MARKER);
     273           22 :     put_u16(io, (uint16_t)CFD_VERSION_MAJOR);
     274           22 :     put_u16(io, (uint16_t)CFD_VERSION_MINOR);
     275           22 :     put_u16(io, (uint16_t)CFD_VERSION_PATCH);
     276           22 :     put_u16(io, (uint16_t)CHK_FLAG_CHECKSUM);
     277           22 :     put_u64(io, 0); /* reserved */
     278           22 : }
     279              : 
     280           22 : static void write_grid(chk_io* io, const grid* g) {
     281           22 :     put_u64(io, (uint64_t)g->nx);
     282           22 :     put_u64(io, (uint64_t)g->ny);
     283           22 :     put_u64(io, (uint64_t)g->nz);
     284           22 :     put_f64(io, g->xmin);
     285           22 :     put_f64(io, g->xmax);
     286           22 :     put_f64(io, g->ymin);
     287           22 :     put_f64(io, g->ymax);
     288           22 :     put_f64(io, g->zmin);
     289           22 :     put_f64(io, g->zmax);
     290           22 :     put_f64_array(io, g->x, g->nx);
     291           22 :     put_f64_array(io, g->y, g->ny);
     292           22 :     put_f64_array(io, g->dx, g->nx - 1);
     293           22 :     put_f64_array(io, g->dy, g->ny - 1);
     294           22 :     if (g->nz > 1) {
     295            1 :         put_f64_array(io, g->z, g->nz);
     296            1 :         put_f64_array(io, g->dz, g->nz - 1);
     297            1 :         put_f64(io, g->inv_dz2); /* derived but min-dz dependent; store to stay exact */
     298              :     }
     299           22 : }
     300              : 
     301           22 : static void write_field(chk_io* io, const flow_field* f) {
     302           22 :     size_t n = f->nx * f->ny * f->nz;
     303           22 :     put_u64(io, (uint64_t)f->nx); /* self-check against grid on read */
     304           22 :     put_u64(io, (uint64_t)f->ny);
     305           22 :     put_u64(io, (uint64_t)f->nz);
     306           22 :     put_f64_array(io, f->u, n);
     307           22 :     put_f64_array(io, f->v, n);
     308           22 :     put_f64_array(io, f->w, n);
     309           22 :     put_f64_array(io, f->p, n);
     310           22 :     put_f64_array(io, f->rho, n);
     311           22 :     put_f64_array(io, f->T, n);
     312              :     /* Turbulence state, always allocated (zero when no model is active). All
     313              :      * four carry over between steps -- nu_t through the momentum equation,
     314              :      * including the wall-function values at wall nodes -- so a restart without
     315              :      * them restarts the turbulence from zero and is not bit-exact. */
     316           22 :     put_f64_array(io, f->turb_k, n);
     317           22 :     put_f64_array(io, f->turb_eps, n);
     318           22 :     put_f64_array(io, f->turb_nu_tilde, n);
     319           22 :     put_f64_array(io, f->nu_t, n);
     320           22 : }
     321              : 
     322           22 : static void write_params(chk_io* io, const ns_solver_params_t* p) {
     323           22 :     put_f64(io, p->dt);
     324           22 :     put_f64(io, p->cfl);
     325           22 :     put_f64(io, p->gamma);
     326           22 :     put_f64(io, p->mu);
     327           22 :     put_f64(io, p->k);
     328           22 :     put_i32(io, p->max_iter);
     329           22 :     put_f64(io, p->tolerance);
     330           22 :     put_f64(io, p->source_amplitude_u);
     331           22 :     put_f64(io, p->source_amplitude_v);
     332           22 :     put_f64(io, p->source_decay_rate);
     333           22 :     put_f64(io, p->pressure_coupling);
     334           22 :     put_f64(io, p->alpha);
     335           22 :     put_f64(io, p->beta);
     336           22 :     put_f64(io, p->T_ref);
     337           22 :     put_f64(io, p->gravity[0]);
     338           22 :     put_f64(io, p->gravity[1]);
     339           22 :     put_f64(io, p->gravity[2]);
     340              :     /* thermal_bc: face types then Dirichlet values */
     341           22 :     put_i32(io, (int32_t)p->thermal_bc.left);
     342           22 :     put_i32(io, (int32_t)p->thermal_bc.right);
     343           22 :     put_i32(io, (int32_t)p->thermal_bc.bottom);
     344           22 :     put_i32(io, (int32_t)p->thermal_bc.top);
     345           22 :     put_i32(io, (int32_t)p->thermal_bc.front);
     346           22 :     put_i32(io, (int32_t)p->thermal_bc.back);
     347           22 :     put_bc_values(io, &p->thermal_bc.dirichlet_values);
     348              :     /* solver selections */
     349           22 :     put_i32(io, (int32_t)p->turb_model);
     350           22 :     put_i32(io, (int32_t)p->pressure_solver);
     351           22 :     put_i32(io, (int32_t)p->convection_scheme);
     352              :     /* turb_closure is a caller-owned context and cannot be stored; the enum
     353              :      * beside it can be, and a resume that dropped it would silently change
     354              :      * the eddy viscosity while reporting success. */
     355           22 :     put_i32(io, (int32_t)p->turb_nut_correction);
     356           22 :     put_i32(io, (int32_t)p->viscous_scheme);
     357              :     /* turb_bc: face types then k, epsilon and nu_tilde Dirichlet values */
     358           22 :     put_i32(io, (int32_t)p->turb_bc.left);
     359           22 :     put_i32(io, (int32_t)p->turb_bc.right);
     360           22 :     put_i32(io, (int32_t)p->turb_bc.bottom);
     361           22 :     put_i32(io, (int32_t)p->turb_bc.top);
     362           22 :     put_i32(io, (int32_t)p->turb_bc.front);
     363           22 :     put_i32(io, (int32_t)p->turb_bc.back);
     364           22 :     put_bc_values(io, &p->turb_bc.k_values);
     365           22 :     put_bc_values(io, &p->turb_bc.eps_values);
     366           22 :     put_bc_values(io, &p->turb_bc.nu_tilde_values);
     367              :     /* A resume that dropped it would switch the wall law back to the default */
     368           22 :     put_i32(io, (int32_t)p->turb_bc.wall_law);
     369              :     /* turb_bc segments, all but the profile callback, which is caller-owned */
     370           22 :     put_u32(io, (uint32_t)p->turb_bc.n_segments);
     371           32 :     for (size_t n = 0; n < p->turb_bc.n_segments; n++) {
     372           10 :         const ns_turbulence_bc_segment_t* s = &p->turb_bc.segments[n];
     373           10 :         put_i32(io, (int32_t)s->edge);
     374           10 :         put_f64(io, s->start);
     375           10 :         put_f64(io, s->end);
     376           10 :         put_i32(io, (int32_t)s->type);
     377              :         /* A profile overrides the values and cannot be stored. NaN in their
     378              :          * place makes turbulence_apply_bcs() refuse the loaded segment, for any
     379              :          * model, until the profile is re-attached -- rather than run on
     380              :          * whatever placeholder values sat beside it. */
     381           17 :         const int profiled = (s->type == BC_TYPE_DIRICHLET && s->profile != NULL);
     382            7 :         put_f64(io, profiled ? NAN : s->k);
     383           10 :         put_f64(io, profiled ? NAN : s->eps);
     384           20 :         put_f64(io, profiled ? NAN : s->nu_tilde);
     385              :     }
     386              :     /* pressure_bc: face types then the prescribed wall values */
     387           22 :     put_i32(io, (int32_t)p->pressure_bc.left);
     388           22 :     put_i32(io, (int32_t)p->pressure_bc.right);
     389           22 :     put_i32(io, (int32_t)p->pressure_bc.bottom);
     390           22 :     put_i32(io, (int32_t)p->pressure_bc.top);
     391           22 :     put_i32(io, (int32_t)p->pressure_bc.front);
     392           22 :     put_i32(io, (int32_t)p->pressure_bc.back);
     393           22 :     put_bc_values(io, &p->pressure_bc.values);
     394           22 : }
     395              : 
     396              : /* ==========================================================================
     397              :  * Public API: write
     398              :  * ========================================================================== */
     399              : 
     400           23 : cfd_status_t cfd_checkpoint_write(const char* path,
     401              :                                   const grid* g,
     402              :                                   const flow_field* field,
     403              :                                   const ns_solver_params_t* params,
     404              :                                   double current_time,
     405              :                                   const char* solver_name,
     406              :                                   const char* run_prefix,
     407              :                                   const char* output_base_dir) {
     408           23 :     if (!path || !g || !field || !params || !solver_name) {
     409            0 :         cfd_set_error(CFD_ERROR_INVALID, "cfd_checkpoint_write: NULL argument");
     410            0 :         return CFD_ERROR_INVALID;
     411              :     }
     412           23 :     if (field->nx != g->nx || field->ny != g->ny || field->nz != g->nz) {
     413            0 :         cfd_set_error(CFD_ERROR_INVALID, "cfd_checkpoint_write: field/grid dimension mismatch");
     414            0 :         return CFD_ERROR_INVALID;
     415              :     }
     416           23 :     if (params->turb_bc.n_segments > NS_TURB_BC_MAX_SEGMENTS) {
     417            1 :         cfd_set_error(CFD_ERROR_INVALID,
     418              :                       "cfd_checkpoint_write: turb_bc.n_segments exceeds NS_TURB_BC_MAX_SEGMENTS");
     419            1 :         return CFD_ERROR_INVALID;
     420              :     }
     421              : 
     422           22 :     FILE* fp = fopen(path, "wb");
     423           22 :     if (!fp) {
     424            0 :         cfd_set_error(CFD_ERROR_IO, "cfd_checkpoint_write: failed to open file");
     425            0 :         return CFD_ERROR_IO;
     426              :     }
     427              : 
     428           22 :     chk_io io = {fp, CFD_SUCCESS, 0xFFFFFFFFu};
     429              : 
     430           22 :     write_header(&io);
     431           22 :     write_grid(&io, g);
     432           22 :     write_field(&io, field);
     433           22 :     write_params(&io, params);
     434           22 :     put_f64(&io, current_time);
     435           22 :     put_string(&io, solver_name);
     436           22 :     put_string(&io, run_prefix);
     437           22 :     put_string(&io, output_base_dir);
     438           22 :     put_u32_raw(&io, io.crc ^ 0xFFFFFFFFu); /* trailing CRC32 over the body */
     439              : 
     440           22 :     cfd_status_t status = io.status;
     441           22 :     if (fclose(fp) != 0 && status == CFD_SUCCESS) {
     442              :         status = CFD_ERROR_IO;
     443              :     }
     444           22 :     if (status != CFD_SUCCESS) {
     445            0 :         cfd_set_error(status, "cfd_checkpoint_write: write failed");
     446              :     }
     447              :     return status;
     448              : }
     449              : 
     450              : /* Every enum below is cast straight out of the file, so none of the values are
     451              :  * ones the compiler chose. Range-checked HERE rather than left to whichever
     452              :  * door downstream happens to look: solver init catches turb_model,
     453              :  * pressure_solver, convection_scheme, viscous_scheme and pressure_bc, but
     454              :  * nothing anywhere range-checks a thermal_bc or turb_bc face, and a caller who
     455              :  * never inits an NS solver is told nothing at all. A corrupt file is the
     456              :  * reader's to reject -- the same reject-unknown rule this file already applies
     457              :  * to version, byte order and dtype. */
     458              : static int chk_bc_type_is_legal(bc_type_t t) {
     459              :     return t == BC_TYPE_PERIODIC || t == BC_TYPE_NEUMANN || t == BC_TYPE_DIRICHLET
     460              :         || t == BC_TYPE_NOSLIP || t == BC_TYPE_INLET || t == BC_TYPE_OUTLET
     461              :         || t == BC_TYPE_SYMMETRY;
     462              : }
     463              : 
     464              : /* The wall-type check is spelled out here rather than calling the canonical
     465              :  * poisson_walls_are_legal(). That predicate lives in linear_solver.c, which is
     466              :  * part of cfd_api, while this file is part of cfd_core -- a target documented
     467              :  * as depending on nothing (docs/architecture/architecture.md) and carrying no
     468              :  * target_link_libraries at all. Calling up into the API layer would invert that
     469              :  * dependency and leave anyone linking CFD::Core alone with an undefined symbol;
     470              :  * the unified CFD::Library that every test links hides it. Six comparisons are
     471              :  * the cheaper price. Keep the two in step if poisson_wall_t gains a member. */
     472              : static int chk_wall_type_is_legal(poisson_wall_t t) {
     473              :     return t == POISSON_WALL_ZERO_GRADIENT || t == POISSON_WALL_DIRICHLET;
     474              : }
     475              : 
     476           18 : static int chk_walls_are_legal(const poisson_walls_t* w) {
     477           18 :     return chk_wall_type_is_legal(w->left) && chk_wall_type_is_legal(w->right)
     478           18 :         && chk_wall_type_is_legal(w->bottom) && chk_wall_type_is_legal(w->top)
     479           18 :         && chk_wall_type_is_legal(w->front) && chk_wall_type_is_legal(w->back);
     480              : }
     481              : 
     482           19 : static int chk_bc_faces_are_legal(const bc_type_t* faces) {
     483          253 :     for (int i = 0; i < 6; i++) {
     484          217 :         if (!chk_bc_type_is_legal(faces[i])) {
     485              :             return 0;
     486              :         }
     487              :     }
     488              :     return 1;
     489              : }
     490              : 
     491           19 : static int chk_params_are_legal(const ns_solver_params_t* p) {
     492           19 :     const bc_type_t thermal[6] = {p->thermal_bc.left, p->thermal_bc.right,
     493           19 :                                   p->thermal_bc.bottom, p->thermal_bc.top,
     494           19 :                                   p->thermal_bc.front, p->thermal_bc.back};
     495           19 :     const bc_type_t turb[6] = {p->turb_bc.left, p->turb_bc.right,
     496           19 :                                p->turb_bc.bottom, p->turb_bc.top,
     497           19 :                                p->turb_bc.front, p->turb_bc.back};
     498           56 :     if (!chk_bc_faces_are_legal(thermal) || !chk_bc_faces_are_legal(turb)) {
     499              :         return 0;
     500              :     }
     501           25 :     if (!chk_walls_are_legal(&p->pressure_bc)) {
     502              :         return 0;
     503              :     }
     504           17 :     if (p->turb_model != TURB_MODEL_NONE && p->turb_model != TURB_MODEL_K_EPSILON
     505              :         && p->turb_model != TURB_MODEL_SPALART_ALLMARAS) {
     506              :         return 0;
     507              :     }
     508           17 :     if (p->pressure_solver != NS_PRESSURE_SOLVER_DEFAULT
     509              :         && p->pressure_solver != NS_PRESSURE_SOLVER_MULTIGRID
     510              :         && p->pressure_solver != NS_PRESSURE_SOLVER_PCG_MG) {
     511              :         return 0;
     512              :     }
     513           17 :     if (p->convection_scheme != NS_CONVECTION_SCHEME_CENTRAL
     514              :         && p->convection_scheme != NS_CONVECTION_SCHEME_UPWIND) {
     515              :         return 0;
     516              :     }
     517              :     /* Folded in from the standalone check that arrived with the strain-rate
     518              :      * correction (#224): same rule, same entry point, one validator. */
     519           17 :     if (p->turb_nut_correction != NS_NUT_CORRECTION_NONE
     520              :         && p->turb_nut_correction != NS_NUT_CORRECTION_S_STAR) {
     521              :         return 0;
     522              :     }
     523           16 :     if (p->viscous_scheme != NS_VISCOUS_SCHEME_EXPLICIT
     524              :         && p->viscous_scheme != NS_VISCOUS_SCHEME_BACKWARD_EULER
     525              :         && p->viscous_scheme != NS_VISCOUS_SCHEME_CRANK_NICOLSON) {
     526              :         return 0;
     527              :     }
     528           15 :     if (p->turb_bc.wall_law != NS_WALL_LAW_LOG
     529              :         && p->turb_bc.wall_law != NS_WALL_LAW_SPALDING) {
     530              :         return 0;
     531              :     }
     532              :     /* Enums only, like the faces above; ranges and values are checked by
     533              :      * turbulence_apply_bcs(), which applies the same rules to any caller. */
     534           23 :     for (size_t n = 0; n < p->turb_bc.n_segments; n++) {
     535           11 :         const ns_turbulence_bc_segment_t* s = &p->turb_bc.segments[n];
     536           11 :         if (s->edge != BC_EDGE_LEFT && s->edge != BC_EDGE_RIGHT
     537           11 :             && s->edge != BC_EDGE_BOTTOM && s->edge != BC_EDGE_TOP) {
     538              :             return 0;
     539              :         }
     540           10 :         if (!chk_bc_type_is_legal(s->type)) {
     541              :             return 0;
     542              :         }
     543              :     }
     544              :     return 1;
     545              : }
     546              : 
     547              : /* ==========================================================================
     548              :  * Public API: read
     549              :  * ========================================================================== */
     550              : 
     551           23 : cfd_status_t cfd_checkpoint_read(const char* path,
     552              :                                  grid** out_grid,
     553              :                                  flow_field** out_field,
     554              :                                  ns_solver_params_t* out_params,
     555              :                                  double* out_current_time,
     556              :                                  char* out_solver_name,
     557              :                                  size_t solver_name_cap,
     558              :                                  char* out_run_prefix,
     559              :                                  size_t run_prefix_cap,
     560              :                                  char* out_output_base_dir,
     561              :                                  size_t output_base_dir_cap) {
     562           23 :     if (out_grid) {
     563           23 :         *out_grid = NULL;
     564              :     }
     565           23 :     if (out_field) {
     566           23 :         *out_field = NULL;
     567              :     }
     568           23 :     if (!path || !out_grid || !out_field || !out_params) {
     569            0 :         cfd_set_error(CFD_ERROR_INVALID, "cfd_checkpoint_read: NULL argument");
     570            0 :         return CFD_ERROR_INVALID;
     571              :     }
     572           23 :     memset(out_params, 0, sizeof(*out_params)); /* leaves callback pointers NULL */
     573              : 
     574           23 :     FILE* fp = fopen(path, "rb");
     575           23 :     if (!fp) {
     576            0 :         cfd_set_error(CFD_ERROR_IO, "cfd_checkpoint_read: failed to open file");
     577            0 :         return CFD_ERROR_IO;
     578              :     }
     579              : 
     580           23 :     chk_io io = {fp, CFD_SUCCESS, 0xFFFFFFFFu};
     581           23 :     grid* g = NULL;
     582           23 :     flow_field* f = NULL;
     583              : 
     584              :     /* --- header --- */
     585           23 :     uint8_t magic[8] = {0};
     586           23 :     chk_read_bytes(&io, magic, sizeof(magic));
     587           23 :     if (io.status == CFD_SUCCESS && memcmp(magic, CHK_MAGIC, sizeof(magic)) != 0) {
     588            1 :         io.status = CFD_ERROR_INVALID;
     589              :     }
     590           23 :     uint32_t version = get_u32(&io);
     591           23 :     uint32_t endian = get_u32(&io);
     592           23 :     (void)get_u16(&io); /* lib major */
     593           23 :     (void)get_u16(&io); /* lib minor */
     594           23 :     (void)get_u16(&io); /* lib patch */
     595           23 :     uint16_t flags = get_u16(&io);
     596           23 :     (void)get_u64(&io); /* reserved */
     597           23 :     if (io.status == CFD_SUCCESS &&
     598           22 :         (version != CFD_CHECKPOINT_FORMAT_VERSION || endian != CHK_ENDIAN_MARKER)) {
     599            1 :         io.status = CFD_ERROR_UNSUPPORTED;
     600              :     }
     601              : 
     602              :     /* --- grid --- */
     603           23 :     uint64_t nx = get_u64(&io);
     604           23 :     uint64_t ny = get_u64(&io);
     605           23 :     uint64_t nz = get_u64(&io);
     606           23 :     double xmin = get_f64(&io);
     607           23 :     double xmax = get_f64(&io);
     608           23 :     double ymin = get_f64(&io);
     609           23 :     double ymax = get_f64(&io);
     610           23 :     double zmin = get_f64(&io);
     611           23 :     double zmax = get_f64(&io);
     612           23 :     if (io.status == CFD_SUCCESS &&
     613           21 :         (nx < 2 || ny < 2 || nz < 1 || nx > CHK_MAX_DIM || ny > CHK_MAX_DIM ||
     614           21 :          nz > CHK_MAX_DIM)) {
     615            0 :         io.status = CFD_ERROR_INVALID;
     616              :     }
     617           23 :     if (io.status == CFD_SUCCESS) {
     618           21 :         g = grid_create((size_t)nx, (size_t)ny, (size_t)nz, xmin, xmax, ymin, ymax, zmin, zmax);
     619           21 :         if (!g) {
     620            0 :             io.status = CFD_ERROR_NOMEM;
     621              :         }
     622              :     }
     623           23 :     if (io.status == CFD_SUCCESS) {
     624           21 :         get_f64_array(&io, g->x, g->nx);
     625           21 :         get_f64_array(&io, g->y, g->ny);
     626           21 :         get_f64_array(&io, g->dx, g->nx - 1);
     627           21 :         get_f64_array(&io, g->dy, g->ny - 1);
     628           21 :         if (g->nz > 1) {
     629            1 :             get_f64_array(&io, g->z, g->nz);
     630            1 :             get_f64_array(&io, g->dz, g->nz - 1);
     631            1 :             g->inv_dz2 = get_f64(&io);
     632              :         }
     633              :     }
     634              : 
     635              :     /* --- field (dimensions must match grid) --- */
     636           23 :     uint64_t fnx = get_u64(&io);
     637           23 :     uint64_t fny = get_u64(&io);
     638           23 :     uint64_t fnz = get_u64(&io);
     639           23 :     if (io.status == CFD_SUCCESS && (fnx != nx || fny != ny || fnz != nz)) {
     640            0 :         io.status = CFD_ERROR_INVALID;
     641              :     }
     642           23 :     if (io.status == CFD_SUCCESS) {
     643           21 :         f = flow_field_create((size_t)nx, (size_t)ny, (size_t)nz);
     644           21 :         if (!f) {
     645            0 :             io.status = CFD_ERROR_NOMEM;
     646              :         }
     647              :     }
     648           23 :     if (io.status == CFD_SUCCESS) {
     649           21 :         size_t n = f->nx * f->ny * f->nz;
     650           21 :         get_f64_array(&io, f->u, n);
     651           21 :         get_f64_array(&io, f->v, n);
     652           21 :         get_f64_array(&io, f->w, n);
     653           21 :         get_f64_array(&io, f->p, n);
     654           21 :         get_f64_array(&io, f->rho, n);
     655           21 :         get_f64_array(&io, f->T, n);
     656           21 :         get_f64_array(&io, f->turb_k, n);
     657           21 :         get_f64_array(&io, f->turb_eps, n);
     658           21 :         get_f64_array(&io, f->turb_nu_tilde, n);
     659           21 :         get_f64_array(&io, f->nu_t, n);
     660              :     }
     661              : 
     662              :     /* --- params (callbacks remain NULL from the memset) --- */
     663           23 :     out_params->dt = get_f64(&io);
     664           23 :     out_params->cfl = get_f64(&io);
     665           23 :     out_params->gamma = get_f64(&io);
     666           23 :     out_params->mu = get_f64(&io);
     667           23 :     out_params->k = get_f64(&io);
     668           23 :     out_params->max_iter = get_i32(&io);
     669           23 :     out_params->tolerance = get_f64(&io);
     670           23 :     out_params->source_amplitude_u = get_f64(&io);
     671           23 :     out_params->source_amplitude_v = get_f64(&io);
     672           23 :     out_params->source_decay_rate = get_f64(&io);
     673           23 :     out_params->pressure_coupling = get_f64(&io);
     674           23 :     out_params->alpha = get_f64(&io);
     675           23 :     out_params->beta = get_f64(&io);
     676           23 :     out_params->T_ref = get_f64(&io);
     677           23 :     out_params->gravity[0] = get_f64(&io);
     678           23 :     out_params->gravity[1] = get_f64(&io);
     679           23 :     out_params->gravity[2] = get_f64(&io);
     680           23 :     out_params->thermal_bc.left = (bc_type_t)get_i32(&io);
     681           23 :     out_params->thermal_bc.right = (bc_type_t)get_i32(&io);
     682           23 :     out_params->thermal_bc.bottom = (bc_type_t)get_i32(&io);
     683           23 :     out_params->thermal_bc.top = (bc_type_t)get_i32(&io);
     684           23 :     out_params->thermal_bc.front = (bc_type_t)get_i32(&io);
     685           23 :     out_params->thermal_bc.back = (bc_type_t)get_i32(&io);
     686           23 :     get_bc_values(&io, &out_params->thermal_bc.dirichlet_values);
     687           23 :     out_params->turb_model = (turbulence_model_t)get_i32(&io);
     688           23 :     out_params->pressure_solver = (ns_pressure_solver_t)get_i32(&io);
     689           23 :     out_params->convection_scheme = (ns_convection_scheme_t)get_i32(&io);
     690           23 :     out_params->turb_nut_correction = (ns_nut_correction_t)get_i32(&io);
     691           23 :     out_params->viscous_scheme = (ns_viscous_scheme_t)get_i32(&io);
     692           23 :     out_params->turb_bc.left = (bc_type_t)get_i32(&io);
     693           23 :     out_params->turb_bc.right = (bc_type_t)get_i32(&io);
     694           23 :     out_params->turb_bc.bottom = (bc_type_t)get_i32(&io);
     695           23 :     out_params->turb_bc.top = (bc_type_t)get_i32(&io);
     696           23 :     out_params->turb_bc.front = (bc_type_t)get_i32(&io);
     697           23 :     out_params->turb_bc.back = (bc_type_t)get_i32(&io);
     698           23 :     get_bc_values(&io, &out_params->turb_bc.k_values);
     699           23 :     get_bc_values(&io, &out_params->turb_bc.eps_values);
     700           23 :     get_bc_values(&io, &out_params->turb_bc.nu_tilde_values);
     701           23 :     out_params->turb_bc.wall_law = (ns_wall_law_t)get_i32(&io);
     702           23 :     uint32_t n_segments = get_u32(&io);
     703           23 :     if (io.status == CFD_SUCCESS && n_segments > NS_TURB_BC_MAX_SEGMENTS) {
     704            0 :         io.status = CFD_ERROR_INVALID; /* more than the array holds: corrupt */
     705              :     }
     706           23 :     if (io.status == CFD_SUCCESS) {
     707           20 :         out_params->turb_bc.n_segments = n_segments;
     708           31 :         for (uint32_t n = 0; n < n_segments; n++) {
     709           11 :             ns_turbulence_bc_segment_t* s = &out_params->turb_bc.segments[n];
     710           11 :             s->edge = (bc_edge_t)get_i32(&io);
     711           11 :             s->start = get_f64(&io);
     712           11 :             s->end = get_f64(&io);
     713           11 :             s->type = (bc_type_t)get_i32(&io);
     714           11 :             s->k = get_f64(&io);
     715           11 :             s->eps = get_f64(&io);
     716           11 :             s->nu_tilde = get_f64(&io);
     717              :         }
     718              :     }
     719           23 :     out_params->pressure_bc.left = (poisson_wall_t)get_i32(&io);
     720           23 :     out_params->pressure_bc.right = (poisson_wall_t)get_i32(&io);
     721           23 :     out_params->pressure_bc.bottom = (poisson_wall_t)get_i32(&io);
     722           23 :     out_params->pressure_bc.top = (poisson_wall_t)get_i32(&io);
     723           23 :     out_params->pressure_bc.front = (poisson_wall_t)get_i32(&io);
     724           23 :     out_params->pressure_bc.back = (poisson_wall_t)get_i32(&io);
     725           23 :     get_bc_values(&io, &out_params->pressure_bc.values);
     726              : 
     727              :     /* --- sim metadata --- */
     728           23 :     double current_time = get_f64(&io);
     729           23 :     get_string(&io, out_solver_name, solver_name_cap);
     730           23 :     get_string(&io, out_run_prefix, run_prefix_cap);
     731           23 :     get_string(&io, out_output_base_dir, output_base_dir_cap);
     732              : 
     733              :     /* --- trailing CRC32 over the body --- */
     734           23 :     if (flags & CHK_FLAG_CHECKSUM) {
     735           22 :         uint32_t computed = io.crc ^ 0xFFFFFFFFu;
     736           22 :         uint32_t stored = get_u32_raw(&io);
     737           22 :         if (io.status == CFD_SUCCESS && computed != stored) {
     738            1 :             io.status = CFD_ERROR_IO;
     739              :         }
     740              :     }
     741              : 
     742              :     // A failed close can surface a buffered read error that the reads missed, so
     743              :     // promote it to a read failure rather than returning success.
     744           23 :     if (fclose(fp) != 0 && io.status == CFD_SUCCESS) {
     745            0 :         io.status = CFD_ERROR_IO;
     746              :     }
     747              : 
     748           23 :     if (io.status != CFD_SUCCESS) {
     749            4 :         grid_destroy(g);
     750            4 :         flow_field_destroy(f);
     751            4 :         cfd_set_error(io.status, "cfd_checkpoint_read: read failed");
     752            4 :         return io.status;
     753              :     }
     754              : 
     755              :     /* After the CRC, so bit-rot is reported as bit-rot; before the outputs are
     756              :      * published, so no caller ever holds params carrying a value no enum
     757              :      * defines. */
     758           19 :     if (!chk_params_are_legal(out_params)) {
     759            7 :         grid_destroy(g);
     760            7 :         flow_field_destroy(f);
     761            7 :         memset(out_params, 0, sizeof(*out_params));
     762            7 :         cfd_set_error(CFD_ERROR_INVALID,
     763              :                       "cfd_checkpoint_read: the file carries a solver parameter "
     764              :                       "outside its enum; it was written by a different build or "
     765              :                       "has been edited");
     766            7 :         return CFD_ERROR_INVALID;
     767              :     }
     768              : 
     769           12 :     *out_grid = g;
     770           12 :     *out_field = f;
     771           12 :     if (out_current_time) {
     772           11 :         *out_current_time = current_time;
     773              :     }
     774              :     return CFD_SUCCESS;
     775              : }
        

Generated by: LCOV version 2.0-1