test_logging.c

Go to the documentation of this file.

/**
 * @file test_logging.c
 * @brief C unit tests for runtime log-level, allow-list, conversion, and profiling helpers.
 */
 
#include "test_support.h"
 
#include "logging.h"
#include "interpolation.h"
#include "setup.h"
#include "statistics_accumulator.h"
#include "statistics_window.h"
 
#include <fcntl.h>
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
/**
 * @brief Asserts that one text file contains a required substring.
 */
 
static PetscErrorCode AssertFileContains(const char *path, const char *needle, const char *context)
{
    FILE *fp = NULL;
    long file_size = 0;
    char *buffer = NULL;
 
    PetscFunctionBeginUser;
    fp = fopen(path, "rb");
    if (!fp) {
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to open '%s' for assertion.", path);
    }
    if (fseek(fp, 0, SEEK_END) != 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to seek '%s'.", path);
    }
    file_size = ftell(fp);
    if (file_size < 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to measure '%s'.", path);
    }
    if (fseek(fp, 0, SEEK_SET) != 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to rewind '%s'.", path);
    }
 
    PetscCall(PetscMalloc1((size_t)file_size + 1, &buffer));
    if (file_size > 0) {
        size_t bytes_read = fread(buffer, 1, (size_t)file_size, fp);
        if (bytes_read != (size_t)file_size) {
            fclose(fp);
            PetscCall(PetscFree(buffer));
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to read '%s'.", path);
        }
    }
    buffer[file_size] = '\0';
    fclose(fp);
 
    PetscCall(PicurvAssertBool((PetscBool)(strstr(buffer, needle) != NULL), context));
    PetscCall(PetscFree(buffer));
    PetscFunctionReturn(0);
}
/**
 * @brief Asserts that one text file does not contain an excluded substring.
 */
 
static PetscErrorCode AssertFileNotContains(const char *path, const char *needle, const char *context)
{
    FILE *fp = NULL;
    long file_size = 0;
    char *buffer = NULL;
 
    PetscFunctionBeginUser;
    fp = fopen(path, "rb");
    if (!fp) {
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to open '%s' for assertion.", path);
    }
    if (fseek(fp, 0, SEEK_END) != 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to seek '%s'.", path);
    }
    file_size = ftell(fp);
    if (file_size < 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to measure '%s'.", path);
    }
    if (fseek(fp, 0, SEEK_SET) != 0) {
        fclose(fp);
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to rewind '%s'.", path);
    }
 
    PetscCall(PetscMalloc1((size_t)file_size + 1, &buffer));
    if (file_size > 0) {
        size_t bytes_read = fread(buffer, 1, (size_t)file_size, fp);
        if (bytes_read != (size_t)file_size) {
            fclose(fp);
            PetscCall(PetscFree(buffer));
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to read '%s'.", path);
        }
    }
    buffer[file_size] = '\0';
    fclose(fp);
 
    PetscCall(PicurvAssertBool((PetscBool)(strstr(buffer, needle) == NULL), context));
    PetscCall(PetscFree(buffer));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Reads the CSV header and the requested 1-based data row from a text file.
 */
static PetscErrorCode ReadCsvHeaderAndRow(const char *path,
                                          PetscInt row_index,
                                          char *header,
                                          size_t header_len,
                                          char *row,
                                          size_t row_len)
{
    FILE *fp = NULL;
    PetscInt current_row = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(path != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV path cannot be NULL.");
    PetscCheck(header != NULL && header_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV header buffer cannot be NULL or empty.");
    PetscCheck(row != NULL && row_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV row buffer cannot be NULL or empty.");
    PetscCheck(row_index >= 1, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "CSV row index must be >= 1.");
 
    fp = fopen(path, "r");
    PetscCheck(fp != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to open CSV '%s'.", path);
    PetscCheck(fgets(header, (int)header_len, fp) != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_READ, "CSV header missing in '%s'.", path);
 
    while (fgets(row, (int)row_len, fp) != NULL) {
        current_row++;
        if (current_row == row_index) {
            fclose(fp);
            PetscFunctionReturn(0);
        }
    }
 
    fclose(fp);
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_READ, "CSV '%s' does not contain data row %d.", path, (int)row_index);
}
 
/**
 * @brief Returns the zero-based column index for one CSV header field.
 */
static PetscErrorCode CsvFindColumnIndex(const char *header, const char *column_name, PetscInt *index_out)
{
    char local_header[4096];
    char *saveptr = NULL;
    char *token = NULL;
    PetscInt index = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(header != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV header cannot be NULL.");
    PetscCheck(column_name != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV column name cannot be NULL.");
    PetscCheck(index_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV column index output cannot be NULL.");
    PetscCheck(strlen(header) < sizeof(local_header), PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "CSV header is too long for the local parser buffer.");
 
    PetscCall(PetscStrncpy(local_header, header, sizeof(local_header)));
    token = strtok_r(local_header, ",\r\n", &saveptr);
    while (token != NULL) {
        if (strcmp(token, column_name) == 0) {
            *index_out = index;
            PetscFunctionReturn(0);
        }
        token = strtok_r(NULL, ",\r\n", &saveptr);
        index++;
    }
 
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "CSV column '%s' was not found.", column_name);
}
 
/**
 * @brief Extracts one CSV cell as text by header name.
 */
static PetscErrorCode CsvGetColumnText(const char *header,
                                       const char *row,
                                       const char *column_name,
                                       char *value,
                                       size_t value_len)
{
    char local_row[4096];
    char *saveptr = NULL;
    char *token = NULL;
    PetscInt target_index = -1;
    PetscInt index = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(row != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV row cannot be NULL.");
    PetscCheck(value != NULL && value_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV value buffer cannot be NULL or empty.");
    PetscCheck(strlen(row) < sizeof(local_row), PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "CSV row is too long for the local parser buffer.");
 
    PetscCall(CsvFindColumnIndex(header, column_name, &target_index));
    PetscCall(PetscStrncpy(local_row, row, sizeof(local_row)));
 
    token = strtok_r(local_row, ",\r\n", &saveptr);
    while (token != NULL) {
        if (index == target_index) {
            PetscCall(PetscStrncpy(value, token, value_len));
            PetscFunctionReturn(0);
        }
        token = strtok_r(NULL, ",\r\n", &saveptr);
        index++;
    }
 
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "CSV row is missing column '%s'.", column_name);
}
 
/**
 * @brief Extracts one CSV cell as an integer by header name.
 */
static PetscErrorCode CsvGetColumnInt(const char *header, const char *row, const char *column_name, PetscInt *value_out)
{
    char text[256];
    char *endptr = NULL;
    long parsed = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(value_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV integer output cannot be NULL.");
    PetscCall(CsvGetColumnText(header, row, column_name, text, sizeof(text)));
    parsed = strtol(text, &endptr, 10);
    PetscCheck(endptr != text, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "CSV column '%s' did not contain an integer.", column_name);
    *value_out = (PetscInt)parsed;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Extracts one CSV cell as a real by header name.
 */
static PetscErrorCode CsvGetColumnReal(const char *header, const char *row, const char *column_name, PetscReal *value_out)
{
    char text[256];
    char *endptr = NULL;
    double parsed = 0.0;
 
    PetscFunctionBeginUser;
    PetscCheck(value_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "CSV real output cannot be NULL.");
    PetscCall(CsvGetColumnText(header, row, column_name, text, sizeof(text)));
    parsed = strtod(text, &endptr);
    PetscCheck(endptr != text, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "CSV column '%s' did not contain a real value.", column_name);
    *value_out = (PetscReal)parsed;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Reads the column header and the requested 1-based data row from a
 *        pipe-delimited solution-convergence log file.
 *
 * Lines starting with '=' (banner) or '-' (separator) are skipped. The first
 * non-skipped line is treated as the column header; subsequent non-skipped
 * lines are data rows numbered from 1.
 */
static PetscErrorCode ReadLogHeaderAndRow(const char *path,
                                          PetscInt row_index,
                                          char *header,
                                          size_t header_len,
                                          char *row,
                                          size_t row_len)
{
    FILE      *fp = NULL;
    PetscInt   current_row = 0;
    char       line[8192];
    PetscBool  header_found = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PetscCheck(path != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log path cannot be NULL.");
    PetscCheck(header != NULL && header_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log header buffer cannot be NULL.");
    PetscCheck(row != NULL && row_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log row buffer cannot be NULL.");
    PetscCheck(row_index >= 1, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Log row index must be >= 1.");
 
    fp = fopen(path, "r");
    PetscCheck(fp != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to open log '%s'.", path);
 
    while (fgets(line, sizeof(line), fp) != NULL) {
        if (line[0] == '=' || line[0] == '-' || line[0] == '\n' || line[0] == '\r') continue;
        if (!header_found) {
            PetscCall(PetscStrncpy(header, line, header_len));
            header_found = PETSC_TRUE;
            continue;
        }
        current_row++;
        if (current_row == row_index) {
            PetscCall(PetscStrncpy(row, line, row_len));
            fclose(fp);
            PetscFunctionReturn(0);
        }
    }
 
    fclose(fp);
    if (!header_found) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_READ, "Log '%s' has no column header.", path);
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_READ, "Log '%s' does not contain data row %d.", path, (int)row_index);
}
 
/**
 * @brief Returns the zero-based column index for one pipe-delimited header field.
 */
static PetscErrorCode LogFindColumnIndex(const char *header, const char *column_name, PetscInt *index_out)
{
    char      local_header[8192];
    char     *saveptr = NULL;
    char     *token = NULL;
    PetscInt  index = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(header != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log header cannot be NULL.");
    PetscCheck(column_name != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log column name cannot be NULL.");
    PetscCheck(index_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log column index output cannot be NULL.");
 
    PetscCall(PetscStrncpy(local_header, header, sizeof(local_header)));
    token = strtok_r(local_header, "|\r\n", &saveptr);
    while (token != NULL) {
        while (*token == ' ') token++;
        char *end = token + strlen(token) - 1;
        while (end > token && (*end == ' ' || *end == '\r' || *end == '\n')) end--;
        *(end + 1) = '\0';
        if (strcmp(token, column_name) == 0) {
            *index_out = index;
            PetscFunctionReturn(0);
        }
        token = strtok_r(NULL, "|\r\n", &saveptr);
        index++;
    }
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Log column '%s' was not found.", column_name);
}
 
/**
 * @brief Extracts one pipe-delimited log cell as text by header name.
 */
static PetscErrorCode LogGetColumnText(const char *header,
                                       const char *row,
                                       const char *column_name,
                                       char *value,
                                       size_t value_len)
{
    char      local_row[8192];
    char     *saveptr = NULL;
    char     *token = NULL;
    PetscInt  target_index = -1;
    PetscInt  index = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(row != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log row cannot be NULL.");
    PetscCheck(value != NULL && value_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log value buffer cannot be NULL.");
 
    PetscCall(LogFindColumnIndex(header, column_name, &target_index));
    PetscCall(PetscStrncpy(local_row, row, sizeof(local_row)));
 
    token = strtok_r(local_row, "|\r\n", &saveptr);
    while (token != NULL) {
        if (index == target_index) {
            while (*token == ' ') token++;
            char *end = token + strlen(token) - 1;
            while (end > token && (*end == ' ' || *end == '\r' || *end == '\n')) end--;
            *(end + 1) = '\0';
            PetscCall(PetscStrncpy(value, token, value_len));
            PetscFunctionReturn(0);
        }
        token = strtok_r(NULL, "|\r\n", &saveptr);
        index++;
    }
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Log row is missing column '%s'.", column_name);
}
 
/**
 * @brief Extracts one pipe-delimited log cell as an integer by header name.
 */
static PetscErrorCode LogGetColumnInt(const char *header, const char *row, const char *column_name, PetscInt *value_out)
{
    char  text[256];
    char *endptr = NULL;
    long  parsed = 0;
 
    PetscFunctionBeginUser;
    PetscCheck(value_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log integer output cannot be NULL.");
    PetscCall(LogGetColumnText(header, row, column_name, text, sizeof(text)));
    parsed = strtol(text, &endptr, 10);
    PetscCheck(endptr != text, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Log column '%s' did not contain an integer.", column_name);
    *value_out = (PetscInt)parsed;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Extracts one pipe-delimited log cell as a real by header name.
 */
static PetscErrorCode LogGetColumnReal(const char *header, const char *row, const char *column_name, PetscReal *value_out)
{
    char   text[256];
    char  *endptr = NULL;
    double parsed = 0.0;
 
    PetscFunctionBeginUser;
    PetscCheck(value_out != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Log real output cannot be NULL.");
    PetscCall(LogGetColumnText(header, row, column_name, text, sizeof(text)));
    parsed = strtod(text, &endptr);
    PetscCheck(endptr != text, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Log column '%s' did not contain a real value.", column_name);
    *value_out = (PetscReal)parsed;
    PetscFunctionReturn(0);
}
 
typedef PetscErrorCode (*CapturedLoggingFn)(UserCtx *user, SimCtx *simCtx, void *ctx);
 
typedef struct AnatomyCaptureCtx {
    FieldId field_id;
    const char *stage_name;
} AnatomyCaptureCtx;
 
/**
 * @brief Captures stdout emitted by one logging helper into a temporary file-backed buffer.
 */
static PetscErrorCode CaptureLoggingOutput(UserCtx *user,
                                           SimCtx *simCtx,
                                           CapturedLoggingFn fn,
                                           void *ctx,
                                           char *captured,
                                           size_t captured_len)
{
    char tmpdir[PETSC_MAX_PATH_LEN];
    char capture_path[PETSC_MAX_PATH_LEN];
    FILE *capture_file = NULL;
    int saved_stdout = -1;
    int capture_fd = -1;
    size_t bytes_read = 0;
    PetscErrorCode ierr;
 
    PetscFunctionBeginUser;
    PetscCheck(fn != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Capture callback cannot be NULL.");
    PetscCheck(captured != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Capture buffer cannot be NULL.");
    PetscCheck(captured_len > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "Capture buffer must be non-empty.");
 
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscSNPrintf(capture_path, sizeof(capture_path), "%s/logging.out", tmpdir));
 
    fflush(stdout);
    saved_stdout = dup(STDOUT_FILENO);
    PetscCheck(saved_stdout >= 0, PETSC_COMM_SELF, PETSC_ERR_SYS, "dup(STDOUT_FILENO) failed.");
    capture_fd = open(capture_path, O_CREAT | O_TRUNC | O_WRONLY, 0600);
    PetscCheck(capture_fd >= 0, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to open capture file '%s'.", capture_path);
    PetscCheck(dup2(capture_fd, STDOUT_FILENO) >= 0, PETSC_COMM_SELF, PETSC_ERR_SYS, "dup2() failed while redirecting stdout.");
    close(capture_fd);
    capture_fd = -1;
 
    ierr = fn(user, simCtx, ctx);
    fflush(stdout);
    PetscCheck(dup2(saved_stdout, STDOUT_FILENO) >= 0, PETSC_COMM_SELF, PETSC_ERR_SYS, "dup2() failed while restoring stdout.");
    close(saved_stdout);
    saved_stdout = -1;
    PetscCall(ierr);
 
    capture_file = fopen(capture_path, "r");
    PetscCheck(capture_file != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to read capture file '%s'.", capture_path);
    bytes_read = fread(captured, 1, captured_len - 1, capture_file);
    captured[bytes_read] = '\0';
    fclose(capture_file);
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Adapts `LOG_PARTICLE_FIELDS()` to the generic stdout-capture callback shape.
 */
static PetscErrorCode InvokeParticleFieldLog(UserCtx *user, SimCtx *simCtx, void *ctx)
{
    PetscInt print_interval = *((PetscInt *)ctx);
 
    PetscFunctionBeginUser;
    (void)simCtx;
    PetscCall(LOG_PARTICLE_FIELDS(user, print_interval));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Adapts `EmitParticleConsoleSnapshot()` to the generic stdout-capture callback shape.
 */
static PetscErrorCode InvokeParticleConsoleSnapshot(UserCtx *user, SimCtx *simCtx, void *ctx)
{
    PetscInt step = *((PetscInt *)ctx);
 
    PetscFunctionBeginUser;
    PetscCall(EmitParticleConsoleSnapshot(user, simCtx, step));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Adapts `EmitStatisticsConsoleSnapshot()` to the generic stdout-capture callback shape.
 */
static PetscErrorCode InvokeStatisticsConsoleSnapshot(UserCtx *user, SimCtx *simCtx, void *ctx)
{
    PetscInt step = *((PetscInt *)ctx);
 
    PetscFunctionBeginUser;
    PetscCall(EmitStatisticsConsoleSnapshot(user, simCtx, step));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Adapts `LOG_FIELD_ANATOMY()` to the generic stdout-capture callback shape.
 */
static PetscErrorCode InvokeFieldAnatomyLog(UserCtx *user, SimCtx *simCtx, void *ctx)
{
    const AnatomyCaptureCtx *anatomy_ctx = (const AnatomyCaptureCtx *)ctx;
 
    PetscFunctionBeginUser;
    (void)simCtx;
    PetscCall(LOG_FIELD_ANATOMY(user, anatomy_ctx->field_id, anatomy_ctx->stage_name));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Creates a small particle-bearing runtime fixture used by logging tests.
 */
static PetscErrorCode SeedLoggingParticleFixture(SimCtx **simCtx_out, UserCtx **user_out)
{
    PetscReal *positions = NULL;
    PetscReal *velocities = NULL;
    PetscReal *weights = NULL;
    PetscInt *cell_ids = NULL;
    PetscInt *status = NULL;
    PetscReal *psi = NULL;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(simCtx_out, user_out, 4, 4, 4));
    PetscCall(PicurvCreateSwarmPair(*user_out, 2, "ske"));
    (*simCtx_out)->np = 2;
    (*simCtx_out)->particleConsoleOutputFreq = 2;
    (*simCtx_out)->LoggingFrequency = 1;
 
    PetscCall(DMSwarmGetField((*user_out)->swarm, "position", NULL, NULL, (void **)&positions));
    PetscCall(DMSwarmGetField((*user_out)->swarm, "velocity", NULL, NULL, (void **)&velocities));
    PetscCall(DMSwarmGetField((*user_out)->swarm, "weight", NULL, NULL, (void **)&weights));
    PetscCall(DMSwarmGetField((*user_out)->swarm, "DMSwarm_CellID", NULL, NULL, (void **)&cell_ids));
    PetscCall(DMSwarmGetField((*user_out)->swarm, "DMSwarm_location_status", NULL, NULL, (void **)&status));
    PetscCall(DMSwarmGetField((*user_out)->swarm, "Psi", NULL, NULL, (void **)&psi));
 
    positions[0] = 0.25; positions[1] = 0.50; positions[2] = 0.75;
    positions[3] = 0.50; positions[4] = 0.50; positions[5] = 0.50;
    velocities[0] = 1.0; velocities[1] = 2.0; velocities[2] = 3.0;
    velocities[3] = 4.0; velocities[4] = 5.0; velocities[5] = 6.0;
    weights[0] = 0.2; weights[1] = 0.3; weights[2] = 0.4;
    weights[3] = 0.5; weights[4] = 0.5; weights[5] = 0.5;
    cell_ids[0] = 0; cell_ids[1] = 0; cell_ids[2] = 0;
    cell_ids[3] = 1; cell_ids[4] = 1; cell_ids[5] = 1;
    status[0] = ACTIVE_AND_LOCATED;
    status[1] = ACTIVE_AND_LOCATED;
    psi[0] = 1.0;
    psi[1] = 3.0;
 
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "Psi", NULL, NULL, (void **)&psi));
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "DMSwarm_location_status", NULL, NULL, (void **)&status));
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "DMSwarm_CellID", NULL, NULL, (void **)&cell_ids));
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "weight", NULL, NULL, (void **)&weights));
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "velocity", NULL, NULL, (void **)&velocities));
    PetscCall(DMSwarmRestoreField((*user_out)->swarm, "position", NULL, NULL, (void **)&positions));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Fills one Cartesian velocity field with a uniform constant state.
 */
static PetscErrorCode SetUniformVelocityField(UserCtx *user, Vec field, PetscReal ux, PetscReal uy, PetscReal uz)
{
    Cmpnts ***arr = NULL;
 
    PetscFunctionBeginUser;
    PetscCheck(user != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx cannot be NULL.");
    PetscCheck(field != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Velocity field cannot be NULL.");
 
    PetscCall(DMDAVecGetArray(user->fda, field, &arr));
    for (PetscInt k = user->info.zs; k < user->info.zs + user->info.zm; ++k) {
        for (PetscInt j = user->info.ys; j < user->info.ys + user->info.ym; ++j) {
            for (PetscInt i = user->info.xs; i < user->info.xs + user->info.xm; ++i) {
                arr[k][j][i].x = ux;
                arr[k][j][i].y = uy;
                arr[k][j][i].z = uz;
            }
        }
    }
    PetscCall(DMDAVecRestoreArray(user->fda, field, &arr));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Fills one scalar field with a uniform constant state.
 */
static PetscErrorCode SetUniformScalarField(UserCtx *user, Vec field, PetscReal value)
{
    PetscReal ***arr = NULL;
 
    PetscFunctionBeginUser;
    PetscCheck(user != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx cannot be NULL.");
    PetscCheck(field != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Scalar field cannot be NULL.");
 
    PetscCall(DMDAVecGetArray(user->da, field, &arr));
    for (PetscInt k = user->info.zs; k < user->info.zs + user->info.zm; ++k) {
        for (PetscInt j = user->info.ys; j < user->info.ys + user->info.ym; ++j) {
            for (PetscInt i = user->info.xs; i < user->info.xs + user->info.xm; ++i) {
                arr[k][j][i] = value;
            }
        }
    }
    PetscCall(DMDAVecRestoreArray(user->da, field, &arr));
    PetscFunctionReturn(0);
}
/**
 * @brief Fills one Cartesian velocity field with u=0, v=v_amp*sin(2π*k/km), w=w_const.
 *
 * Sets the sinusoidal profile at ALL owned nodes (including the periodic duplicate endpoint),
 * matching how the IC routines populate fields before any periodic-endpoint fix is applied.
 */
static PetscErrorCode SetSinusoidalVZField(UserCtx *user, Vec field, PetscReal v_amp, PetscReal w_const)
{
    Cmpnts   ***arr = NULL;
    /* Production layout: physical cells occupy 1..mz-2; 0 and mz-1 are ghost layers,
       which on a periodic axis hold copies of the opposite physical cell. */
    const PetscInt ncells = user->info.mz - 2;
 
    PetscFunctionBeginUser;
    PetscCheck(user != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx cannot be NULL.");
    PetscCheck(field != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Velocity field cannot be NULL.");
 
    PetscCall(DMDAVecGetArray(user->fda, field, &arr));
    for (PetscInt k = user->info.zs; k < user->info.zs + user->info.zm; ++k) {
        const PetscInt  cell = (k == 0) ? ncells : (k == user->info.mz - 1) ? 1 : k;
        PetscReal z_phase = (2.0 * PETSC_PI * (PetscReal)(cell - 1)) / (PetscReal)ncells;
        for (PetscInt j = user->info.ys; j < user->info.ys + user->info.ym; ++j) {
            for (PetscInt i = user->info.xs; i < user->info.xs + user->info.xm; ++i) {
                arr[k][j][i].x = 0.0;
                arr[k][j][i].y = v_amp * PetscSinReal(z_phase);
                arr[k][j][i].z = w_const;
            }
        }
    }
    PetscCall(DMDAVecRestoreArray(user->fda, field, &arr));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Tests string-conversion helpers for configured enums and unknown values.
 */
 
static PetscErrorCode TestStringConversionHelpers(void)
{
    PetscFunctionBeginUser;
    PetscCall(PicurvAssertBool(strcmp(BCFaceToString(BC_FACE_NEG_X), "-Xi (I-Min)") == 0,
                               "BCFaceToString should report the negative-x face"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString(IC_MODE_ZERO), "Zero") == 0,
                               "InitialConditionModeToString should report the zero mode"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString(IC_MODE_CONSTANT_CARTESIAN), "Cartesian Constant") == 0,
                               "InitialConditionModeToString should report the Cartesian constant mode"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString(IC_MODE_CONSTANT_STREAMWISE), "Streamwise Constant") == 0,
                               "InitialConditionModeToString should report the streamwise constant mode"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString(IC_MODE_POISEUILLE), "Poiseuille") == 0,
                               "InitialConditionModeToString should report the Poiseuille mode"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString(IC_MODE_FILE), "File") == 0,
                               "InitialConditionModeToString should report the file mode"));
    PetscCall(PicurvAssertBool(strcmp(InitialConditionModeToString((InitialConditionMode)99), "Unknown Initial Condition") == 0,
                               "InitialConditionModeToString should reject unknown selectors"));
    PetscCall(PicurvAssertBool(strcmp(ParticleInitializationToString(PARTICLE_INIT_VOLUME), "Volume") == 0,
                               "ParticleInitializationToString should report the volume mode"));
    PetscCall(PicurvAssertBool(strcmp(LESModelToString(CONSTANT_SMAGORINSKY), "Constant Smagorinsky") == 0,
                               "LESModelToString should report the constant model"));
    PetscCall(PicurvAssertBool(strcmp(MomentumSolverTypeToString(MOMENTUM_SOLVER_EXPLICIT_RK), "Explicit 4 stage Runge-Kutta ") == 0,
                               "MomentumSolverTypeToString should report the explicit solver"));
    PetscCall(PicurvAssertBool(strcmp(MomentumSolverTypeToString(MOMENTUM_SOLVER_NEWTON_KRYLOV), "Newton Krylov") == 0,
                               "MomentumSolverTypeToString should report the Newton Krylov solver"));
    PetscCall(PicurvAssertBool(strcmp(BCTypeToString(PERIODIC), "PERIODIC") == 0,
                               "BCTypeToString should report periodic boundaries"));
    PetscCall(PicurvAssertBool(strcmp(BCHandlerTypeToString(BC_HANDLER_PERIODIC_DRIVEN_CONSTANT_FLUX), "constant flux") == 0,
                               "BCHandlerTypeToString should report the driven periodic handler"));
    PetscCall(PicurvAssertBool(strcmp(ParticleLocationStatusToString(LOST), "LOST") == 0,
                               "ParticleLocationStatusToString should report LOST state"));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests that log level selection honors the environment variable.
 */
 
static PetscErrorCode TestGetLogLevelFromEnvironment(void)
{
    PetscFunctionBeginUser;
    PetscCall(PicurvAssertIntEqual(LOG_INFO, get_log_level(),
                                   "get_log_level should honor LOG_LEVEL=INFO in this test binary"));
    PetscCall(print_log_level());
    PetscFunctionReturn(0);
}
/**
 * @brief Tests the function allow-list filter used by the logging layer.
 */
 
static PetscErrorCode TestAllowedFunctionsFilter(void)
{
    const char *allow_list[] = {"ComputeSpecificKE", "WriteEulerianFile"};
 
    PetscFunctionBeginUser;
    set_allowed_functions(allow_list, 2);
    PetscCall(PicurvAssertBool(is_function_allowed("ComputeSpecificKE"),
                               "Allowed list should include ComputeSpecificKE"));
    PetscCall(PicurvAssertBool((PetscBool)!is_function_allowed("UnlistedFunction"),
                               "Allowed list should exclude unknown function names"));
 
    set_allowed_functions(NULL, 0);
    PetscCall(PicurvAssertBool(is_function_allowed("AnyFunction"),
                               "Empty allow-list should permit all functions"));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests periodic particle console snapshot enablement and cadence.
 */
 
static PetscErrorCode TestParticleConsoleSnapshotCadence(void)
{
    SimCtx simCtx;
 
    PetscFunctionBeginUser;
    PetscCall(PetscMemzero(&simCtx, sizeof(simCtx)));
    simCtx.np = 32;
    simCtx.particleConsoleOutputFreq = 4;
 
    PetscCall(PicurvAssertBool(IsParticleConsoleSnapshotEnabled(&simCtx),
                               "Particle snapshot contract should be enabled when particles and cadence are configured"));
    PetscCall(PicurvAssertBool(ShouldEmitPeriodicParticleConsoleSnapshot(&simCtx, 8),
                               "Snapshot should emit on cadence-aligned completed steps"));
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicParticleConsoleSnapshot(&simCtx, 7),
                               "Snapshot should not emit off-cadence"));
 
    simCtx.particleConsoleOutputFreq = 0;
    PetscCall(PicurvAssertBool((PetscBool)!IsParticleConsoleSnapshotEnabled(&simCtx),
                               "Zero cadence should disable periodic particle snapshots"));
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicParticleConsoleSnapshot(NULL, 4),
                               "NULL SimCtx should never emit periodic snapshots"));
    PetscFunctionReturn(0);
}
/**
 * @brief Builds the window definition backing this suite's statistics console fixture.
 *
 * One bounded pressure window on a per-step cadence: bounded so the snapshot exercises
 * its percentage-progress branch, and a single field so the fixture stays cheap.
 */
static PicurvWindowDefinition LoggingStatisticsDefinition(void)
{
    PicurvWindowDefinition definition;
 
    memset(&definition, 0, sizeof(definition));
    strncpy(definition.name, "console_window", PICURV_WINDOW_NAME_LENGTH - 1);
    definition.weighting = PICURV_WEIGHTING_SAMPLE;
    definition.cadence_kind = PICURV_CADENCE_STEP;
    definition.step_cadence = 1;
    definition.bounded = PETSC_TRUE;
    definition.end_time = 4.0;
    definition.field_count = 1;
    definition.fields[0].field_id = FIELD_ID_P;
    return definition;
}
/**
 * @brief Tests periodic statistics console snapshot enablement and cadence.
 */
 
static PetscErrorCode TestStatisticsConsoleSnapshotCadence(void)
{
    SimCtx simCtx;
    PicurvWindow window;
    PicurvWindowDefinition definition = LoggingStatisticsDefinition();
 
    PetscFunctionBeginUser;
    PetscCall(PetscMemzero(&simCtx, sizeof(simCtx)));
    PetscCall(PicurvWindowInit(&window, &definition));
    simCtx.fieldStatisticsEnabled = PETSC_TRUE;
    simCtx.fieldStatisticsWindowCount = 1;
    simCtx.fieldStatisticsWindows = &window;
    simCtx.statisticsConsoleOutputFreq = 4;
 
    PetscCall(PicurvAssertBool(IsStatisticsConsoleSnapshotEnabled(&simCtx),
                               "Statistics snapshot contract should be enabled when a window and cadence are configured"));
    PetscCall(PicurvAssertBool(ShouldEmitPeriodicStatisticsConsoleSnapshot(&simCtx, 8),
                               "Snapshot should emit on cadence-aligned completed steps"));
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicStatisticsConsoleSnapshot(&simCtx, 7),
                               "Snapshot should not emit off-cadence"));
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicStatisticsConsoleSnapshot(&simCtx, -1),
                               "Snapshot should not emit for a step that has not completed"));
 
    simCtx.statisticsConsoleOutputFreq = 0;
    PetscCall(PicurvAssertBool((PetscBool)!IsStatisticsConsoleSnapshotEnabled(&simCtx),
                               "Zero cadence should disable periodic statistics snapshots"));
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicStatisticsConsoleSnapshot(&simCtx, 0),
                               "Zero cadence should not emit even on the step that opens a run"));
 
    /* The console cadence is a reporting contract layered on the subsystem gate: with
     * nothing accumulating there is nothing to report, whatever the cadence says. */
    simCtx.statisticsConsoleOutputFreq = 4;
    simCtx.fieldStatisticsWindowCount = 0;
    PetscCall(PicurvAssertBool((PetscBool)!IsStatisticsConsoleSnapshotEnabled(&simCtx),
                               "A configured cadence should not enable snapshots without an accumulating window"));
 
    simCtx.fieldStatisticsWindowCount = 1;
    simCtx.fieldStatisticsEnabled = PETSC_FALSE;
    PetscCall(PicurvAssertBool((PetscBool)!IsStatisticsConsoleSnapshotEnabled(&simCtx),
                               "A disabled subsystem should not emit statistics snapshots"));
 
    PetscCall(PicurvAssertBool((PetscBool)!ShouldEmitPeriodicStatisticsConsoleSnapshot(NULL, 4),
                               "NULL SimCtx should never emit periodic snapshots"));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests logging-side file parsing, helper formatting, and progress utilities.
 */
 
static PetscErrorCode TestLoggingFileParsingAndFormattingHelpers(void)
{
    char tmpdir[PETSC_MAX_PATH_LEN];
    char allow_path[PETSC_MAX_PATH_LEN];
    char dual_log_path[PETSC_MAX_PATH_LEN];
    FILE *file = NULL;
    char **funcs = NULL;
    PetscInt nfuncs = 0;
    Cell cell;
    PetscReal distances[6] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
    DualMonitorCtx *monctx = NULL;
    void *ctx = NULL;
 
    PetscFunctionBeginUser;
    PetscCall(PetscMemzero(&cell, sizeof(cell)));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscSNPrintf(allow_path, sizeof(allow_path), "%s/allowed_functions.txt", tmpdir));
    PetscCall(PetscSNPrintf(dual_log_path, sizeof(dual_log_path), "%s/dual-monitor.log", tmpdir));
 
    file = fopen(allow_path, "w");
    PetscCheck(file != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to create allow-list file '%s'.", allow_path);
    fputs("  ComputeSpecificKE  \n", file);
    fputs("# comment-only line\n", file);
    for (PetscInt i = 0; i < 17; ++i) {
        fprintf(file, "Helper_%02d   # trailing comment\n", (int)i);
    }
    fclose(file);
    file = NULL;
 
    PetscCall(LoadAllowedFunctionsFromFile(allow_path, &funcs, &nfuncs));
    PetscCall(PicurvAssertIntEqual(18, nfuncs, "LoadAllowedFunctionsFromFile should trim comments and keep all identifiers"));
    PetscCall(PicurvAssertBool((PetscBool)(strcmp(funcs[0], "ComputeSpecificKE") == 0),
                               "LoadAllowedFunctionsFromFile should trim leading and trailing whitespace"));
    PetscCall(PicurvAssertBool((PetscBool)(strcmp(funcs[17], "Helper_16") == 0),
                               "LoadAllowedFunctionsFromFile should grow past the initial pointer capacity"));
    PetscCall(FreeAllowedFunctions(funcs, nfuncs));
 
    for (PetscInt i = 0; i < 8; ++i) {
        cell.vertices[i].x = (PetscReal)i;
        cell.vertices[i].y = (PetscReal)(i + 1);
        cell.vertices[i].z = (PetscReal)(i + 2);
    }
    PetscCall(LOG_CELL_VERTICES(&cell, 0));
    PetscCall(LOG_FACE_DISTANCES(distances));
 
    PetscCall(PetscCalloc1(1, &monctx));
    monctx->file_handle = fopen(dual_log_path, "w");
    PetscCheck(monctx->file_handle != NULL, PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Failed to create dual-monitor log '%s'.", dual_log_path);
    ctx = monctx;
    PetscCall(DualMonitorDestroy(&ctx));
    PetscCall(PicurvAssertBool((PetscBool)(ctx == NULL),
                               "DualMonitorDestroy should clear the caller-owned context pointer"));
 
    PrintProgressBar(0, 0, 4, 0.10);
    PrintProgressBar(3, 0, 4, 0.40);
    PrintProgressBar(0, 0, 0, 0.00);
    PetscCall(PetscPrintf(PETSC_COMM_SELF, "\n"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests continuity, min/max, and anatomy logging helpers on minimal runtime fixtures.
 */
 
static PetscErrorCode TestLoggingContinuityAndFieldDiagnostics(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char continuity_path[PETSC_MAX_PATH_LEN];
    PetscReal ***p = NULL;
    Cmpnts ***ucat = NULL;
    Cmpnts ***ucont = NULL;
    PetscErrorCode ierr_minmax = 0;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
 
    simCtx->StartStep = 0;
    simCtx->step = 1;
    simCtx->MaxDiv = 1.25;
    simCtx->MaxDivx = 1;
    simCtx->MaxDivy = 2;
    simCtx->MaxDivz = 3;
    simCtx->MaxDivFlatArg = 17;
    simCtx->poissonSourceImbalance = 8.5;
    simCtx->FluxInSum = 5.0;
    simCtx->FluxOutSum = 3.25;
    PetscCall(LOG_CONTINUITY_METRICS(user));
 
    simCtx->step = 2;
    simCtx->MaxDiv = 0.75;
    simCtx->poissonSourceImbalance = 4.5;
    simCtx->FluxInSum = 2.5;
    simCtx->FluxOutSum = 1.0;
    PetscCall(LOG_CONTINUITY_METRICS(user));
 
    PetscCall(PetscSNPrintf(continuity_path, sizeof(continuity_path), "%s/Continuity_Metrics.log", simCtx->log_dir));
    PetscCall(PicurvAssertFileExists(continuity_path, "continuity metrics log should be written"));
    PetscCall(AssertFileContains(continuity_path, "Timestep", "continuity metrics log should include the header"));
    PetscCall(AssertFileContains(continuity_path, "([3][2][1] = 17)", "continuity metrics log should include the divergence location"));
    PetscCall(AssertFileContains(continuity_path, "2          | 0", "continuity metrics log should append later timesteps"));
 
    PetscCall(DMDAVecGetArray(user->da, user->P, &p));
    PetscCall(DMDAVecGetArray(user->fda, user->Ucat, &ucat));
    PetscCall(DMDAVecGetArray(user->fda, user->Ucont, &ucont));
    for (PetscInt k = user->info.zs; k < user->info.zs + user->info.zm; ++k) {
        for (PetscInt j = user->info.ys; j < user->info.ys + user->info.ym; ++j) {
            for (PetscInt i = user->info.xs; i < user->info.xs + user->info.xm; ++i) {
                p[k][j][i] = (PetscReal)(i + j + k);
                ucat[k][j][i].x = (PetscReal)i;
                ucat[k][j][i].y = (PetscReal)(-j);
                ucat[k][j][i].z = (PetscReal)(2 * k);
                ucont[k][j][i].x = (PetscReal)(10 + i);
                ucont[k][j][i].y = (PetscReal)(20 + j);
                ucont[k][j][i].z = (PetscReal)(30 + k);
            }
        }
    }
    PetscCall(DMDAVecRestoreArray(user->fda, user->Ucont, &ucont));
    PetscCall(DMDAVecRestoreArray(user->fda, user->Ucat, &ucat));
    PetscCall(DMDAVecRestoreArray(user->da, user->P, &p));
 
    PetscCall(DMGlobalToLocalBegin(user->da, user->P, INSERT_VALUES, user->lP));
    PetscCall(DMGlobalToLocalEnd(user->da, user->P, INSERT_VALUES, user->lP));
    PetscCall(DMGlobalToLocalBegin(user->fda, user->Ucat, INSERT_VALUES, user->lUcat));
    PetscCall(DMGlobalToLocalEnd(user->fda, user->Ucat, INSERT_VALUES, user->lUcat));
    PetscCall(DMGlobalToLocalBegin(user->fda, user->Ucont, INSERT_VALUES, user->lUcont));
    PetscCall(DMGlobalToLocalEnd(user->fda, user->Ucont, INSERT_VALUES, user->lUcont));
 
    PetscCall(LOG_FIELD_MIN_MAX(user, FIELD_ID_P));
    PetscCall(LOG_FIELD_MIN_MAX(user, FIELD_ID_UCAT));
    PetscCall(LOG_FIELD_MIN_MAX(user, FIELD_ID_COORDINATES));
    PetscCall(LOG_FIELD_MIN_MAX(user, FIELD_ID_UCONT));
 
    PetscCall(PetscPushErrorHandler(PetscIgnoreErrorHandler, NULL));
    ierr_minmax = LOG_FIELD_MIN_MAX(user, FIELD_ID_INVALID);
    PetscCall(PetscPopErrorHandler());
    PetscCall(PicurvAssertBool((PetscBool)(ierr_minmax != 0),
                               "LOG_FIELD_MIN_MAX should reject invalid field IDs"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests interpolation-error logging against an analytically matched particle field.
 */
 
static PetscErrorCode TestInterpolationErrorLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    PetscReal (*pos_arr)[3] = NULL;
    PetscReal (*vel_arr)[3] = NULL;
    Vec position_vec = NULL;
    Vec analytical_vec = NULL;
    const PetscScalar *analytical_arr = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char metrics_path[PETSC_MAX_PATH_LEN];
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvCreateSwarmPair(user, 2, "ske"));
    PetscCall(PetscStrncpy(simCtx->AnalyticalSolutionType, "TGV3D", sizeof(simCtx->AnalyticalSolutionType)));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->analysis_dir, tmpdir, sizeof(simCtx->analysis_dir)));
    simCtx->ren = 1.0;
    /* ti is physical time, not a step count. The CSV once wrote ti * dt, which read
       2.5e-03 here instead of 0.25. */
    simCtx->step = 25;
    simCtx->dt = 0.01;
    simCtx->ti = 0.25;
 
    PetscCall(DMSwarmGetField(user->swarm, "position", NULL, NULL, (void *)&pos_arr));
    pos_arr[0][0] = 0.5 * PETSC_PI; pos_arr[0][1] = 0.0;          pos_arr[0][2] = 0.0;
    pos_arr[1][0] = 0.0;           pos_arr[1][1] = 0.5 * PETSC_PI; pos_arr[1][2] = 0.0;
    PetscCall(DMSwarmRestoreField(user->swarm, "position", NULL, NULL, (void *)&pos_arr));
 
    PetscCall(DMSwarmCreateGlobalVectorFromField(user->swarm, "position", &position_vec));
    PetscCall(VecDuplicate(position_vec, &analytical_vec));
    PetscCall(VecCopy(position_vec, analytical_vec));
    PetscCall(SetAnalyticalSolutionForParticles(analytical_vec, simCtx));
 
    PetscCall(DMSwarmGetField(user->swarm, "velocity", NULL, NULL, (void *)&vel_arr));
    PetscCall(VecGetArrayRead(analytical_vec, &analytical_arr));
    for (PetscInt particle = 0; particle < 2; ++particle) {
        vel_arr[particle][0] = PetscRealPart(analytical_arr[3 * particle + 0]);
        vel_arr[particle][1] = PetscRealPart(analytical_arr[3 * particle + 1]);
        vel_arr[particle][2] = PetscRealPart(analytical_arr[3 * particle + 2]);
    }
    PetscCall(VecRestoreArrayRead(analytical_vec, &analytical_arr));
    PetscCall(DMSwarmRestoreField(user->swarm, "velocity", NULL, NULL, (void *)&vel_arr));
 
    PetscCall(VecDestroy(&analytical_vec));
    PetscCall(DMSwarmDestroyGlobalVectorFromField(user->swarm, "position", &position_vec));
    PetscCall(LOG_INTERPOLATION_ERROR(user));
 
    PetscCall(PetscSNPrintf(metrics_path, sizeof(metrics_path), "%s/interpolation_error.csv", simCtx->analysis_dir));
    PetscCall(PicurvAssertFileExists(metrics_path, "LOG_INTERPOLATION_ERROR should write interpolation_error.csv"));
    PetscCall(AssertFileContains(metrics_path, "25,2.500000e-01,",
                                 "interpolation_error.csv should record physical time, not time multiplied by dt"));
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests file-backed scatter metrics logging against a fully occupied constant field.
 */
 
static PetscErrorCode TestScatterMetricsLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char metrics_path[PETSC_MAX_PATH_LEN];
    PetscReal *positions = NULL;
    PetscReal *psi = NULL;
    PetscInt *cell_ids = NULL;
    PetscInt *status = NULL;
    PetscInt particle = 0;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvCreateSwarmPair(user, 27, "ske"));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->np = 27;
    simCtx->step = 3;
    simCtx->ti = 0.3;
    simCtx->verificationScalar.enabled = PETSC_TRUE;
    PetscCall(PetscStrncpy(simCtx->verificationScalar.mode,
                           "analytical",
                           sizeof(simCtx->verificationScalar.mode)));
    PetscCall(PetscStrncpy(simCtx->verificationScalar.profile,
                           "CONSTANT",
                           sizeof(simCtx->verificationScalar.profile)));
    simCtx->verificationScalar.value = 2.0;
 
    PetscCall(DMSwarmGetField(user->swarm, "position", NULL, NULL, (void **)&positions));
    PetscCall(DMSwarmGetField(user->swarm, "DMSwarm_CellID", NULL, NULL, (void **)&cell_ids));
    PetscCall(DMSwarmGetField(user->swarm, "DMSwarm_location_status", NULL, NULL, (void **)&status));
    PetscCall(DMSwarmGetField(user->swarm, "Psi", NULL, NULL, (void **)&psi));
 
    for (PetscInt k = 0; k < 3; ++k) {
        for (PetscInt j = 0; j < 3; ++j) {
            for (PetscInt i = 0; i < 3; ++i) {
                positions[3 * particle + 0] = (i + 0.5) / 4.0;
                positions[3 * particle + 1] = (j + 0.5) / 4.0;
                positions[3 * particle + 2] = (k + 0.5) / 4.0;
                cell_ids[3 * particle + 0] = i;
                cell_ids[3 * particle + 1] = j;
                cell_ids[3 * particle + 2] = k;
                status[particle] = ACTIVE_AND_LOCATED;
                psi[particle] = 2.0;
                ++particle;
            }
        }
    }
 
    PetscCall(DMSwarmRestoreField(user->swarm, "Psi", NULL, NULL, (void **)&psi));
    PetscCall(DMSwarmRestoreField(user->swarm, "DMSwarm_location_status", NULL, NULL, (void **)&status));
    PetscCall(DMSwarmRestoreField(user->swarm, "DMSwarm_CellID", NULL, NULL, (void **)&cell_ids));
    PetscCall(DMSwarmRestoreField(user->swarm, "position", NULL, NULL, (void **)&positions));
 
    PetscCall(ScatterAllParticleFieldsToEulerFields(user));
    PetscCall(LOG_SCATTER_METRICS(user));
 
    PetscCall(PetscSNPrintf(metrics_path, sizeof(metrics_path), "%s/scatter_metrics.csv", simCtx->analysis_dir));
    PetscCall(PicurvAssertFileExists(metrics_path, "LOG_SCATTER_METRICS should write scatter_metrics.csv"));
    PetscCall(AssertFileContains(metrics_path, "relative_L2_error",
                                 "Scatter metrics CSV header should include relative_L2_error"));
    PetscCall(AssertFileContains(metrics_path,
                                 "3,3.000000e-01,27,27,27,1.000000e+00,1.000000e+00,5.400000e+01,5.400000e+01,0.000000e+00,0.000000e+00,0.000000e+00,0.000000e+00,0.000000e+00",
                                 "Scatter metrics CSV should record the expected constant-field zero-error row"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests stdout particle-table logging on a production-like swarm fixture.
 */
 
static PetscErrorCode TestParticleFieldTableLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    PetscInt print_interval = 1;
    char captured[8192];
 
    PetscFunctionBeginUser;
    PetscCall(SeedLoggingParticleFixture(&simCtx, &user));
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeParticleFieldLog, &print_interval, captured, sizeof(captured)));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Position (x,y,z)") != NULL),
                               "LOG_PARTICLE_FIELDS should print the particle table header"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Weights (a1,a2,a3)") != NULL),
                               "LOG_PARTICLE_FIELDS should print the weight-column header"));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests console snapshot logging against the public periodic-snapshot helper.
 */
 
static PetscErrorCode TestParticleConsoleSnapshotLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    PetscInt step = 4;
    char captured[8192];
 
    PetscFunctionBeginUser;
    PetscCall(SeedLoggingParticleFixture(&simCtx, &user));
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeParticleConsoleSnapshot, &step, captured, sizeof(captured)));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Particle states at step 4") != NULL),
                               "EmitParticleConsoleSnapshot should print the step banner"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Position (x,y,z)") != NULL),
                               "EmitParticleConsoleSnapshot should reuse the particle table output"));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests statistics console snapshot content, and its silence when disabled.
 *
 * Covers both halves of the monitoring contract from one fixture: an active window
 * reports its window-level scalars, and the identical call on a disabled subsystem
 * writes nothing at all, which is the observable form of the gate the runloop relies
 * on to keep a non-statistics run's log untouched.
 */
 
static PetscErrorCode TestStatisticsConsoleSnapshotLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    PicurvWindow window;
    PicurvWindowStorage storage;
    PicurvWindowDefinition definition = LoggingStatisticsDefinition();
    PetscInt step = 2;
    char captured[8192];
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(VecSet(user->Nvert, 0.0));
    PetscCall(PicurvWindowInit(&window, &definition));
    PetscCall(PicurvWindowStorageCreate(user, &definition, &storage));
 
    simCtx->fieldStatisticsEnabled = PETSC_TRUE;
    simCtx->fieldStatisticsWindowCount = 1;
    simCtx->fieldStatisticsWindows = &window;
    simCtx->statisticsConsoleOutputFreq = 1;
    user->fieldStatisticsStorage = &storage;
 
    /* Step 0 anchors the origin without sampling; steps 1 and 2 each represent one
     * unit of time, so the snapshot has two accepted samples to report. */
    for (PetscInt offered = 0; offered <= step; ++offered) {
        PetscCall(FieldStatisticsUpdateWindows(simCtx, offered, (PetscReal)offered));
    }
 
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeStatisticsConsoleSnapshot, &step,
                                   captured, sizeof(captured)));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Statistics windows at step 2") != NULL),
                               "EmitStatisticsConsoleSnapshot should print the step banner"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "console_window") != NULL),
                               "EmitStatisticsConsoleSnapshot should name each configured window"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "samples=2") != NULL),
                               "EmitStatisticsConsoleSnapshot should report the accepted sample count"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "valid=[") != NULL),
                               "EmitStatisticsConsoleSnapshot should report mask coverage once storage carries samples"));
 
    simCtx->fieldStatisticsEnabled = PETSC_FALSE;
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeStatisticsConsoleSnapshot, &step,
                                   captured, sizeof(captured)));
    PetscCall(PicurvAssertIntEqual(0, (PetscInt)strlen(captured),
                                   "a disabled subsystem emits no statistics console output"));
 
    simCtx->fieldStatisticsWindows = NULL;
    simCtx->fieldStatisticsWindowCount = 0;
    user->fieldStatisticsStorage = NULL;
    PetscCall(PicurvWindowStorageDestroy(&storage));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Sets the pressure field to a uniform value across the owned range.
 */
static PetscErrorCode SetUniformPressure(UserCtx *user, PetscReal value)
{
    PetscReal ***p = NULL;
    const DMDALocalInfo info = user->info;
 
    PetscFunctionBeginUser;
    PetscCall(DMDAVecGetArray(user->da, user->P, &p));
    for (PetscInt k = info.zs; k < info.zs + info.zm; ++k)
        for (PetscInt j = info.ys; j < info.ys + info.ym; ++j)
            for (PetscInt i = info.xs; i < info.xs + info.xm; ++i) p[k][j][i] = value;
    PetscCall(DMDAVecRestoreArray(user->da, user->P, &p));
    PetscFunctionReturn(0);
}
/**
 * @brief Drives one accumulation run at a given console cadence, in the runloop's order.
 *
 * Reproduces the sequence the run loop applies for each completed step so the console
 * observes exactly the states a real run would present to it.
 */
static PetscErrorCode AccumulateAtConsoleCadence(SimCtx *simCtx, UserCtx *user,
                                                 PicurvWindow *window,
                                                 PicurvWindowStorage *storage,
                                                 const PicurvWindowDefinition *definition,
                                                 PetscInt console_frequency)
{
    PetscFunctionBeginUser;
    PetscCall(PicurvWindowInit(window, definition));
    simCtx->fieldStatisticsEnabled = PETSC_TRUE;
    simCtx->fieldStatisticsWindowCount = 1;
    simCtx->fieldStatisticsWindows = window;
    simCtx->statisticsConsoleOutputFreq = console_frequency;
    user->fieldStatisticsStorage = storage;
 
    for (PetscInt step = 0; step <= 3; ++step) {
        PetscCall(SetUniformPressure(user, 1.0 + (PetscReal)step));
        PetscCall(FieldStatisticsUpdateWindows(simCtx, step, (PetscReal)step));
        if (ShouldEmitPeriodicStatisticsConsoleSnapshot(simCtx, step)) {
            PetscCall(EmitStatisticsConsoleSnapshot(user, simCtx, step));
        }
    }
    PetscFunctionReturn(0);
}
/**
 * @brief Asserts two accumulator vectors are bit-identical.
 */
static PetscErrorCode AssertVecsIdentical(Vec expected, Vec actual, const char *context)
{
    PetscBool equal = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PetscCall(VecEqual(expected, actual, &equal));
    PetscCall(PicurvAssertBool(equal, context));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests that the console cadence has no effect on any accumulated result.
 *
 * This is the observable form of the console cadence's exclusion from the window
 * definition hash: two runs over an identical field series, one reporting every step
 * and one reporting never, must leave bit-identical accumulator state. Running it
 * where the log level is at least `LOG_INFO` matters, because a snapshot that silently
 * declined to emit would make the comparison vacuous.
 */
 
static PetscErrorCode TestConsoleCadenceDoesNotChangeAccumulation(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    PicurvWindow reported, silent;
    PicurvWindowStorage reported_storage, silent_storage;
    PicurvWindowDefinition definition = LoggingStatisticsDefinition();
    char captured[8192];
    PetscInt step = 3;
 
    PetscFunctionBeginUser;
    definition.fields[0].want_second = PETSC_TRUE;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(VecSet(user->Nvert, 0.0));
    PetscCall(PicurvWindowStorageCreate(user, &definition, &reported_storage));
    PetscCall(PicurvWindowStorageCreate(user, &definition, &silent_storage));
 
    PetscCall(AccumulateAtConsoleCadence(simCtx, user, &reported, &reported_storage, &definition, 1));
    PetscCall(AccumulateAtConsoleCadence(simCtx, user, &silent, &silent_storage, &definition, 0));
 
    PetscCall(PicurvAssertIntEqual(reported.sample_count, silent.sample_count,
                                   "both cadences accept the same states"));
    PetscCall(PicurvAssertRealNear(reported.total_weight, silent.total_weight, 0.0,
                                   "both cadences accumulate the same total weight"));
    PetscCall(AssertVecsIdentical(reported_storage.count, silent_storage.count,
                                  "per-point sample counts are independent of the console cadence"));
    PetscCall(AssertVecsIdentical(reported_storage.weight, silent_storage.weight,
                                  "per-point weights are independent of the console cadence"));
    PetscCall(AssertVecsIdentical(reported_storage.mean[0], silent_storage.mean[0],
                                  "means are independent of the console cadence"));
    PetscCall(AssertVecsIdentical(reported_storage.m2[0], silent_storage.m2[0],
                                  "second moments are independent of the console cadence"));
 
    /* The reporting cadence did drive real output, so the comparison above compared a
     * reported run against a silent one rather than two silent ones. */
    simCtx->statisticsConsoleOutputFreq = 1;
    simCtx->fieldStatisticsWindows = &reported;
    user->fieldStatisticsStorage = &reported_storage;
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeStatisticsConsoleSnapshot, &step,
                                   captured, sizeof(captured)));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "console_window") != NULL),
                               "the reporting cadence emits console output at this log level"));
 
    simCtx->fieldStatisticsEnabled = PETSC_FALSE;
    simCtx->fieldStatisticsWindows = NULL;
    simCtx->fieldStatisticsWindowCount = 0;
    user->fieldStatisticsStorage = NULL;
    PetscCall(PicurvWindowStorageDestroy(&silent_storage));
    PetscCall(PicurvWindowStorageDestroy(&reported_storage));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests file-backed particle metrics logging after derived metrics are computed.
 */
 
static PetscErrorCode TestParticleMetricsLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char metrics_path[PETSC_MAX_PATH_LEN];
 
    PetscFunctionBeginUser;
    PetscCall(SeedLoggingParticleFixture(&simCtx, &user));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->StartStep = 0;
    simCtx->step = 1;
    simCtx->particlesLostLastStep = 1;
    simCtx->particlesLostCumulative = 7;
    simCtx->particlesMigratedLastStep = 2;
    simCtx->migrationPassesLastStep = 3;
 
    PetscCall(CalculateParticleCountPerCell(user));
    PetscCall(CalculateAdvancedParticleMetrics(user));
    PetscCall(LOG_PARTICLE_METRICS(user, "Timestep Metrics"));
 
    PetscCall(PetscSNPrintf(metrics_path, sizeof(metrics_path), "%s/Particle_Metrics.log", simCtx->log_dir));
    PetscCall(PicurvAssertFileExists(metrics_path, "LOG_PARTICLE_METRICS should write Particle_Metrics.log"));
    PetscCall(AssertFileContains(metrics_path, "Timestep Metrics", "Particle metrics log should include the caller-provided stage label"));
    PetscCall(AssertFileContains(metrics_path, "Occupied Cells", "Particle metrics log should include the metrics table header"));
    PetscCall(AssertFileContains(metrics_path, "Lost Total", "Particle metrics log should include the cumulative-loss column"));
    PetscCall(AssertFileContains(metrics_path, "| 1          | 7          | 2", "Particle metrics log should record both per-step and cumulative loss values"));
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests file-backed search metrics logging with the compact CSV contract.
 */
 
static PetscErrorCode TestSearchMetricsLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char metrics_path[PETSC_MAX_PATH_LEN];
 
    PetscFunctionBeginUser;
    PetscCall(SeedLoggingParticleFixture(&simCtx, &user));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->step = 2;
    simCtx->ti = 0.2;
    simCtx->particlesLostLastStep = 1;
    simCtx->particlesLostCumulative = 7;
    simCtx->particlesMigratedLastStep = 2;
    simCtx->migrationPassesLastStep = 3;
    simCtx->particleLoadImbalance = 1.5;
    simCtx->searchMetrics.searchAttempts = 4;
    simCtx->searchMetrics.searchPopulation = 2;
    simCtx->searchMetrics.searchLocatedCount = 1;
    simCtx->searchMetrics.searchLostCount = 1;
    simCtx->searchMetrics.traversalStepsSum = 10;
    simCtx->searchMetrics.reSearchCount = 2;
    simCtx->searchMetrics.maxTraversalSteps = 6;
    simCtx->searchMetrics.maxTraversalFailCount = 1;
    simCtx->searchMetrics.tieBreakCount = 1;
    simCtx->searchMetrics.boundaryClampCount = 2;
    simCtx->searchMetrics.bboxGuessSuccessCount = 3;
    simCtx->searchMetrics.bboxGuessFallbackCount = 1;
    simCtx->searchMetrics.maxParticlePassDepth = 3;
 
    PetscCall(LOG_SEARCH_METRICS(user));
 
    PetscCall(PetscSNPrintf(metrics_path, sizeof(metrics_path), "%s/search_metrics.csv", simCtx->analysis_dir));
    PetscCall(PicurvAssertFileExists(metrics_path, "LOG_SEARCH_METRICS should write search_metrics.csv"));
    PetscCall(AssertFileContains(metrics_path, "search_attempts", "Search metrics CSV header should include search_attempts"));
    PetscCall(AssertFileContains(metrics_path, "search_population", "Search metrics CSV header should include search_population"));
    PetscCall(AssertFileContains(metrics_path, "max_particle_pass_depth", "Search metrics CSV header should include max_particle_pass_depth"));
    PetscCall(AssertFileContains(metrics_path, "search_work_index", "Search metrics CSV header should include search_work_index"));
    PetscCall(AssertFileContains(metrics_path, "re_search_fraction", "Search metrics CSV header should include re_search_fraction"));
    PetscCall(AssertFileContains(metrics_path, "lost_cumulative", "Search metrics CSV header should include the cumulative-loss column"));
    PetscCall(AssertFileContains(metrics_path, "2,2.000000e-01,2,1,7,2,3,4,2.500000e+00,6,1,2,3,1,3,1.500000e+00,2,1,1,10,2,1,5.000000e-01,5.000000e+00,1.000000e+00", "Search metrics CSV should record the V2 raw and derived search metrics"));
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests stdout field-anatomy logging on the corrected production-like DM fixture.
 */
 
static PetscErrorCode TestFieldAnatomyLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char captured[8192];
    AnatomyCaptureCtx anatomy_ctx = {FIELD_ID_P, "unit-test"};
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(VecSet(user->P, 7.0));
    PetscCall(DMGlobalToLocalBegin(user->da, user->P, INSERT_VALUES, user->lP));
    PetscCall(DMGlobalToLocalEnd(user->da, user->P, INSERT_VALUES, user->lP));
    PetscCall(CaptureLoggingOutput(user, simCtx, InvokeFieldAnatomyLog, &anatomy_ctx, captured, sizeof(captured)));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Field Anatomy Log: [P]") != NULL),
                               "LOG_FIELD_ANATOMY should print the requested field name"));
    PetscCall(PicurvAssertBool((PetscBool)(strstr(captured, "Layout: [Cell-Centered]") != NULL),
                               "LOG_FIELD_ANATOMY should report the inferred data layout"));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Tests profiling helper lifecycle logging for timestep and final-summary outputs.
 */
 
static PetscErrorCode TestProfilingLifecycleHelpers(void)
{
    SimCtx simCtx;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char timestep_path[PETSC_MAX_PATH_LEN];
    char summary_path[PETSC_MAX_PATH_LEN];
    static char selected_name[] = "FlowSolver";
    char *selected_funcs[] = {selected_name};
 
    PetscFunctionBeginUser;
    PetscCall(PetscMemzero(&simCtx, sizeof(simCtx)));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx.log_dir, tmpdir, sizeof(simCtx.log_dir)));
    PetscCall(PetscStrncpy(simCtx.profilingTimestepMode, "selected", sizeof(simCtx.profilingTimestepMode)));
    PetscCall(PetscStrncpy(simCtx.profilingTimestepFile, "Profiling_Timestep_Summary.csv", sizeof(simCtx.profilingTimestepFile)));
    simCtx.rank = 0;
    simCtx.exec_mode = EXEC_MODE_SOLVER;
    simCtx.StartStep = 0;
    simCtx.nProfilingSelectedFuncs = 1;
    simCtx.profilingSelectedFuncs = selected_funcs;
    simCtx.profilingFinalSummary = PETSC_TRUE;
 
    PetscCall(ProfilingInitialize(&simCtx));
 
    _ProfilingStart("FlowSolver");
    _ProfilingEnd("FlowSolver");
    _ProfilingStart("UnselectedHelper");
    _ProfilingEnd("UnselectedHelper");
    PetscCall(ProfilingLogTimestepSummary(&simCtx, 1));
 
    _ProfilingStart("FlowSolver");
    _ProfilingEnd("FlowSolver");
    PetscCall(ProfilingResetTimestepCounters());
    PetscCall(ProfilingLogTimestepSummary(&simCtx, 2));
    PetscCall(ProfilingFinalize(&simCtx));
 
    PetscCall(PetscSNPrintf(timestep_path, sizeof(timestep_path), "%s/%s", simCtx.log_dir, simCtx.profilingTimestepFile));
    PetscCall(PetscSNPrintf(summary_path, sizeof(summary_path), "%s/ProfilingSummary_Solver.log", simCtx.log_dir));
    PetscCall(PicurvAssertFileExists(timestep_path, "profiling timestep summary should be written"));
    PetscCall(PicurvAssertFileExists(summary_path, "profiling final summary should be written"));
    PetscCall(AssertFileContains(timestep_path, "step,function,calls,step_time_s",
                                 "profiling timestep summary should contain the CSV header"));
    PetscCall(AssertFileContains(timestep_path, "1,FlowSolver,1,",
                                 "profiling timestep summary should log selected functions"));
    PetscCall(AssertFileNotContains(timestep_path, "UnselectedHelper",
                                    "profiling timestep summary should omit unselected functions in selected mode"));
    PetscCall(AssertFileContains(summary_path, "FINAL PROFILING SUMMARY",
                                 "profiling final summary should include its table banner"));
    PetscCall(AssertFileContains(summary_path, "FlowSolver",
                                 "profiling final summary should include selected functions"));
    PetscCall(AssertFileContains(summary_path, "UnselectedHelper",
                                 "profiling final summary should include total-time entries for unselected functions"));
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Tests runtime memory log header, step rows, final rows, and disabled mode.
 */
static PetscErrorCode TestRuntimeMemoryLogHelpers(void)
{
    SimCtx simCtx;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char memory_path[PETSC_MAX_PATH_LEN];
 
    PetscFunctionBeginUser;
    PetscCall(PetscMemzero(&simCtx, sizeof(simCtx)));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx.log_dir, tmpdir, sizeof(simCtx.log_dir)));
    PetscCall(PetscStrncpy(simCtx.runtimeMemoryLogFile, "Runtime_Memory.log", sizeof(simCtx.runtimeMemoryLogFile)));
    simCtx.rank = 0;
    simCtx.runtimeMemoryLogEnabled = PETSC_TRUE;
    simCtx.runtimeMemoryLogStarted = PETSC_FALSE;
    simCtx.runtimeMemoryLogHasPrevious = PETSC_FALSE;
    simCtx.continueMode = PETSC_FALSE;
    simCtx.StartStep = 0;
    PetscCall(PetscMemorySetGetMaximumUsage());
 
    PetscCall(RuntimeMemoryLogSample(&simCtx, 1, "Step", "-"));
    PetscCall(RuntimeMemoryLogSample(&simCtx, 1, "Final", "Complete"));
    PetscCall(PetscSNPrintf(memory_path, sizeof(memory_path), "%s/%s", simCtx.log_dir, simCtx.runtimeMemoryLogFile));
    PetscCall(PicurvAssertFileExists(memory_path, "runtime memory log should be written"));
    PetscCall(AssertFileContains(memory_path, "Process Current MB Max",
                                 "runtime memory log should contain readable column labels"));
    PetscCall(AssertFileContains(memory_path, "Step",
                                 "runtime memory log should contain a step row"));
    PetscCall(AssertFileContains(memory_path, "Final",
                                 "runtime memory log should contain a final row"));
    PetscCall(AssertFileContains(memory_path, "Complete",
                                 "runtime memory log should record final reason"));
 
    simCtx.runtimeMemoryLogEnabled = PETSC_FALSE;
    PetscCall(PetscStrncpy(simCtx.runtimeMemoryLogFile, "Runtime_Memory_Disabled.log", sizeof(simCtx.runtimeMemoryLogFile)));
    PetscCall(RuntimeMemoryLogSample(&simCtx, 2, "Step", "-"));
    PetscCall(PetscSNPrintf(memory_path, sizeof(memory_path), "%s/%s", simCtx.log_dir, simCtx.runtimeMemoryLogFile));
    PetscCall(PicurvAssertBool((PetscBool)(access(memory_path, F_OK) != 0),
                               "disabled runtime memory log should not create a file"));
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Verifies -solution_convergence_enabled=false suppresses the convergence writer.
 */
static PetscErrorCode TestSolutionConvergenceDisabled(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char log_path[PETSC_MAX_PATH_LEN];
    PetscBool exists = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->solutionConvergenceEnabled = PETSC_FALSE;
 
    PetscCall(InitializeSolutionConvergenceState(simCtx));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
    PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
    PetscCall(PetscTestFile(log_path, 'r', &exists));
    PetscCall(PicurvAssertBool((PetscBool)!exists,
                               "disabled solution convergence must not create a log"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Tests steady solution-convergence log output, IBM masking, and gauge-invariant pressure drift.
 */
static PetscErrorCode TestSolutionConvergenceSteadyLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char log_path[PETSC_MAX_PATH_LEN];
    char header[4096];
    char row1[4096];
    char row2[4096];
    char mode[128];
    Cmpnts ***ucat = NULL;
    PetscReal ***nvert = NULL;
    PetscReal mean_speed = NAN;
    PetscReal mean_speed_ref = NAN;
    PetscReal mean_speed_abs = NAN;
    PetscReal p_abs = NAN;
    PetscInt has_reference_1 = 0;
    PetscInt has_reference_2 = 0;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->solutionConvergenceMode = SOLUTION_CONVERGENCE_STEADY_DETERMINISTIC;
 
    PetscCall(InitializeSolutionConvergenceState(simCtx));
 
    simCtx->step = 1;
    simCtx->ti = 0.1;
    PetscCall(SetUniformVelocityField(user, user->Ucat, 1.0, 0.0, 0.0));
    PetscCall(SetUniformScalarField(user, user->P, 11.0));
    PetscCall(DMDAVecGetArray(user->da, user->Nvert, &nvert));
    nvert[1][1][1] = 1.0;
    PetscCall(DMDAVecRestoreArray(user->da, user->Nvert, &nvert));
    PetscCall(DMDAVecGetArray(user->fda, user->Ucat, &ucat));
    ucat[1][1][1].x = 999.0;
    PetscCall(DMDAVecRestoreArray(user->fda, user->Ucat, &ucat));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    simCtx->step = 2;
    simCtx->ti = 0.2;
    PetscCall(SetUniformVelocityField(user, user->Ucat, 1.0, 0.0, 0.0));
    PetscCall(SetUniformVelocityField(user, user->Ucat_o, 0.5, 0.0, 0.0));
    PetscCall(SetUniformScalarField(user, user->P, 11.0));
    PetscCall(SetUniformScalarField(user, user->P_o, 7.0));
    PetscCall(DMDAVecGetArray(user->fda, user->Ucat, &ucat));
    ucat[1][1][1].x = 999.0;
    PetscCall(DMDAVecRestoreArray(user->fda, user->Ucat, &ucat));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
    PetscCall(PicurvAssertFileExists(log_path, "steady solution-convergence logging should write the log"));
    PetscCall(ReadLogHeaderAndRow(log_path, 1, header, sizeof(header), row1, sizeof(row1)));
    PetscCall(ReadLogHeaderAndRow(log_path, 2, header, sizeof(header), row2, sizeof(row2)));
    PetscCall(LogGetColumnText(header, row1, "mode", mode, sizeof(mode)));
    PetscCall(LogGetColumnInt(header, row1, "ref", &has_reference_1));
    PetscCall(LogGetColumnInt(header, row2, "ref", &has_reference_2));
    PetscCall(LogGetColumnReal(header, row2, "mean_speed", &mean_speed));
    PetscCall(LogGetColumnReal(header, row2, "spd_ref", &mean_speed_ref));
    PetscCall(LogGetColumnReal(header, row2, "spd_abs", &mean_speed_abs));
    PetscCall(LogGetColumnReal(header, row2, "p_abs_l2", &p_abs));
 
    PetscCall(PicurvAssertBool((PetscBool)(strcmp(mode, "steady_deterministic") == 0),
                               "steady solution convergence row should record the mode name"));
    PetscCall(PicurvAssertIntEqual(0, has_reference_1,
                                   "the first steady solution-convergence row should be a warmup row"));
    PetscCall(PicurvAssertIntEqual(1, has_reference_2,
                                   "steady solution convergence should compare against the previous solved step"));
    PetscCall(PicurvAssertRealNear(1.0, mean_speed, 1.0e-12,
                                   "steady solution convergence should mask IBM-marked solid cells"));
    PetscCall(PicurvAssertRealNear(0.5, mean_speed_ref, 1.0e-12,
                                   "steady solution convergence should report the previous-step mean speed"));
    PetscCall(PicurvAssertRealNear(0.5, mean_speed_abs, 1.0e-12,
                                   "steady solution convergence should report mean-speed drift"));
    PetscCall(PicurvAssertRealNear(0.0, p_abs, 1.0e-12,
                                   "steady solution convergence pressure drift should be gauge invariant"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Tests periodic solution-convergence warmup and phase-aligned reference reuse.
 */
static PetscErrorCode TestSolutionConvergencePeriodicLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char log_path[PETSC_MAX_PATH_LEN];
    char header[4096];
    char row1[4096];
    char row2[4096];
    char row3[4096];
    PetscInt has_reference_1 = 0;
    PetscInt has_reference_2 = 0;
    PetscInt has_reference_3 = 0;
    PetscInt phase_step_1 = -1;
    PetscInt phase_step_2 = -1;
    PetscInt phase_step_3 = -1;
    PetscReal mean_speed_ref_2 = NAN;
    PetscReal mean_speed_abs_2 = NAN;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->solutionConvergenceMode = SOLUTION_CONVERGENCE_PERIODIC_DETERMINISTIC;
    simCtx->solutionConvergencePeriodSteps = 2;
 
    PetscCall(InitializeSolutionConvergenceState(simCtx));
 
    simCtx->step = 1;
    simCtx->ti = 0.1;
    PetscCall(SetUniformVelocityField(user, user->Ucat, 1.0, 0.0, 0.0));
    PetscCall(SetUniformScalarField(user, user->P, 2.0));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    simCtx->step = 2;
    simCtx->ti = 0.2;
    PetscCall(SetUniformVelocityField(user, user->Ucat, 2.0, 0.0, 0.0));
    PetscCall(SetUniformScalarField(user, user->P, 5.0));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    simCtx->step = 3;
    simCtx->ti = 0.3;
    PetscCall(SetUniformVelocityField(user, user->Ucat, 1.25, 0.0, 0.0));
    PetscCall(SetUniformScalarField(user, user->P, 9.0));
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
    PetscCall(PicurvAssertFileExists(log_path, "periodic solution-convergence logging should write the log"));
    PetscCall(ReadLogHeaderAndRow(log_path, 1, header, sizeof(header), row1, sizeof(row1)));
    PetscCall(ReadLogHeaderAndRow(log_path, 2, header, sizeof(header), row2, sizeof(row2)));
    PetscCall(ReadLogHeaderAndRow(log_path, 3, header, sizeof(header), row3, sizeof(row3)));
    PetscCall(LogGetColumnInt(header, row1, "ref", &has_reference_1));
    PetscCall(LogGetColumnInt(header, row2, "ref", &has_reference_2));
    PetscCall(LogGetColumnInt(header, row3, "ref", &has_reference_3));
    PetscCall(LogGetColumnInt(header, row1, "ph", &phase_step_1));
    PetscCall(LogGetColumnInt(header, row2, "ph", &phase_step_2));
    PetscCall(LogGetColumnInt(header, row3, "ph", &phase_step_3));
    PetscCall(LogGetColumnReal(header, row3, "spd_ref", &mean_speed_ref_2));
    PetscCall(LogGetColumnReal(header, row3, "spd_abs", &mean_speed_abs_2));
 
    PetscCall(PicurvAssertIntEqual(0, has_reference_1,
                                   "the first periodic phase visit should log warmup without a reference"));
    PetscCall(PicurvAssertIntEqual(0, has_reference_2,
                                   "the first periodic cycle should fully warm up before comparisons begin"));
    PetscCall(PicurvAssertIntEqual(1, has_reference_3,
                                   "the repeated periodic phase visit should compare against the stored reference"));
    PetscCall(PicurvAssertIntEqual(1, phase_step_1,
                                   "periodic solution convergence should log the current phase slot"));
    PetscCall(PicurvAssertIntEqual(0, phase_step_2,
                                   "periodic solution convergence should log distinct phase slots during warmup"));
    PetscCall(PicurvAssertIntEqual(1, phase_step_3,
                                   "periodic solution convergence should reuse the same phase slot on later cycles"));
    PetscCall(PicurvAssertRealNear(1.0, mean_speed_ref_2, 1.0e-12,
                                   "periodic solution convergence should report the stored phase-aligned reference"));
    PetscCall(PicurvAssertRealNear(0.25, mean_speed_abs_2, 1.0e-12,
                                   "periodic solution convergence should report the phase-aligned drift"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
 
/**
 * @brief Tests statistical solution-convergence sliding-window metrics.
 */
static PetscErrorCode TestSolutionConvergenceStatisticalLogging(void)
{
    SimCtx *simCtx = NULL;
    UserCtx *user = NULL;
    char tmpdir[PETSC_MAX_PATH_LEN];
    char log_path[PETSC_MAX_PATH_LEN];
    char header[4096];
    char row[4096];
    PetscReal mean_speed_window = NAN;
    PetscReal mean_speed_window_prev = NAN;
    PetscReal mean_speed_window_abs = NAN;
    PetscReal mean_speed_rms_window = NAN;
    PetscReal mean_ke_window = NAN;
    PetscReal mean_ke_window_prev = NAN;
    PetscReal mean_ke_window_abs = NAN;
    PetscReal mean_ke_rms_window_abs = NAN;
    PetscInt has_reference = 0;
    const PetscReal speed_samples[4] = {1.0, 3.0, 2.0, 4.0};
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 4, 4, 4));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    simCtx->solutionConvergenceMode = SOLUTION_CONVERGENCE_STATISTICAL_STEADY;
    simCtx->solutionConvergenceWindowSteps = 2;
 
    PetscCall(InitializeSolutionConvergenceState(simCtx));
    for (PetscInt step = 0; step < 4; ++step) {
        simCtx->step = step + 1;
        simCtx->ti = 0.1 * (PetscReal)(step + 1);
        PetscCall(SetUniformVelocityField(user, user->Ucat, speed_samples[step], 0.0, 0.0));
        PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
    }
 
    PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
    PetscCall(PicurvAssertFileExists(log_path, "statistical solution-convergence logging should write the log"));
    PetscCall(ReadLogHeaderAndRow(log_path, 4, header, sizeof(header), row, sizeof(row)));
    PetscCall(LogGetColumnInt(header, row, "ref", &has_reference));
    PetscCall(LogGetColumnReal(header, row, "spd_win", &mean_speed_window));
    PetscCall(LogGetColumnReal(header, row, "spd_win_prev", &mean_speed_window_prev));
    PetscCall(LogGetColumnReal(header, row, "spd_win_abs", &mean_speed_window_abs));
    PetscCall(LogGetColumnReal(header, row, "spd_rms_win", &mean_speed_rms_window));
    PetscCall(LogGetColumnReal(header, row, "ke_win", &mean_ke_window));
    PetscCall(LogGetColumnReal(header, row, "ke_win_prev", &mean_ke_window_prev));
    PetscCall(LogGetColumnReal(header, row, "ke_win_abs", &mean_ke_window_abs));
    PetscCall(LogGetColumnReal(header, row, "ke_rms_abs", &mean_ke_rms_window_abs));
 
    PetscCall(PicurvAssertIntEqual(1, has_reference,
                                   "statistical solution convergence should emit adjacent-window drift once two windows exist"));
    PetscCall(PicurvAssertRealNear(3.0, mean_speed_window, 1.0e-12,
                                   "statistical solution convergence should report the current mean-speed window"));
    PetscCall(PicurvAssertRealNear(2.0, mean_speed_window_prev, 1.0e-12,
                                   "statistical solution convergence should report the previous mean-speed window"));
    PetscCall(PicurvAssertRealNear(1.0, mean_speed_window_abs, 1.0e-12,
                                   "statistical solution convergence should report mean-speed window drift"));
    PetscCall(PicurvAssertRealNear(1.0, mean_speed_rms_window, 1.0e-12,
                                   "statistical solution convergence should report current mean-speed RMS"));
    PetscCall(PicurvAssertRealNear(5.0, mean_ke_window, 1.0e-12,
                                   "statistical solution convergence should report the current kinetic-energy window"));
    PetscCall(PicurvAssertRealNear(2.5, mean_ke_window_prev, 1.0e-12,
                                   "statistical solution convergence should report the previous kinetic-energy window"));
    PetscCall(PicurvAssertRealNear(2.5, mean_ke_window_abs, 1.0e-12,
                                   "statistical solution convergence should report kinetic-energy window drift"));
    PetscCall(PicurvAssertRealNear(1.0, mean_ke_rms_window_abs, 1.0e-12,
                                   "statistical solution convergence should report RMS kinetic-energy drift"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Regression test: convergence observables ignore the ghost layers of a walled box.
 *
 * Interior cells carry speed 1 and every ghost layer carries speed 100, as a
 * boundary-condition image may. The volume-averaged mean speed must be exactly 1: the
 * loops once ran over the ghost layers too, which put wall images into every mean.
 */
static PetscErrorCode TestSolutionConvergenceMeansExcludeGhostLayers(void)
{
    SimCtx   *simCtx = NULL;
    UserCtx  *user = NULL;
    char      tmpdir[PETSC_MAX_PATH_LEN];
    char      log_path[PETSC_MAX_PATH_LEN];
    char      header[4096];
    char      row[4096];
    PetscReal mean_speed = NAN;
    Cmpnts ***arr = NULL;
 
    PetscFunctionBeginUser;
    PetscCall(PicurvCreateMinimalContexts(&simCtx, &user, 6, 6, 6));
    PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
    PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
    PetscCall(PicurvPopulateIdentityMetrics(user));
    PetscCall(DMDAVecGetArray(user->fda, user->Ucat, &arr));
    for (PetscInt k = user->info.zs; k < user->info.zs + user->info.zm; ++k) {
        for (PetscInt j = user->info.ys; j < user->info.ys + user->info.ym; ++j) {
            for (PetscInt i = user->info.xs; i < user->info.xs + user->info.xm; ++i) {
                const PetscBool ghost = (PetscBool)(i == 0 || j == 0 || k == 0 || i == user->info.mx - 1 ||
                                                    j == user->info.my - 1 || k == user->info.mz - 1);
                arr[k][j][i].x = 0.0;
                arr[k][j][i].y = 0.0;
                arr[k][j][i].z = ghost ? 100.0 : 1.0;
            }
        }
    }
    PetscCall(DMDAVecRestoreArray(user->fda, user->Ucat, &arr));
 
    simCtx->solutionConvergenceMode = SOLUTION_CONVERGENCE_STEADY_DETERMINISTIC;
    PetscCall(InitializeSolutionConvergenceState(simCtx));
    simCtx->step = 1;
    simCtx->ti = 0.1;
    PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
    PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
    PetscCall(ReadLogHeaderAndRow(log_path, 1, header, sizeof(header), row, sizeof(row)));
    PetscCall(LogGetColumnReal(header, row, "mean_speed", &mean_speed));
    PetscCall(PicurvAssertRealNear(1.0, mean_speed, 1.0e-12,
                                   "mean speed must average physical cells only, not wall ghost images"));
 
    PetscCall(PicurvRemoveTempDir(tmpdir));
    PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    PetscFunctionReturn(0);
}
/**
 * @brief Regression test: volume-averaged mean KE of a sinusoidal field in a fully periodic domain.
 *
 * For u=0, v=0.1*sin(2πz), w=1 on a uniform [0,1]³ grid the exact continuous mean KE is 0.5025.
 * With identity metrics (Aj=1) the discrete mean over the N physical cells also equals 0.5025
 * for any N >= 3, because Σ_{k=0}^{N-1} sin²(2πk/N) = N/2.
 *
 * The physical cells are 1..mz-2. The ghost layers at 0 and mz-1 hold periodic copies of the
 * opposite cells, so counting either one weights a cell twice. The loops once counted the
 * upper ghost, and later still counted the lower one; this test requires both excluded.
 */
static PetscErrorCode TestPeriodicSinusoidalMeanKE(void)
{
    const PetscInt km_values[] = {8, 16};
    const PetscInt n_cases = (PetscInt)(sizeof(km_values) / sizeof(km_values[0]));
 
    PetscFunctionBeginUser;
    for (PetscInt t = 0; t < n_cases; ++t) {
        const PetscInt km = km_values[t];
        SimCtx   *simCtx = NULL;
        UserCtx  *user = NULL;
        char      tmpdir[PETSC_MAX_PATH_LEN];
        char      log_path[PETSC_MAX_PATH_LEN];
        char      header[4096];
        char      row[4096];
        PetscReal mean_ke = NAN;
 
        PetscCall(PicurvCreateMinimalContextsWithPeriodicity(&simCtx, &user, km, km, km,
                                                            PETSC_TRUE, PETSC_TRUE, PETSC_TRUE));
        PetscCall(PicurvMakeTempDir(tmpdir, sizeof(tmpdir)));
        PetscCall(PetscStrncpy(simCtx->log_dir, tmpdir, sizeof(simCtx->log_dir)));
        PetscCall(PicurvPopulateIdentityMetrics(user));
        PetscCall(SetSinusoidalVZField(user, user->Ucat, 0.1, 1.0));
 
        simCtx->solutionConvergenceMode = SOLUTION_CONVERGENCE_STATISTICAL_STEADY;
        simCtx->solutionConvergenceWindowSteps = 2;
        PetscCall(InitializeSolutionConvergenceState(simCtx));
 
        simCtx->step = 1;
        simCtx->ti = 0.1;
        PetscCall(LOG_SOLUTION_CONVERGENCE(simCtx));
 
        PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
        PetscCall(ReadLogHeaderAndRow(log_path, 1, header, sizeof(header), row, sizeof(row)));
        PetscCall(LogGetColumnReal(header, row, "mean_ke", &mean_ke));
        PetscCall(PicurvAssertRealNear(0.5025, mean_ke, 1.0e-10,
                                       "periodic sinusoidal field mean KE must equal 0.5025 (no duplicate endpoint)"));
 
        PetscCall(PicurvRemoveTempDir(tmpdir));
        PetscCall(PicurvDestroyMinimalContexts(&simCtx, &user));
    }
    PetscFunctionReturn(0);
}
 
/**
 * @brief Runs the unit-logging PETSc test binary.
 */
 
int main(int argc, char **argv)
{
    PetscErrorCode ierr;
    const PicurvTestCase cases[] = {
        {"string-conversion-helpers", TestStringConversionHelpers},
        {"get-log-level-from-environment", TestGetLogLevelFromEnvironment},
        {"allowed-functions-filter", TestAllowedFunctionsFilter},
        {"particle-console-snapshot-cadence", TestParticleConsoleSnapshotCadence},
        {"statistics-console-snapshot-cadence", TestStatisticsConsoleSnapshotCadence},
        {"logging-file-parsing-and-formatting-helpers", TestLoggingFileParsingAndFormattingHelpers},
        {"logging-continuity-and-field-diagnostics", TestLoggingContinuityAndFieldDiagnostics},
        {"interpolation-error-logging", TestInterpolationErrorLogging},
        {"scatter-metrics-logging", TestScatterMetricsLogging},
        {"particle-field-table-logging", TestParticleFieldTableLogging},
        {"particle-console-snapshot-logging", TestParticleConsoleSnapshotLogging},
        {"statistics-console-snapshot-logging", TestStatisticsConsoleSnapshotLogging},
        {"console-cadence-does-not-change-accumulation", TestConsoleCadenceDoesNotChangeAccumulation},
        {"particle-metrics-logging", TestParticleMetricsLogging},
        {"search-metrics-logging", TestSearchMetricsLogging},
        {"field-anatomy-logging", TestFieldAnatomyLogging},
        {"profiling-lifecycle-helpers", TestProfilingLifecycleHelpers},
        {"runtime-memory-log-helpers", TestRuntimeMemoryLogHelpers},
        {"solution-convergence-disabled", TestSolutionConvergenceDisabled},
        {"solution-convergence-steady-logging", TestSolutionConvergenceSteadyLogging},
        {"solution-convergence-periodic-logging", TestSolutionConvergencePeriodicLogging},
        {"solution-convergence-statistical-logging", TestSolutionConvergenceStatisticalLogging},
        {"periodic-sinusoidal-mean-ke", TestPeriodicSinusoidalMeanKE},
        {"solution-convergence-means-exclude-ghost-layers", TestSolutionConvergenceMeansExcludeGhostLayers},
    };
 
    (void)setenv("LOG_LEVEL", "INFO", 1);
 
    ierr = PetscInitialize(&argc, &argv, NULL, "PICurv logging tests");
    if (ierr) {
        return (int)ierr;
    }
 
    ierr = PicurvRunTests("unit-logging", cases, sizeof(cases) / sizeof(cases[0]));
    if (ierr) {
        PetscFinalize();
        return (int)ierr;
    }
 
    set_allowed_functions(NULL, 0);
 
    ierr = PetscFinalize();
    return (int)ierr;
}