logging.h File Reference

Logging utilities and macros for PETSc-based applications. More...

#include <petsc.h>
#include <stdlib.h>
#include <string.h>
#include <petscsys.h>
#include <ctype.h>
#include "variables.h"
#include "statistics_window.h"
#include "Boundaries.h"

Include dependency graph for logging.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	DualMonitorCtx
	Context for a dual-purpose KSP monitor. More...

Macros
#define	LOCAL   0
	Logging scope definitions for controlling message output.
#define	GLOBAL   1
	Scope for global logging across all processes.
#define	LOG(scope, level, fmt, ...)
	Logging macro for PETSc-based applications with scope control.
#define	LOG_DEFAULT(level, fmt, ...)
	Default logging macro for PETSc-based applications.
#define	LOG_SYNC(scope, level, fmt, ...)
	Logging macro for PETSc-based applications with scope control, using synchronized output across processes.
#define	LOG_SYNC_DEFAULT(level, fmt, ...)
	Default synchronized logging macro for PETSc-based applications.
#define	LOG_ALLOW(scope, level, fmt, ...)
	Logging macro that checks both the log level and whether the calling function is in the allowed-function list before printing.
#define	LOG_ALLOW_SYNC(scope, level, fmt, ...)
	Synchronized logging macro that checks both the log level and whether the calling function is in the allow-list.
#define	LOG_LOOP_ALLOW(scope, level, iterVar, interval, fmt, ...)
	Logs a message inside a loop, but only every interval iterations.
#define	LOG_LOOP_ALLOW_EXACT(scope, level, var, val, fmt, ...)
	Logs a custom message if a variable equals a specific value.
#define	LOG_ARRAY_ELEMENT_ALLOW(scope, level, arr, length, idx, fmt)
	Logs a single element of an array, given an index.
#define	LOG_ARRAY_SUBRANGE_ALLOW(scope, level, arr, length, start, end, fmt)
	Logs a consecutive subrange of an array.
#define	PROFILE_FUNCTION_BEGIN    _ProfilingStart(__FUNCT__)
	Marks the beginning of a profiled code block (typically a function).
#define	PROFILE_FUNCTION_END    _ProfilingEnd(__FUNCT__)
	Marks the end of a profiled code block.

Enumerations
enum	LogLevel {   LOG_ERROR = 0 , LOG_WARNING , LOG_INFO , LOG_DEBUG ,   LOG_TRACE , LOG_VERBOSE }
	Enumeration of logging levels. More...

Functions
LogLevel	get_log_level ()
	Retrieves the current logging level from the environment variable LOG_LEVEL.
PetscErrorCode	print_log_level (void)
	Prints the current logging level to the console.
void	set_allowed_functions (const char **functionList, int count)
	Sets the global list of function names that are allowed to log.
PetscBool	is_function_allowed (const char *functionName)
	Checks if a given function is in the allow-list.
PetscErrorCode	LOG_CELL_VERTICES (const Cell *cell, PetscMPIInt rank)
	Prints the coordinates of a cell's vertices.
PetscErrorCode	LOG_FACE_DISTANCES (PetscReal *d)
	Prints the signed distances to each face of the cell.
PetscErrorCode	LOG_PARTICLE_FIELDS (UserCtx *user, PetscInt printInterval)
	Prints particle fields in a table that automatically adjusts its column widths.
PetscBool	IsParticleConsoleSnapshotEnabled (const SimCtx *simCtx)
	Returns whether periodic particle console snapshots are enabled.
PetscBool	ShouldEmitPeriodicParticleConsoleSnapshot (const SimCtx *simCtx, PetscInt completed_step)
	Returns whether a particle console snapshot should be emitted for the.
PetscErrorCode	EmitParticleConsoleSnapshot (UserCtx *user, SimCtx *simCtx, PetscInt step)
	Emits one particle console snapshot into the main solver log.
PetscBool	IsStatisticsConsoleSnapshotEnabled (const struct SimCtx *simCtx)
	Reports whether the periodic statistics console snapshot is enabled.
PetscBool	ShouldEmitPeriodicStatisticsConsoleSnapshot (const struct SimCtx *simCtx, PetscInt completed_step)
	Reports whether a completed step falls on the console snapshot cadence.
PetscErrorCode	EmitStatisticsConsoleSnapshot (UserCtx *user, const struct SimCtx *simCtx, PetscInt step)
	Emits one console snapshot of window progress.
PetscErrorCode	FreeAllowedFunctions (char **funcs, PetscInt n)
	Free an array previously returned by LoadAllowedFunctionsFromFile().
PetscErrorCode	LoadAllowedFunctionsFromFile (const char filename[], char ***funcsOut, PetscInt *nOut)
	Load function names from a text file.
const char *	BCFaceToString (BCFace face)
	Returns the canonical log token for a boundary-face enum value.
const char *	InitialConditionModeToString (InitialConditionMode mode)
	Convert an initial-condition mode to a string representation.
const char *	FlowDirectionToString (FlowDirection fd)
	Convert a FlowDirection enum value to its YAML token string.
const char *	ParticleInitializationToString (ParticleInitializationType ParticleInitialization)
	Returns the canonical log token for a particle-initialization mode.
const char *	LESModelToString (LESModelType LESFlag)
	Returns the canonical log token for an LES model selector.
const char *	MomentumSolverTypeToString (MomentumSolverType SolverFlag)
	Returns the canonical log token for a momentum-solver selector.
const char *	BCTypeToString (BCType type)
	Returns the canonical log token for a boundary mathematical type.
const char *	BCHandlerTypeToString (BCHandlerType handler_type)
	Converts a BCHandlerType enum to its string representation.
PetscErrorCode	DualKSPMonitor (KSP ksp, PetscInt it, PetscReal rnorm, void *ctx)
	A custom KSP monitor that logs to a file and optionally to the console.
PetscErrorCode	DualMonitorDestroy (void **ctx)
	Destroys the DualMonitorCtx.
PetscErrorCode	LOG_CONTINUITY_METRICS (UserCtx *user)
	Logs continuity metrics for a single block to a file.
PetscErrorCode	LOG_SOLUTION_CONVERGENCE (SimCtx *simCtx)
	Logs physical solution-convergence metrics once per completed timestep.
const char *	ParticleLocationStatusToString (ParticleLocationStatus level)
	A function that outputs the name of the current level in the ParticleLocation enum.
void	PrintProgressBar (PetscInt step, PetscInt startStep, PetscInt totalSteps, PetscReal currentTime)
	Prints a progress bar to the console.
PetscErrorCode	ProfilingInitialize (SimCtx *simCtx)
	Initializes the custom profiling system using configuration from SimCtx.
PetscErrorCode	ProfilingResetTimestepCounters (void)
	Resets per-timestep profiling counters for the next solver step.
PetscErrorCode	ProfilingLogTimestepSummary (SimCtx *simCtx, PetscInt step)
	Logs the performance summary for the current timestep and resets timers.
PetscErrorCode	RuntimeMemoryLogSample (SimCtx *simCtx, PetscInt step, const char *event, const char *reason)
	Append a reduced runtime memory sample to the configured memory log.
PetscErrorCode	ProfilingFinalize (SimCtx *simCtx)
	the profiling excercise and build a profiling summary which is then printed to a log file.
void	_ProfilingStart (const char *func_name)
	Internal profiling hook invoked by PROFILE_FUNCTION_BEGIN.
void	_ProfilingEnd (const char *func_name)
	Internal profiling hook invoked by PROFILE_FUNCTION_END.
PetscErrorCode	LOG_FIELD_MIN_MAX (UserCtx *user, FieldId field_id)
	Computes and logs the local and global min/max values of a 3-component vector field.
PetscErrorCode	LOG_FIELD_ANATOMY (UserCtx *user, FieldId field_id, const char *stage_name)
	Logs the anatomy of a specified field at key boundary locations, respecting the solver's specific grid and variable architecture.
PetscErrorCode	LOG_CORNER_FIELD_ANATOMY (UserCtx *user, FieldId corner_field_id, const char *stage_name)
	Logs the node-layout anatomy of the transient center-to-corner interpolation field.
PetscErrorCode	LOG_INTERPOLATION_ERROR (UserCtx *user)
	Logs the interpolation error between the analytical and computed solutions.
PetscErrorCode	LOG_SCATTER_METRICS (UserCtx *user)
	Logs particle-to-grid scatter verification metrics for the prescribed scalar truth path.
PetscErrorCode	ResetSearchMetrics (SimCtx *simCtx)
	Resets the aggregate per-timestep search instrumentation counters.
PetscErrorCode	CalculateAdvancedParticleMetrics (UserCtx *user)
	Computes advanced particle statistics and stores them in SimCtx.
PetscErrorCode	LOG_SEARCH_METRICS (UserCtx *user)
	Writes compact runtime search metrics to CSV and optionally to console.
PetscErrorCode	LOG_PARTICLE_METRICS (UserCtx *user, const char *stageName)
	Logs particle swarm metrics, adapting its behavior based on a boolean flag in SimCtx.

Detailed Description

Logging utilities and macros for PETSc-based applications.

This header defines logging levels, scopes, and macros for consistent logging throughout the application. It provides functions to retrieve the current logging level and macros to simplify logging with scope control.

Definition in file logging.h.

---

Data Structure Documentation

DualMonitorCtx

struct DualMonitorCtx

Context for a dual-purpose KSP monitor.

This struct holds a file viewer for unconditional logging and a boolean flag to enable/disable optional logging to the console.

Definition at line 56 of file logging.h.

Data Fields
FILE *	file_handle
PetscBool	log_to_console
PetscReal	bnorm
PetscInt	step
PetscInt	block_id

Macro Definition Documentation

LOCAL

#define LOCAL   0

Logging scope definitions for controlling message output.

• LOCAL: Logs on the current process using MPI_COMM_SELF.
• GLOBAL: Logs across all processes using MPI_COMM_WORLD. Scope for local logging on the current process.

Definition at line 45 of file logging.h.

GLOBAL

#define GLOBAL   1

Scope for global logging across all processes.

Definition at line 46 of file logging.h.

LOG

#define LOG	(		scope,
			level,
			fmt,
			...
	)

Value:

    do { \
        /* Determine the MPI communicator based on the scope */ \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Print the message to the specified communicator */ \
            PetscPrintf(comm, fmt, ##__VA_ARGS__); \
        } \
    } while (0)

Logging macro for PETSc-based applications with scope control.

This macro provides a convenient way to log messages with different scopes (LOCAL or GLOBAL) and severity levels. It utilizes PETSc's PetscPrintf function for message output.

Parameters

scope	Specifies the logging scope: LOCAL: Logs on the current process using MPI_COMM_SELF. GLOBAL: Logs on all processes using MPI_COMM_WORLD.
level	The severity level of the message (e.g., LOG_INFO, LOG_ERROR).
fmt	The format string for the message (similar to printf).
...	Additional arguments for the format string (optional).

Example usage: LOG(LOCAL, LOG_ERROR, "An error occurred at index %ld.\n", idx); LOG(GLOBAL, LOG_INFO, "Grid size: %ld x %ld x %ld.\n", nx, ny, nz);

Definition at line 84 of file logging.h.

       { \
        /* Determine the MPI communicator based on the scope */ \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Print the message to the specified communicator */ \
            PetscPrintf(comm, fmt, ##__VA_ARGS__); \
        } \
    } while (0)

LOG_DEFAULT

#define LOG_DEFAULT	(		level,
			fmt,
			...
	)

Value:

    do { \
        /* Set the communicator to global (MPI_COMM_WORLD) by default */ \
        MPI_Comm comm = MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Print the message using PetscPrintf with the global communicator */ \
            PetscPrintf(comm, fmt, ##__VA_ARGS__); \
        } \
    } while (0)

Default logging macro for PETSc-based applications.

This macro simplifies logging by defaulting the scope to GLOBAL (i.e., MPI_COMM_WORLD) and providing a convenient interface for common logging needs.

Parameters

level	The severity level of the message (e.g., LOG_ERROR, LOG_INFO).
fmt	The format string for the log message (similar to printf).
...	Additional arguments for the format string (optional).

Example usage: LOG_DEFAULT(LOG_ERROR, "Error occurred at index %ld.\n", idx); LOG_DEFAULT(LOG_INFO, "Grid size: %ld x %ld x %ld.\n", nx, ny, nz);

Note

• By default, this macro logs across all MPI processes using MPI_COMM_WORLD.
• If finer control (e.g., local logging) is required, use the more general LOG macro.
• The log level is filtered based on the value returned by get_log_level().

Definition at line 115 of file logging.h.

       { \
        /* Set the communicator to global (MPI_COMM_WORLD) by default */ \
        MPI_Comm comm = MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Print the message using PetscPrintf with the global communicator */ \
            PetscPrintf(comm, fmt, ##__VA_ARGS__); \
        } \
    } while (0)

LOG_SYNC

#define LOG_SYNC	(		scope,
			level,
			fmt,
			...
	)

Value:

    do { \
        /* Determine the MPI communicator based on the scope */ \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Synchronized print (collective) on the specified communicator */ \
            PetscSynchronizedPrintf(comm, fmt, ##__VA_ARGS__); \
            /* Ensure all ranks have finished printing before continuing */ \
            PetscSynchronizedFlush(comm, PETSC_STDOUT); \
        } \
    } while (0)

Logging macro for PETSc-based applications with scope control, using synchronized output across processes.

This macro uses PetscSynchronizedPrintf and PetscSynchronizedFlush to ensure messages from different ranks are printed in a synchronized (rank-by-rank) manner, preventing interleaved outputs.

Parameters

scope	Specifies the logging scope: LOCAL: Logs on the current process using MPI_COMM_SELF. GLOBAL: Logs on all processes using MPI_COMM_WORLD.
level	The severity level of the message (e.g., LOG_INFO, LOG_ERROR).
fmt	The format string for the message (similar to printf).
...	Additional arguments for the format string (optional).

Example usage: LOG_SYNC(LOCAL, LOG_ERROR, "An error occurred at index %ld.\n", idx); LOG_SYNC(GLOBAL, LOG_INFO, "Synchronized info: rank = %ld.\n", rank);

Definition at line 145 of file logging.h.

       { \
        /* Determine the MPI communicator based on the scope */ \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        /* Check if the log level is within the allowed range */ \
        if ((int)(level) <= (int)get_log_level()) { \
            /* Synchronized print (collective) on the specified communicator */ \
            PetscSynchronizedPrintf(comm, fmt, ##__VA_ARGS__); \
            /* Ensure all ranks have finished printing before continuing */ \
            PetscSynchronizedFlush(comm, PETSC_STDOUT); \
        } \
    } while (0)

LOG_SYNC_DEFAULT

#define LOG_SYNC_DEFAULT	(		level,
			fmt,
			...
	)

Value:

    do { \
        if ((int)(level) <= (int)get_log_level()) { \
            PetscSynchronizedPrintf(MPI_COMM_WORLD, fmt, ##__VA_ARGS__); \
            PetscSynchronizedFlush(MPI_COMM_WORLD, PETSC_STDOUT); \
        } \
    } while (0)

Default synchronized logging macro for PETSc-based applications.

This macro simplifies logging by defaulting the scope to GLOBAL (i.e., MPI_COMM_WORLD) and provides synchronized output across all processes.

Parameters

level	The severity level of the message (e.g., LOG_ERROR, LOG_INFO).
fmt	The format string for the log message (similar to printf).
...	Additional arguments for the format string (optional).

Example usage: LOG_SYNC_DEFAULT(LOG_ERROR, "Error at index %ld.\n", idx); LOG_SYNC_DEFAULT(LOG_INFO, "Process rank: %ld.\n", rank);

Note

• By default, this macro logs across all MPI processes using MPI_COMM_WORLD.
• If local (per-process) logging is required, use the more general LOG_SYNC macro.
• The log level is filtered based on the value returned by get_log_level().

Definition at line 178 of file logging.h.

       { \
        if ((int)(level) <= (int)get_log_level()) { \
            PetscSynchronizedPrintf(MPI_COMM_WORLD, fmt, ##__VA_ARGS__); \
            PetscSynchronizedFlush(MPI_COMM_WORLD, PETSC_STDOUT); \
        } \
    } while (0)

LOG_ALLOW

#define LOG_ALLOW	(		scope,
			level,
			fmt,
			...
	)

Value:

    do { \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        if ((int)(level) <= (int)get_log_level() && is_function_allowed(__func__)) { \
            PetscPrintf(comm, "[%s] " fmt, __func__, ##__VA_ARGS__); \
        } \
    } while (0)

Logging macro that checks both the log level and whether the calling function is in the allowed-function list before printing.

Useful for selective, per-function logging.

Parameters

scope	Specifies the logging scope (LOCAL or GLOBAL).
level	The severity level of the message (e.g., LOG_INFO, LOG_ERROR).
fmt	The format string for the message (similar to printf).
...	Additional arguments for the format string (optional).

Example usage: LOG_ALLOW(LOCAL, LOG_DEBUG, "Debugging info in function: %s\n", func);

Definition at line 200 of file logging.h.

       { \
        MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
        if ((int)(level) <= (int)get_log_level() && is_function_allowed(__func__)) { \
            PetscPrintf(comm, "[%s] " fmt, __func__, ##__VA_ARGS__); \
        } \
    } while (0)

LOG_ALLOW_SYNC

#define LOG_ALLOW_SYNC	(		scope,
			level,
			fmt,
			...
	)

Value:

do {                                                                               \
    /* ------------------------------------------------------------------ */      \
    /* Validate scope and pick communicator *before* any early exits.     */      \
    /* ------------------------------------------------------------------ */      \
    MPI_Comm _comm;                                                                \
    if      ((scope) == LOCAL)  _comm = MPI_COMM_SELF;                             \
    else if ((scope) == GLOBAL) _comm = MPI_COMM_WORLD;                            \
    else {                                                                        \
        fprintf(stderr, "LOG_ALLOW_SYNC ERROR: invalid scope (%d) at %s:%d\n",     \
                (scope), __FILE__, __LINE__);                                      \
        MPI_Abort(MPI_COMM_WORLD, 1);                                              \
    }                                                                              \
                                                                                   \
    /* ------------------------------------------------------------------ */      \
    /* Decide whether *this* rank should actually print.                   */      \
    /* ------------------------------------------------------------------ */      \
    PetscBool _doPrint =                                                          \
        is_function_allowed(__func__) && ((int)(level) <= (int)get_log_level());   \
                                                                                   \
    if (_doPrint) {                                                                \
        PetscSynchronizedPrintf(_comm, "[%s] " fmt, __func__, ##__VA_ARGS__);      \
    }                                                                              \
                                                                                   \
    /* ------------------------------------------------------------------ */      \
    /* ALL ranks call the flush, even if they printed nothing.            */      \
    /* ------------------------------------------------------------------ */      \
    PetscSynchronizedFlush(_comm, PETSC_STDOUT);                                   \
} while (0)

Synchronized logging macro that checks both the log level and whether the calling function is in the allow-list.

This macro uses PetscSynchronizedPrintf and PetscSynchronizedFlush to ensure messages from different ranks are printed in a rank-ordered fashion (i.e., to avoid interleaving). It also filters out messages if the current function is not in the allow-list (is_function_allowed(__func__)) or the requested log level is higher than get_log_level().

Parameters

scope	Either LOCAL (MPI_COMM_SELF) or GLOBAL (MPI_COMM_WORLD).
level	One of LOG_ERROR, LOG_WARNING, LOG_INFO, LOG_DEBUG.
fmt	A printf-style format string (e.g., "Message: %ld\n").
...	Variadic arguments to fill in fmt.

Example usage:

LOG_ALLOW_SYNC(LOCAL, LOG_DEBUG, "Debug info: rank = %ld\n", rank);
LOG_ALLOW_SYNC(GLOBAL, LOG_INFO,  "Synchronized info in %s\n", __func__);

Definition at line 253 of file logging.h.

   {                                                                               \
    /* ------------------------------------------------------------------ */      \
    /* Validate scope and pick communicator *before* any early exits.     */      \
    /* ------------------------------------------------------------------ */      \
    MPI_Comm _comm;                                                                \
    if      ((scope) == LOCAL)  _comm = MPI_COMM_SELF;                             \
    else if ((scope) == GLOBAL) _comm = MPI_COMM_WORLD;                            \
    else {                                                                        \
        fprintf(stderr, "LOG_ALLOW_SYNC ERROR: invalid scope (%d) at %s:%d\n",     \
                (scope), __FILE__, __LINE__);                                      \
        MPI_Abort(MPI_COMM_WORLD, 1);                                              \
    }                                                                              \
                                                                                   \
    /* ------------------------------------------------------------------ */      \
    /* Decide whether *this* rank should actually print.                   */      \
    /* ------------------------------------------------------------------ */      \
    PetscBool _doPrint =                                                          \
        is_function_allowed(__func__) && ((int)(level) <= (int)get_log_level());   \
                                                                                   \
    if (_doPrint) {                                                                \
        PetscSynchronizedPrintf(_comm, "[%s] " fmt, __func__, ##__VA_ARGS__);      \
    }                                                                              \
                                                                                   \
    /* ------------------------------------------------------------------ */      \
    /* ALL ranks call the flush, even if they printed nothing.            */      \
    /* ------------------------------------------------------------------ */      \
    PetscSynchronizedFlush(_comm, PETSC_STDOUT);                                   \
} while (0)

LOG_LOOP_ALLOW

#define LOG_LOOP_ALLOW	(		scope,
			level,
			iterVar,
			interval,
			fmt,
			...
	)

Value:

    do {                                                                       \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            if ((iterVar) % (interval) == 0) {                                 \
                MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                PetscPrintf(comm, "[%s] [%s=%d] " fmt,                       \
                            __func__, #iterVar, (iterVar), ##__VA_ARGS__);               \
            }                                                                  \
        }                                                                      \
    } while (0)

Logs a message inside a loop, but only every interval iterations.

Parameters

scope	LOCAL or GLOBAL.
level	LOG_* level.
iterVar	The loop variable (e.g., i).
interval	Only log when (iterVar % interval == 0).
fmt	printf-style format string.
...	Variadic arguments to include in the formatted message.

Example: for (int i = 0; i < 100; i++) { LOG_LOOP_ALLOW(LOCAL, LOG_DEBUG, i, 10, "Value of i=%d\n", i); }

Definition at line 298 of file logging.h.

       {                                                                       \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            if ((iterVar) % (interval) == 0) {                                 \
                MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                PetscPrintf(comm, "[%s] [%s=%d] " fmt,                       \
                            __func__, #iterVar, (iterVar), ##__VA_ARGS__);               \
            }                                                                  \
        }                                                                      \
    } while (0)

LOG_LOOP_ALLOW_EXACT

#define LOG_LOOP_ALLOW_EXACT	(		scope,
			level,
			var,
			val,
			fmt,
			...
	)

Value:

    do {                                                                       \
        /* First, perform the cheap, standard gatekeeper checks. */            \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            /* Only if those pass, check the user's specific condition. */      \
            if ((var) == (val)) {                                              \
                MPI_Comm comm = ((scope) == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                /* Print the standard prefix, then the user's custom message. */ \
                PetscPrintf(comm, "[%s] [%s=%d] " fmt,                          \
                    __func__, #var, (var), ##__VA_ARGS__);                      \
            }                                                                  \
        }                                                                      \
    } while (0)

Logs a custom message if a variable equals a specific value.

This is a variadic macro for logging a single event when a condition is met. It is extremely useful for printing debug information at a specific iteration of a loop or when a state variable reaches a certain value.

Parameters

scope	Either LOCAL or GLOBAL.
level	The logging level.
var	The variable to check (e.g., a loop counter 'k').
val	The value that triggers the log (e.g., 6). The log prints if var == val.
fmt	A printf-style format string.
...	A printf-style format string and its corresponding arguments.

Definition at line 335 of file logging.h.

       {                                                                       \
        /* First, perform the cheap, standard gatekeeper checks. */            \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            /* Only if those pass, check the user's specific condition. */      \
            if ((var) == (val)) {                                              \
                MPI_Comm comm = ((scope) == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                /* Print the standard prefix, then the user's custom message. */ \
                PetscPrintf(comm, "[%s] [%s=%d] " fmt,                          \
                    __func__, #var, (var), ##__VA_ARGS__);                      \
            }                                                                  \
        }                                                                      \
    } while (0)

LOG_ARRAY_ELEMENT_ALLOW

#define LOG_ARRAY_ELEMENT_ALLOW	(		scope,
			level,
			arr,
			length,
			idx,
			fmt
	)

Value:

    do {                                                                      \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            if ((idx) >= 0 && (idx) < (length)) {                             \
                MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                PetscPrintf(comm, "[%s] arr[%d] = " fmt "\n",                 \
                            __func__, (idx), (arr)[idx]);                     \
            }                                                                 \
        }                                                                     \
    } while (0)

Logs a single element of an array, given an index.

Parameters

scope	Either LOCAL or GLOBAL.
level	LOG_ERROR, LOG_WARNING, LOG_INFO, or LOG_DEBUG.
arr	Pointer to the array to log from.
length	The length of the array (to prevent out-of-bounds).
idx	The index of the element to print.
fmt	The printf-style format specifier (e.g. "%g", "%f", etc.).

This macro only logs if: 1) The current function is in the allow-list (is_function_allowed(__func__)). 2) The requested logging level <= the current global get_log_level(). 3) The index idx is valid (0 <= idx < length).

Definition at line 364 of file logging.h.

       {                                                                      \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            if ((idx) >= 0 && (idx) < (length)) {                             \
                MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
                PetscPrintf(comm, "[%s] arr[%d] = " fmt "\n",                 \
                            __func__, (idx), (arr)[idx]);                     \
            }                                                                 \
        }                                                                     \
    } while (0)

LOG_ARRAY_SUBRANGE_ALLOW

#define LOG_ARRAY_SUBRANGE_ALLOW	(		scope,
			level,
			arr,
			length,
			start,
			end,
			fmt
	)

Value:

    do {                                                                      \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
            PetscInt _start = (start) < 0 ? 0 : (start);                      \
            PetscInt _end   = (end) >= (length) ? (length) - 1 : (end);       \
            for (PetscInt i = _start; i <= _end; i++) {                       \
                PetscPrintf(comm, "[%s] arr[%d] = " fmt "\n", __func__, i, (arr)[i]); \
            }                                                                 \
        }                                                                     \
    } while (0)

Logs a consecutive subrange of an array.

Parameters

scope	Either LOCAL or GLOBAL.
level	LOG_ERROR, LOG_WARNING, LOG_INFO, or LOG_DEBUG.
arr	Pointer to the array to log from.
length	Total length of the array.
start	Starting index of the subrange.
end	Ending index of the subrange (inclusive).
fmt	The printf-style format specifier (e.g., "%g", "%f").

This macro prints each element arr[i] for i in [start, end], bounded by [0, length-1].

Definition at line 388 of file logging.h.

       {                                                                      \
        if (is_function_allowed(__func__) && (int)(level) <= (int)get_log_level()) { \
            MPI_Comm comm = (scope == LOCAL) ? MPI_COMM_SELF : MPI_COMM_WORLD; \
            PetscInt _start = (start) < 0 ? 0 : (start);                      \
            PetscInt _end   = (end) >= (length) ? (length) - 1 : (end);       \
            for (PetscInt i = _start; i <= _end; i++) {                       \
                PetscPrintf(comm, "[%s] arr[%d] = " fmt "\n", __func__, i, (arr)[i]); \
            }                                                                 \
        }                                                                     \
    } while (0)

PROFILE_FUNCTION_BEGIN

#define PROFILE_FUNCTION_BEGIN    _ProfilingStart(__FUNCT__)

Marks the beginning of a profiled code block (typically a function).

Place this macro at the very beginning of a function you wish to profile. It automatically captures the function's name and starts a wall-clock timer.

Definition at line 850 of file logging.h.

PROFILE_FUNCTION_END

#define PROFILE_FUNCTION_END    _ProfilingEnd(__FUNCT__)

Marks the end of a profiled code block.

Place this macro just before every return point in a function that starts with PROFILE_FUNCTION_BEGIN. It stops the timer and accumulates the results.

Definition at line 859 of file logging.h.

Enumeration Type Documentation

LogLevel

enum LogLevel

Enumeration of logging levels.

Defines various severity levels for logging messages.

Enumerator
LOG_ERROR	Critical errors that may halt the program.
LOG_WARNING	Non-critical issues that warrant attention.
LOG_INFO	Informational messages about program execution.
LOG_DEBUG	Detailed debugging information.
LOG_TRACE	Very fine-grained tracing information for in-depth debugging.
LOG_VERBOSE	Extremely detailed logs, typically for development use only.

Definition at line 28 of file logging.h.

             {
    LOG_ERROR = 0,   /**< Critical errors that may halt the program */
    LOG_WARNING,     /**< Non-critical issues that warrant attention */
    LOG_INFO,        /**< Informational messages about program execution */
    LOG_DEBUG,       /**< Detailed debugging information */
    LOG_TRACE,        /**< Very fine-grained tracing information for in-depth debugging */
    LOG_VERBOSE      /**< Extremely detailed logs, typically for development use only */
} LogLevel;

Function Documentation

get_log_level()

LogLevel get_log_level

(

)

Retrieves the current logging level from the environment variable LOG_LEVEL.

The function checks the LOG_LEVEL environment variable and sets the logging level accordingly. Supported levels are "ERROR", "WARNING", "INFO", "DEBUG", "TRACE", and "VERBOSE". Unset or unrecognized values default to "ERROR".

Returns

LogLevel The current logging level.

Retrieves the current logging level from the environment variable LOG_LEVEL.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

get_log_level()

Definition at line 87 of file logging.c.

                         {
    if (current_log_level == -1) { // Log level not set yet
        const char *env = getenv("LOG_LEVEL");
        if (!env) {
            current_log_level = LOG_ERROR; // Default level
        }
        else if (strcmp(env, "DEBUG") == 0) {
            current_log_level = LOG_DEBUG;
        }
        else if (strcmp(env, "INFO") == 0) {
            current_log_level = LOG_INFO;
        }
        else if (strcmp(env, "WARNING") == 0) {
            current_log_level = LOG_WARNING;
        }
        else if (strcmp(env, "VERBOSE") == 0) {
            current_log_level = LOG_VERBOSE;
        }
        else if (strcmp(env, "TRACE") == 0) {
            current_log_level = LOG_TRACE;
        }
        else {
            current_log_level = LOG_ERROR; // Default if unrecognized
        }
    }
    return current_log_level;
}

Here is the caller graph for this function:

print_log_level()

PetscErrorCode print_log_level

(

void

)

Prints the current logging level to the console.

This function retrieves the log level using get_log_level() and prints the corresponding log level name. It helps verify the logging configuration at runtime. The log levels supported are:

• LOG_ERROR (0) : Logs only critical errors.
• LOG_WARNING (1) : Logs warnings and errors.
• LOG_INFO (2) : Logs general information, warnings, and errors.
• LOG_DEBUG (3) : Logs debugging information, info, warnings, and errors.
• LOG_TRACE (4) : Logs fine-grained trace information.

• LOG_VERBOSE (5) : Logs very detailed developer output. If LOG_LEVEL is not set, it defaults to LOG_ERROR.

  Returns

  PetscErrorCode 0 on success.

  Prints the current logging level to the console.

  Local to this translation unit.

Definition at line 119 of file logging.c.

{
  PetscMPIInt     rank;
  PetscErrorCode  ierr;
  int             level;
  const char     *level_name;
 
  PetscFunctionBeginUser;
  /* get MPI rank */
  ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRMPI(ierr);
 
  /* decide level name */
  level       = get_log_level();
  level_name = (level == LOG_ERROR)   ? "ERROR"   :
               (level == LOG_WARNING) ? "WARNING" :
               (level == LOG_INFO)    ? "INFO"    :
               (level == LOG_DEBUG)   ? "DEBUG"   :
               (level == LOG_VERBOSE) ? "VERBOSE" :
               (level == LOG_TRACE)   ? "TRACE"   :
               "UNKNOWN";
 
  /* print it out */
  ierr = PetscPrintf(PETSC_COMM_SELF,
                     "Current log level: %s (%d) | rank: %d\n",
                     level_name, level, (int)rank);
  CHKERRMPI(ierr);
 
  PetscFunctionReturn(PETSC_SUCCESS);
}

Here is the call graph for this function:

Here is the caller graph for this function:

set_allowed_functions()

void set_allowed_functions	(	const char **	functionList,
		int	count
	)

Sets the global list of function names that are allowed to log.

You can replace the entire list of allowed function names at runtime.

Parameters

functionList	Replacement array of permitted function names.
count	Number of entries in functionList.

Sets the global list of function names that are allowed to log.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

set_allowed_functions()

Definition at line 155 of file logging.c.

{
    // 1. Free any existing entries
    if (gAllowedFunctions) {
        for (int i = 0; i < gNumAllowed; ++i) {
            free(gAllowedFunctions[i]); // each was strdup'ed
        }
        free(gAllowedFunctions);
        gAllowedFunctions = NULL;
        gNumAllowed = 0;
    }
 
    // 2. Allocate new array
    if (count > 0) {
        gAllowedFunctions = (char**)malloc(sizeof(char*) * count);
    }
 
    // 3. Copy the new entries
    for (int i = 0; i < count; ++i) {
        // strdup is a POSIX function. If not available, implement your own string copy.
        gAllowedFunctions[i] = strdup(functionList[i]);
    }
    gNumAllowed = count;
}

Here is the caller graph for this function:

is_function_allowed()

PetscBool is_function_allowed

(

const char *

functionName

)

Checks if a given function is in the allow-list.

This helper is used internally by the LOG_ALLOW macro.

Parameters

functionName

Function name to query.

Returns

PETSC_TRUE when the name is enabled by the allow-list.

Checks if a given function is in the allow-list.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

is_function_allowed()

Definition at line 186 of file logging.c.

{
    /* no list ⇒ allow all */
    if (gNumAllowed == 0) {
        return PETSC_TRUE;
    }
 
    /* otherwise only the listed functions are allowed */
    for (int i = 0; i < gNumAllowed; ++i) {
        if (strcmp(gAllowedFunctions[i], functionName) == 0) {
            return PETSC_TRUE;
        }
    }
    return PETSC_FALSE;
}

Here is the caller graph for this function:

LOG_CELL_VERTICES()

PetscErrorCode LOG_CELL_VERTICES	(	const Cell *	cell,
		PetscMPIInt	rank
	)

Prints the coordinates of a cell's vertices.

This function iterates through the eight vertices of a given cell and prints their coordinates. It is primarily used for debugging purposes to verify the correctness of cell vertex assignments.

Parameters

[in]	cell	Pointer to a Cell structure representing the cell, containing its vertices.
[in]	rank	MPI rank for identification (useful in parallel environments).

Returns

PetscErrorCode Returns 0 to indicate successful execution. Non-zero on failure.

Note

• Ensure that the cell pointer is not NULL before calling this function..

Prints the coordinates of a cell's vertices.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_CELL_VERTICES()

Definition at line 208 of file logging.c.

{
 
    // Validate input pointers
    if (cell == NULL) {
      LOG_ALLOW(LOCAL,LOG_ERROR, "'cell' is NULL.\n");
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "LOG_CELL_VERTICES - Input parameter 'cell' is NULL.");
    }
 
      LOG_ALLOW(LOCAL,LOG_VERBOSE, "Rank %d, Cell Vertices:\n", rank);
        for(int i = 0; i < 8; i++){ 
      LOG_ALLOW(LOCAL,LOG_VERBOSE, "  Vertex[%d]: (%.2f, %.2f, %.2f)\n", 
                       i, cell->vertices[i].x, cell->vertices[i].y, cell->vertices[i].z);
        }
 
    return 0; // Indicate successful execution
}

Here is the caller graph for this function:

LOG_FACE_DISTANCES()

PetscErrorCode LOG_FACE_DISTANCES

(

PetscReal *

d

)

Prints the signed distances to each face of the cell.

This function iterates through the six signed distances from a point to each face of a given cell and prints their values. It is primarily used for debugging purposes to verify the correctness of distance calculations.

Parameters

[in]

d

An array of six PetscReal values representing the signed distances. The indices correspond to: d[LEFT]: Left Face d[RIGHT]: Right Face d[BOTTOM]: Bottom Face d[TOP]: Top Face d[FRONT]: Front Face d[BACK]: Back Face

Returns

PetscErrorCode Returns 0 to indicate successful execution. Non-zero on failure.

Note

• Ensure that the d array is correctly populated with signed distances before calling this function.

Prints the signed distances to each face of the cell.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_FACE_DISTANCES()

Definition at line 233 of file logging.c.

{
 
    // Validate input array
    if (d == NULL) {
      LOG_ALLOW(LOCAL,LOG_ERROR, "  'd' is NULL.\n");
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "  Input array 'd' is NULL.");
    }
 
    PetscPrintf(PETSC_COMM_SELF, "  Face Distances:\n");
    PetscPrintf(PETSC_COMM_SELF, "  LEFT(%d):   %.15f\n", LEFT, d[LEFT]);
    PetscPrintf(PETSC_COMM_SELF, "  RIGHT(%d):  %.15f\n", RIGHT, d[RIGHT]);
    PetscPrintf(PETSC_COMM_SELF, "  BOTTOM(%d): %.15f\n", BOTTOM, d[BOTTOM]);
    PetscPrintf(PETSC_COMM_SELF, "  TOP(%d):    %.15f\n", TOP, d[TOP]);
    PetscPrintf(PETSC_COMM_SELF, "  FRONT(%d):  %.15f\n", FRONT, d[FRONT]);
    PetscPrintf(PETSC_COMM_SELF, "  BACK(%d):   %.15f\n", BACK, d[BACK]);
 
    return 0; // Indicate successful execution
}

Here is the caller graph for this function:

LOG_PARTICLE_FIELDS()

PetscErrorCode LOG_PARTICLE_FIELDS	(	UserCtx *	user,
		PetscInt	printInterval
	)

Prints particle fields in a table that automatically adjusts its column widths.

This function retrieves data from the particle swarm and prints a table where the width of each column is determined by the maximum width needed to display the data. Only every 'printInterval'-th particle is printed.

Parameters

[in]	user	Pointer to the UserCtx structure.
[in]	printInterval	Only every printInterval‑th particle is printed.

Returns

PetscErrorCode Returns 0 on success.

Prints particle fields in a table that automatically adjusts its column widths.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_PARTICLE_FIELDS()

Definition at line 400 of file logging.c.

{
    DM swarm = user->swarm;
    PetscErrorCode ierr;
    PetscInt localNumParticles;
    PetscReal *positions = NULL;
    PetscInt64 *particleIDs = NULL;
    PetscMPIInt *particleRanks = NULL;
    PetscInt *cellIDs = NULL;
    PetscReal *weights = NULL;
    PetscReal *velocities = NULL;
    PetscMPIInt rank;
    
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
    LOG_ALLOW(LOCAL,LOG_INFO, "Rank %d is retrieving particle data.\n", rank);
 
    ierr = DMSwarmGetLocalSize(swarm, &localNumParticles); CHKERRQ(ierr);
    LOG_ALLOW(LOCAL,LOG_DEBUG,"Rank %d has %d particles.\n", rank, localNumParticles);
 
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_POSITION), NULL, NULL, (void**)&positions); CHKERRQ(ierr);
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_PID), NULL, NULL, (void**)&particleIDs); CHKERRQ(ierr);
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_RANK), NULL, NULL, (void**)&particleRanks); CHKERRQ(ierr);
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_CELL_ID), NULL, NULL, (void**)&cellIDs); CHKERRQ(ierr);
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_WEIGHT), NULL, NULL, (void**)&weights); CHKERRQ(ierr);
    ierr = DMSwarmGetField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_VELOCITY), NULL, NULL, (void**)&velocities); CHKERRQ(ierr);
    
    /* Compute maximum column widths. */
    int wRank, wPID, wCell, wPos, wVel, wWt;
    wRank = wPID = wCell = wPos = wVel = wWt = 0;
    ierr = ComputeMaxColumnWidths(localNumParticles, particleRanks, particleIDs, cellIDs,
                                  positions, velocities, weights,
                                  &wRank, &wPID, &wCell, &wPos, &wVel, &wWt); CHKERRQ(ierr);
 
    /* Build a header string and a row format string. */
    char headerFmt[256];
    char rowFmt[256];
    BuildHeaderString(headerFmt, sizeof(headerFmt), wRank, wPID, wCell, wPos, wVel, wWt);
    BuildRowFormatString(wRank, wPID, wCell, wPos, wVel, wWt, rowFmt, sizeof(rowFmt));
    
    /* Print header (using synchronized printing for parallel output). */
    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "--------------------------------------------------------------------------------------------------------------\n"); CHKERRQ(ierr);
    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "%s", headerFmt); CHKERRQ(ierr);
    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "--------------------------------------------------------------------------------------------------------------\n"); CHKERRQ(ierr);
    
    /* Loop over particles and print every printInterval-th row. */
    char rowStr[256];
    for (PetscInt i = 0; i < localNumParticles; i++) {
        if (i % printInterval == 0) {
      // ------- DEBUG 
      //char cellStr[TMP_BUF_SIZE], posStr[TMP_BUF_SIZE], velStr[TMP_BUF_SIZE], wtStr[TMP_BUF_SIZE];
      //CellToStr(&cellIDs[3*i], cellStr, TMP_BUF_SIZE);
      //TripleRealToStr(&positions[3*i], posStr, TMP_BUF_SIZE);
      //TripleRealToStr(&velocities[3*i], velStr, TMP_BUF_SIZE);
      // TripleRealToStr(&weights[3*i], wtStr, TMP_BUF_SIZE);
            
      // if (rank == 0) { // Or whatever rank is Rank 0
        //PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] Particle %lld: PID=%lld, Rank=%d\n", (long long)i, (long long)particleIDs[i], particleRanks[i]);
        //PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] Raw Pos: (%.10e, %.10e, %.10e)\n", positions[3*i+0], positions[3*i+1], positions[3*i+2]);
        //PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] Str Pos: %s\n", posStr);
        //PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] Raw Vel: (%.10e, %.10e, %.10e)\n", velocities[3*i+0], velocities[3*i+1], velocities[3*i+2]);
        // PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] Str Vel: %s\n", velStr);
        // Add similar for cell, weights
        // PetscPrintf(PETSC_COMM_SELF, "[Rank 0 DEBUG LPF] About to build rowStr for particle %lld\n", (long long)i);
        //  fflush(stdout);
        // }
 
      //  snprintf(rowStr, sizeof(rowStr), rowFmt,
          //           particleRanks[i],
          //           particleIDs[i],
          //           cellStr,
          //           posStr,
          //           velStr,
      //         wtStr);
 
         
         //    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "%s", rowStr); CHKERRQ(ierr);
      
         // ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "%s", rowStr); CHKERRQ(ierr); 
      
      // -------- DEBUG
            /* Format the row by converting each field to a string first.
             * We use temporary buffers and then build the row string.
             */
      
       char cellStr[TMP_BUF_SIZE], posStr[TMP_BUF_SIZE], velStr[TMP_BUF_SIZE], wtStr[TMP_BUF_SIZE];
            CellToStr(&cellIDs[3*i], cellStr, TMP_BUF_SIZE);
            TripleRealToStr(&positions[3*i], posStr, TMP_BUF_SIZE);
            TripleRealToStr(&velocities[3*i], velStr, TMP_BUF_SIZE);
            TripleRealToStr(&weights[3*i], wtStr, TMP_BUF_SIZE);
            
            /* Build the row string. Note that for the integer fields we can use the row format string. */
            snprintf(rowStr, sizeof(rowStr), rowFmt,
                     particleRanks[i],
                     particleIDs[i],
                     cellStr,
                     posStr,
                     velStr,
                     wtStr);
     ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "%s", rowStr); CHKERRQ(ierr);
        }
    }
 
 
    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "--------------------------------------------------------------------------------------------------------------\n"); CHKERRQ(ierr);
    ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "\n"); CHKERRQ(ierr);
    ierr = PetscSynchronizedFlush(PETSC_COMM_WORLD, PETSC_STDOUT); CHKERRQ(ierr);
 
    LOG_ALLOW_SYNC(GLOBAL,LOG_DEBUG,"Completed printing on Rank %d.\n", rank);
 
    /* Restore fields */
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_POSITION), NULL, NULL, (void**)&positions); CHKERRQ(ierr);
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_PID), NULL, NULL, (void**)&particleIDs); CHKERRQ(ierr);
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_RANK), NULL, NULL, (void**)&particleRanks); CHKERRQ(ierr);
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_CELL_ID), NULL, NULL, (void**)&cellIDs); CHKERRQ(ierr);
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_WEIGHT), NULL, NULL, (void**)&weights); CHKERRQ(ierr);
    ierr = DMSwarmRestoreField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_VELOCITY), NULL, NULL, (void**)&velocities); CHKERRQ(ierr);
 
    LOG_ALLOW(LOCAL,LOG_DEBUG, "Restored all particle fields.\n");
    return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

IsParticleConsoleSnapshotEnabled()

PetscBool IsParticleConsoleSnapshotEnabled

(

const SimCtx *

simCtx

)

Returns whether periodic particle console snapshots are enabled.

This checks only the reporting contract (particles exist, cadence is enabled, and the global log level is at least INFO).

Parameters

simCtx

Simulation context controlling the operation.

Returns

PetscBool indicating the result of IsParticleConsoleSnapshotEnabled().

Returns whether periodic particle console snapshots are enabled.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

IsParticleConsoleSnapshotEnabled()

Definition at line 528 of file logging.c.

{
    if (!simCtx) {
        return PETSC_FALSE;
    }
    return (PetscBool)(simCtx->np > 0 &&
                       simCtx->particleConsoleOutputFreq > 0 &&
                       get_log_level() >= LOG_INFO);
}

Here is the call graph for this function:

Here is the caller graph for this function:

ShouldEmitPeriodicParticleConsoleSnapshot()

PetscBool ShouldEmitPeriodicParticleConsoleSnapshot	(	const SimCtx *	simCtx,
		PetscInt	completed_step
	)

Returns whether a particle console snapshot should be emitted for the.

completed timestep.

Parameters

simCtx	Simulation context controlling the operation.
completed_step	Completed step index used by the decision helper.

Returns

PetscBool indicating the result of ShouldEmitPeriodicParticleConsoleSnapshot().

Returns whether a particle console snapshot should be emitted for the.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ShouldEmitPeriodicParticleConsoleSnapshot()

Definition at line 545 of file logging.c.

{
    return (PetscBool)(IsParticleConsoleSnapshotEnabled(simCtx) &&
                       completed_step > 0 &&
                       completed_step % simCtx->particleConsoleOutputFreq == 0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

EmitParticleConsoleSnapshot()

PetscErrorCode EmitParticleConsoleSnapshot	(	UserCtx *	user,
		SimCtx *	simCtx,
		PetscInt	step
	)

Emits one particle console snapshot into the main solver log.

Parameters

user	Primary UserCtx input for the operation.
simCtx	Simulation context controlling the operation.
step	Step index associated with the operation.

Returns

PetscErrorCode 0 on success.

Emits one particle console snapshot into the main solver log.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

EmitParticleConsoleSnapshot()

Definition at line 559 of file logging.c.

{
    PetscErrorCode ierr;
 
    PetscFunctionBeginUser;
    LOG(GLOBAL, LOG_INFO, "Particle states at step %d:\n", step);
    ierr = LOG_PARTICLE_FIELDS(user, simCtx->LoggingFrequency); CHKERRQ(ierr);
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

IsStatisticsConsoleSnapshotEnabled()

PetscBool IsStatisticsConsoleSnapshotEnabled

(

const struct SimCtx *

simCtx

)

Reports whether the periodic statistics console snapshot is enabled.

Mirrors the particle console gate: the subsystem must be active, the configured cadence positive, and the effective log level at least LOG_INFO.

Parameters

[in]

simCtx

Simulation context to inspect.

Returns

PETSC_TRUE when snapshots should be emitted.

Here is the caller graph for this function:

ShouldEmitPeriodicStatisticsConsoleSnapshot()

PetscBool ShouldEmitPeriodicStatisticsConsoleSnapshot	(	const struct SimCtx *	simCtx,
		PetscInt	completed_step
	)

Reports whether a completed step falls on the console snapshot cadence.

Parameters

[in]	simCtx	Simulation context to inspect.
[in]	completed_step	Step that has just completed.

Returns

PETSC_TRUE when a snapshot is due for this step.

Here is the caller graph for this function:

EmitStatisticsConsoleSnapshot()

PetscErrorCode EmitStatisticsConsoleSnapshot	(	UserCtx *	user,
		const struct SimCtx *	simCtx,
		PetscInt	step
	)

Emits one console snapshot of window progress.

Reports window-level scalars only; it never dumps field data.

Parameters

[in]	user	Finest-level block array supplying accumulator state.
[in]	simCtx	Simulation context carrying the window array.
[in]	step	Step the snapshot describes.

Returns

Zero on success.

Here is the caller graph for this function:

FreeAllowedFunctions()

PetscErrorCode FreeAllowedFunctions	(	char **	funcs,
		PetscInt	n
	)

Free an array previously returned by LoadAllowedFunctionsFromFile().

Parameters

[in,out]	funcs	Array of strings to release (may be NULL).
[in]	n	Number of entries in funcs. Ignored if funcs is NULL.

Returns

0 on success or a PETSc error code.

Free an array previously returned by LoadAllowedFunctionsFromFile().

Local to this translation unit.

Definition at line 652 of file logging.c.

{
  PetscErrorCode ierr;
  PetscFunctionBegin;
  if (funcs) {
    for (PetscInt i = 0; i < n; ++i) {
      ierr = PetscFree(funcs[i]); CHKERRQ(ierr);
    }
    ierr = PetscFree(funcs); CHKERRQ(ierr);
  }
  PetscFunctionReturn(0);
}

Here is the caller graph for this function:

LoadAllowedFunctionsFromFile()

PetscErrorCode LoadAllowedFunctionsFromFile	(	const char	filename[],
		char ***	funcsOut,
		PetscInt *	nOut
	)

Load function names from a text file.

The file is expected to contain one identifier per line. Blank lines and lines whose first non‑blank character is a # are silently skipped so the file can include comments. Example:

# Allowed function list
main
InitializeSimulation
InterpolateAllFieldsToSwarm  # inline comments are OK, too

The routine allocates memory as needed (growing an internal buffer with PetscRealloc()) and returns the resulting array and its length to the caller. Use FreeAllowedFunctions() to clean up when done.

Parameters

[in]	filename	Path of the configuration file to read.
[out]	funcsOut	On success, points to a freshly‑allocated array of char* (size nOut).
[out]	nOut	Number of valid entries in funcsOut.

Returns

0 on success, or a PETSc error code on failure (e.g. I/O error, OOM).

Load function names from a text file.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LoadAllowedFunctionsFromFile()

Definition at line 598 of file logging.c.

{
  FILE          *fp    = NULL;
  char         **funcs = NULL;
  size_t         cap   = 16;   /* initial capacity */
  size_t         n     = 0;    /* number of names  */
  char           line[PETSC_MAX_PATH_LEN];
  PetscErrorCode ierr;
 
  PetscFunctionBegin;
 
  /* ---------------------------------------------------------------------- */
  /* 1. Open file                                                           */
  fp = fopen(filename, "r");
  if (!fp) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN,
                    "Cannot open %s", filename);
 
  /* 2. Allocate initial pointer array                                      */
  ierr = PetscMalloc1(cap, &funcs); CHKERRQ(ierr);
 
  /* 3. Read file line by line                                              */
  while (fgets(line, sizeof line, fp)) {
    /* Strip everything after a comment character '#'. */
    char *hash = strchr(line, '#');
    if (hash) *hash = '\0';
 
    trim(line);                 /* remove leading/trailing blanks */
    if (!*line) continue;       /* skip if empty                  */
 
    /* Grow the array if necessary */
    if (n == cap) {
      cap *= 2;
      ierr = PetscRealloc(cap * sizeof(*funcs), (void **)&funcs); CHKERRQ(ierr);
    }
 
    /* Deep‑copy the cleaned identifier */
    ierr = PetscStrallocpy(line, &funcs[n++]); CHKERRQ(ierr);
  }
  fclose(fp);
 
  /* 4. Return results to caller                                           */
  *funcsOut = funcs;
  *nOut     = (PetscInt)n;
 
  PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

BCFaceToString()

const char * BCFaceToString

(

BCFace

face

)

Returns the canonical log token for a boundary-face enum value.

Parameters

[in]

face

The BCFace enum value.

Returns

Pointer to a constant string representing the face.

Returns the canonical log token for a boundary-face enum value.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

BCFaceToString()

Definition at line 671 of file logging.c.

                                        {
    switch (face) {
        case BC_FACE_NEG_X: return "-Xi (I-Min)";
        case BC_FACE_POS_X: return "+Xi (I-Max)";
        case BC_FACE_NEG_Y: return "-Eta (J-Min)";
        case BC_FACE_POS_Y: return "+Eta (J-Max)";
        case BC_FACE_NEG_Z: return "-Zeta (K-Min)";
        case BC_FACE_POS_Z: return "+Zeta (K-Max)";
        default:            return "Unknown Face";
    }
}

Here is the caller graph for this function:

InitialConditionModeToString()

const char * InitialConditionModeToString

(

InitialConditionMode

mode

)

Convert an initial-condition mode to a string representation.

Parameters

[in]

mode

Initial-condition mode value.

Returns

Pointer to a constant string representing the initial-condition mode.

Convert an initial-condition mode to a string representation.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

InitialConditionModeToString()

Definition at line 689 of file logging.c.

{
    switch(mode){
        case IC_MODE_ZERO: return "Zero";
        case IC_MODE_CONSTANT_CARTESIAN: return "Cartesian Constant";
        case IC_MODE_POISEUILLE: return "Poiseuille";
        case IC_MODE_CONSTANT_STREAMWISE: return "Streamwise Constant";
        case IC_MODE_FILE: return "File";
        default: return "Unknown Initial Condition";
    }
}

Here is the caller graph for this function:

FlowDirectionToString()

const char * FlowDirectionToString

(

FlowDirection

fd

)

Convert a FlowDirection enum value to its YAML token string.

Parameters

[in]

fd

FlowDirection value.

Returns

Token string such as "+Zeta", or "from INLET" when FLOW_DIR_UNSET.

Definition at line 705 of file logging.c.

{
    switch ((int)fd) {
        case FLOW_DIR_POS_XI:   return "+Xi";
        case FLOW_DIR_NEG_XI:   return "-Xi";
        case FLOW_DIR_POS_ETA:  return "+Eta";
        case FLOW_DIR_NEG_ETA:  return "-Eta";
        case FLOW_DIR_POS_ZETA: return "+Zeta";
        case FLOW_DIR_NEG_ZETA: return "-Zeta";
        default:                return "from INLET";
    }
}

Here is the caller graph for this function:

ParticleInitializationToString()

const char * ParticleInitializationToString

(

ParticleInitializationType

ParticleInitialization

)

Returns the canonical log token for a particle-initialization mode.

Parameters

[in]

ParticleInitialization

The ParticleInitialization enum value.

Returns

Pointer to a constant string representing the particle initialization type.

Returns the canonical log token for a particle-initialization mode.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ParticleInitializationToString()

Definition at line 724 of file logging.c.

{
    switch(ParticleInitialization){
        case PARTICLE_INIT_SURFACE_RANDOM: return "Surface: Random";
        case PARTICLE_INIT_VOLUME:         return "Volume";
        case PARTICLE_INIT_POINT_SOURCE:   return "Point Source";
        case PARTICLE_INIT_SURFACE_EDGES:  return "Surface: At edges";
        default: return "Unknown Particle Initialization";
    }
}

Here is the caller graph for this function:

LESModelToString()

const char * LESModelToString

(

LESModelType

LESFlag

)

Returns the canonical log token for an LES model selector.

Parameters

[in]

LESFlag

The LES flag value.

Returns

Pointer to a constant string representing the LES Flag.

Returns the canonical log token for an LES model selector.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LESModelToString()

Definition at line 741 of file logging.c.

{
    switch(LESFlag){
        case NO_LES_MODEL: return "No LES";
        case CONSTANT_SMAGORINSKY: return "Constant Smagorinsky";
        case DYNAMIC_SMAGORINSKY: return "Dynamic Smagorinsky";
        default: return "Unknown LES Flag";
    }
}

Here is the caller graph for this function:

MomentumSolverTypeToString()

const char * MomentumSolverTypeToString

(

MomentumSolverType

SolverFlag

)

Returns the canonical log token for a momentum-solver selector.

Parameters

[in]

SolverFlag

The Momentum Solver flag value.

Returns

Pointer to a constant string representing the MomentumSolverType.

Returns the canonical log token for a momentum-solver selector.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

MomentumSolverTypeToString()

Definition at line 757 of file logging.c.

{
    switch(SolverFlag){
        case MOMENTUM_SOLVER_EXPLICIT_RK: return "Explicit 4 stage Runge-Kutta ";
        case MOMENTUM_SOLVER_DUALTIME_PICARD_JAMESON_RK: return "Dual Time Picard with 4-stage Jameson RK Smoothing";
        case MOMENTUM_SOLVER_NEWTON_KRYLOV: return "Newton Krylov";
        default: return "Unknown Momentum Solver Type";
    }
}

Here is the caller graph for this function:

BCTypeToString()

const char * BCTypeToString

(

BCType

type

)

Returns the canonical log token for a boundary mathematical type.

Parameters

[in]

type

The BCType enum value.

Returns

Pointer to a constant string representing the BC type.

Returns the canonical log token for a boundary mathematical type.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

BCTypeToString()

Definition at line 773 of file logging.c.

                                        {
    switch (type) {
      //  case DIRICHLET: return "DIRICHLET";
      //  case NEUMANN:   return "NEUMANN";
        case WALL:      return "WALL";
        case INLET:     return "INLET";
        case OUTLET:    return "OUTLET";
        case FARFIELD:  return "FARFIELD";
        case PERIODIC:  return "PERIODIC";
        case INTERFACE: return "INTERFACE";
 
    // case CUSTOM:    return "CUSTOM";
        default:        return "Unknown BC Type";
    }
}

Here is the caller graph for this function:

BCHandlerTypeToString()

const char * BCHandlerTypeToString

(

BCHandlerType

handler_type

)

Converts a BCHandlerType enum to its string representation.

Provides a descriptive string for a specific boundary condition implementation strategy. This is crucial for logging the exact behavior configured for a face.

Parameters

handler_type

The BCHandlerType enum value (e.g., BC_HANDLER_WALL_NOSLIP).

Returns

A constant character string corresponding to the enum. Returns "UNKNOWN_HANDLER" if the enum value is not recognized.

Converts a BCHandlerType enum to its string representation.

Local to this translation unit.

Definition at line 793 of file logging.c.

                                                              {
    switch (handler_type) {
        // Wall & Symmetry Handlers
        case BC_HANDLER_WALL_NOSLIP:             return "noslip";
        case BC_HANDLER_WALL_MOVING:             return "moving";
        case BC_HANDLER_SYMMETRY_PLANE:          return "symmetry_plane";
 
        // Inlet Handlers
        case BC_HANDLER_INLET_CONSTANT_VELOCITY: return "constant_velocity";
        case BC_HANDLER_INLET_PULSATILE_FLUX:   return "pulsatile_flux";
        case BC_HANDLER_INLET_PARABOLIC:         return "parabolic";
        case BC_HANDLER_INLET_PROFILE_FROM_FILE: return "prescribed_flow";
 
        // Outlet Handlers
        case BC_HANDLER_OUTLET_CONSERVATION:     return "conservation";
        case BC_HANDLER_OUTLET_PRESSURE:         return "pressure";
 
        // Other Physical Handlers
        case BC_HANDLER_FARFIELD_NONREFLECTING:  return "nonreflecting";
 
        // Multi-Block / Interface Handlers
        case BC_HANDLER_PERIODIC_GEOMETRIC:      return "geometric";
        case BC_HANDLER_PERIODIC_DRIVEN_CONSTANT_FLUX:   return "constant flux";
        case BC_HANDLER_PERIODIC_DRIVEN_INITIAL_FLUX:    return "initial flux";
        case BC_HANDLER_INTERFACE_OVERSET:       return "overset";
 
        // Default case
        case BC_HANDLER_UNDEFINED:
        default:                                 return "UNKNOWN_HANDLER";
    }
}

Here is the caller graph for this function:

DualKSPMonitor()

PetscErrorCode DualKSPMonitor	(	KSP	ksp,
		PetscInt	it,
		PetscReal	rnorm,
		void *	ctx
	)

A custom KSP monitor that logs to a file and optionally to the console.

This function unconditionally calls the standard true residual monitor to log to a file viewer provided in the context. It also checks a flag in the context and, if true, calls the monitor again to log to standard output.

Parameters

ksp	The Krylov subspace context.
it	The current iteration number.
rnorm	The preconditioned residual norm.
ctx	A pointer to the DualMonitorCtx structure.

Returns

PetscErrorCode 0 on success.

A custom KSP monitor that logs to a file and optionally to the console.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

DualKSPMonitor()

Definition at line 870 of file logging.c.

{
    DualMonitorCtx *monctx = (DualMonitorCtx*)ctx;
    PetscErrorCode ierr;
    PetscReal      trnorm, relnorm;
    Vec            r;
    char           norm_buf[256];
    PetscMPIInt    rank;
 
    PetscFunctionBeginUser;
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank); CHKERRQ(ierr);
 
    // 1. Calculate the true residual norm.
    ierr = KSPBuildResidual(ksp, NULL, NULL, &r); CHKERRQ(ierr);
    ierr = VecNorm(r, NORM_2, &trnorm); CHKERRQ(ierr);
    ierr = VecDestroy(&r); CHKERRQ(ierr);
 
    // 2. On the first iteration, compute and store the norm of the RHS vector `b`.
    if (it == 0) {
        Vec b;
        ierr = KSPGetRhs(ksp, &b); CHKERRQ(ierr);
        ierr = VecNorm(b, NORM_2, &monctx->bnorm); CHKERRQ(ierr);
    }
 
    if(!rank){
    // 3. Compute the relative norm and format the output string.
    if (monctx->bnorm > 1.e-15) {
      relnorm = trnorm / monctx->bnorm;
      sprintf(norm_buf, "ts: %-5d | block: %-2d | iter: %-3d | Unprecond Norm: %12.5e | True Norm: %12.5e | Rel Norm: %12.5e",(int)monctx->step, (int)monctx->block_id, (int)it, (double)rnorm, (double)trnorm, (double)relnorm);
    } else {
      sprintf(norm_buf,"ts: %-5d | block: %-2d | iter: %-3d | Unprecond Norm: %12.5e | True Norm: %12.5e",(int)monctx->step, (int)monctx->block_id, (int)it, (double)rnorm, (double)trnorm);
    }
 
    // 4. Log to the file viewer (unconditionally).
    if(monctx->file_handle){
      ierr = PetscFPrintf(PETSC_COMM_SELF,monctx->file_handle,"%s\n", norm_buf); CHKERRQ(ierr);
    }
    // 5. Log to the console (conditionally).
    if (monctx->log_to_console) {
      PetscFPrintf(PETSC_COMM_SELF,stdout, "%s\n", norm_buf); CHKERRQ(ierr);
    }
 
    } //rank
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

DualMonitorDestroy()

PetscErrorCode DualMonitorDestroy

(

void **

ctx

)

Destroys the DualMonitorCtx.

This function is passed to KSPMonitorSet to ensure the viewer is properly destroyed and the context memory is freed when the KSP is destroyed.

Parameters

ctx	a pointer to the context pointer to be destroyed

Returns

PetscErrorCode

Destroys the DualMonitorCtx.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

DualMonitorDestroy()

Definition at line 831 of file logging.c.

{
    DualMonitorCtx *monctx = (DualMonitorCtx*)*ctx;
    PetscErrorCode ierr;
    PetscMPIInt    rank;
    
    PetscFunctionBeginUser;
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank); CHKERRQ(ierr);
    if(!rank && monctx->file_handle){
      fclose(monctx->file_handle);
    }
    
    ierr = PetscFree(monctx); CHKERRQ(ierr);
    *ctx = NULL;
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

LOG_CONTINUITY_METRICS()

PetscErrorCode LOG_CONTINUITY_METRICS

(

UserCtx *

user

)

Logs continuity metrics for a single block to a file.

This function should be called for each block, once per timestep. It opens a central log file in append mode. To ensure the header is written only once, it checks if it is processing block 0 on the simulation's start step.

Parameters

user	A pointer to the UserCtx for the specific block whose metrics are to be logged. The function accesses both global (SimCtx) and local (user->...) data.

Returns

PetscErrorCode 0 on success.

Logs continuity metrics for a single block to a file.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_CONTINUITY_METRICS()

Definition at line 1796 of file logging.c.

{
    PetscErrorCode ierr;
    PetscMPIInt    rank;
    SimCtx         *simCtx = user->simCtx;      // Get the shared SimCtx
    const PetscInt bi = user->_this;          // Get this block's specific ID
    const PetscInt ti = simCtx->step;         // Get the current timestep
 
    PetscFunctionBeginUser;
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
 
    // Only rank 0 performs file I/O.
    if (!rank) {
        FILE *f;
        char filen[PETSC_MAX_PATH_LEN + 64];
        ierr = PetscSNPrintf(filen, sizeof(filen), "%s/Continuity_Metrics.log", simCtx->log_dir); CHKERRQ(ierr);
 
        // Open the log file in append mode.
        f = fopen(filen, "a");
        if (!f) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open log file: %s", filen);
        }
 
        // Write a header only when the file is empty and it's the first block (bi=0).
        // Using ftell() instead of step comparison ensures correctness across continuations.
        if (ftell(f) == 0 && bi == 0) {
            PetscFPrintf(PETSC_COMM_SELF, f, "%-10s | %-6s | %-18s | %-30s | %-18s | %-18s | %-18s | %-18s\n",
                         "Timestep", "Block", "Max Divergence", "Max Divergence Location ([k][j][i]=idx)", "Sum(RHS)","Total Flux In", "Total Flux Out", "Net Flux");
            PetscFPrintf(PETSC_COMM_SELF, f, "------------------------------------------------------------------------------------------------------------------------------------------\n");
        }
        if (simCtx->continueMode && ti == simCtx->StartStep + 1 && bi == 0) {
            PetscFPrintf(PETSC_COMM_SELF, f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
        }
 
        // Prepare the data strings and values for the current block.
        PetscReal net_flux = simCtx->FluxInSum - simCtx->FluxOutSum;
        char location_str[64];
        sprintf(location_str, "([%d][%d][%d] = %d)", (int)simCtx->MaxDivz, (int)simCtx->MaxDivy, (int)simCtx->MaxDivx, (int)simCtx->MaxDivFlatArg);
 
        // Write the formatted line for the current block.
        PetscFPrintf(PETSC_COMM_SELF, f, "%-10d | %-6d | %-18.10e | %-39s | %-18.10e | %-18.10e | %-18.10e | %-18.10e\n",
                     (int)ti,
                     (int)bi,
                     (double)simCtx->MaxDiv,
                     location_str,
                     (double)simCtx->summationRHS,
             (double)simCtx->FluxInSum,
                     (double)simCtx->FluxOutSum,
                     (double)net_flux);
 
        fclose(f);
    }
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

LOG_SOLUTION_CONVERGENCE()

PetscErrorCode LOG_SOLUTION_CONVERGENCE

(

SimCtx *

simCtx

)

Logs physical solution-convergence metrics once per completed timestep.

This logger is intentionally separate from the detailed inner solver-health logs. Depending on the configured mode, it records deterministic step drift, periodic phase-aligned drift, or statistical window drift into logs/solution_convergence.log.

The logger is solver-mode only and is intended to run after a completed flow-solve / projection step but before history vectors are shifted forward. Warmup rows are handled internally:

• steady/transient mode: the first logged step has has_reference = 0
• periodic mode: the first cycle fills the phase reference ring
• statistical mode: window-drift fields remain zero until enough samples exist to form the requested windows

Existing detailed inner logs remain the authoritative source for momentum, Poisson, and continuity health. This logger only summarizes physical solution-drift metrics.

Parameters

[in,out]

simCtx

Master simulation context controlling the logging mode and owning any supporting runtime buffers.

Returns

PetscErrorCode 0 on success.

Logs physical solution-convergence metrics once per completed timestep.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_SOLUTION_CONVERGENCE()

Definition at line 1600 of file logging.c.

{
    PetscMPIInt rank = 0;
    PetscBool   has_reference = PETSC_FALSE;
    PetscInt    phase_step = -1;
    PetscInt    samples_before = 0;
    PetscReal   u_abs_l2 = 0.0, u_rel_l2 = 0.0, p_abs_l2 = 0.0, p_rel_l2 = 0.0;
    PetscReal   mean_speed = 0.0, mean_speed_reference = 0.0, mean_speed_abs_drift = 0.0, mean_speed_rel_drift = 0.0;
    PetscReal   mean_ke = 0.0, mean_ke_reference = 0.0, mean_ke_abs_drift = 0.0, mean_ke_rel_drift = 0.0;
    PetscReal   mean_speed_window = 0.0, mean_speed_window_prev = 0.0, mean_speed_window_abs_drift = 0.0, mean_speed_window_rel_drift = 0.0;
    PetscReal   mean_speed_rms_window = 0.0, mean_speed_rms_window_prev = 0.0, mean_speed_rms_window_abs_drift = 0.0, mean_speed_rms_window_rel_drift = 0.0;
    PetscReal   mean_ke_window = 0.0, mean_ke_window_prev = 0.0, mean_ke_window_abs_drift = 0.0, mean_ke_window_rel_drift = 0.0;
    PetscReal   mean_ke_rms_window = 0.0, mean_ke_rms_window_prev = 0.0, mean_ke_rms_window_abs_drift = 0.0, mean_ke_rms_window_rel_drift = 0.0;
 
    PetscFunctionBeginUser;
    if (!simCtx) PetscFunctionReturn(0);
    if (simCtx->exec_mode != EXEC_MODE_SOLVER) PetscFunctionReturn(0);
    if (!simCtx->solutionConvergenceEnabled) PetscFunctionReturn(0);
 
    samples_before = simCtx->solutionConvergenceSamplesRecorded;
 
    switch (simCtx->solutionConvergenceMode) {
        case SOLUTION_CONVERGENCE_STEADY_DETERMINISTIC:
        case SOLUTION_CONVERGENCE_TRANSIENT:
            PetscCall(ComputeDeterministicSolutionMetrics(simCtx, PETSC_FALSE, -1, samples_before,
                                                          &has_reference,
                                                          &u_abs_l2, &u_rel_l2,
                                                          &p_abs_l2, &p_rel_l2,
                                                          &mean_speed, &mean_speed_reference,
                                                          &mean_speed_abs_drift, &mean_speed_rel_drift,
                                                          &mean_ke, &mean_ke_reference,
                                                          &mean_ke_abs_drift, &mean_ke_rel_drift));
            break;
        case SOLUTION_CONVERGENCE_PERIODIC_DETERMINISTIC:
            phase_step = simCtx->solutionConvergencePeriodSteps > 0 ? (simCtx->step % simCtx->solutionConvergencePeriodSteps) : -1;
            PetscCall(ComputeDeterministicSolutionMetrics(simCtx, PETSC_TRUE, phase_step, samples_before,
                                                          &has_reference,
                                                          &u_abs_l2, &u_rel_l2,
                                                          &p_abs_l2, &p_rel_l2,
                                                          &mean_speed, &mean_speed_reference,
                                                          &mean_speed_abs_drift, &mean_speed_rel_drift,
                                                          &mean_ke, &mean_ke_reference,
                                                          &mean_ke_abs_drift, &mean_ke_rel_drift));
            break;
        case SOLUTION_CONVERGENCE_STATISTICAL_STEADY:
            PetscCall(ComputeCurrentFlowObservables(simCtx, &mean_speed, &mean_ke));
            PetscCall(AppendStatisticalObservableSample(simCtx, samples_before, mean_speed, mean_ke));
            PetscCall(ComputeStatisticalWindowMetrics(simCtx, samples_before + 1,
                                                      &has_reference,
                                                      &mean_speed_window, &mean_speed_window_prev,
                                                      &mean_speed_window_abs_drift, &mean_speed_window_rel_drift,
                                                      &mean_speed_rms_window, &mean_speed_rms_window_prev,
                                                      &mean_speed_rms_window_abs_drift, &mean_speed_rms_window_rel_drift,
                                                      &mean_ke_window, &mean_ke_window_prev,
                                                      &mean_ke_window_abs_drift, &mean_ke_window_rel_drift,
                                                      &mean_ke_rms_window, &mean_ke_rms_window_prev,
                                                      &mean_ke_rms_window_abs_drift, &mean_ke_rms_window_rel_drift));
            break;
        default:
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Unknown solution convergence mode %d.", (int)simCtx->solutionConvergenceMode);
    }
 
    PetscCallMPI(MPI_Comm_rank(PETSC_COMM_WORLD, &rank));
    if (rank == 0) {
        char log_path[PETSC_MAX_PATH_LEN + 32];
        FILE *f = NULL;
        const char *mode_str = SolutionConvergenceModeToString(simCtx->solutionConvergenceMode);
 
        PetscCall(PetscSNPrintf(log_path, sizeof(log_path), "%s/solution_convergence.log", simCtx->log_dir));
        f = fopen(log_path, "a");
        if (!f) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open solution convergence log: %s", log_path);
        }
 
        if (ftell(f) == 0) {
            switch (simCtx->solutionConvergenceMode) {
                case SOLUTION_CONVERGENCE_STEADY_DETERMINISTIC:
                case SOLUTION_CONVERGENCE_TRANSIENT:
                    fprintf(f, "==================== Solution Convergence Log [mode: %s] ====================\n", mode_str);
                    /* 16 columns; header width = 314 chars */
                    fprintf(f, "%-10s | %-18s | %-22s | %-3s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s\n",
                            "step", "time", "mode", "ref",
                            "u_abs_l2", "u_rel_l2", "p_abs_l2", "p_rel_l2",
                            "mean_speed", "spd_ref", "spd_abs", "spd_rel",
                            "mean_ke", "ke_ref", "ke_abs", "ke_rel");
                    fprintf(f, "----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n");
                    break;
                case SOLUTION_CONVERGENCE_PERIODIC_DETERMINISTIC:
                    fprintf(f, "==================== Solution Convergence Log [mode: %s | period_steps: %d] ====================\n",
                            mode_str, (int)simCtx->solutionConvergencePeriodSteps);
                    /* 18 columns; header width = 330 chars */
                    fprintf(f, "%-10s | %-18s | %-22s | %-3s | %-5s | %-5s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s\n",
                            "step", "time", "mode", "ref", "ph", "per",
                            "u_abs_l2", "u_rel_l2", "p_abs_l2", "p_rel_l2",
                            "mean_speed", "spd_ref", "spd_abs", "spd_rel",
                            "mean_ke", "ke_ref", "ke_abs", "ke_rel");
                    fprintf(f, "----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n");
                    break;
                case SOLUTION_CONVERGENCE_STATISTICAL_STEADY:
                    fprintf(f, "==================== Solution Convergence Log [mode: %s | window_steps: %d] ====================\n",
                            mode_str, (int)simCtx->solutionConvergenceWindowSteps);
                    /* 21 columns; header width = 406 chars */
                    fprintf(f, "%-10s | %-18s | %-22s | %-3s | %-5s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s | %-18s\n",
                            "step", "time", "mode", "ref", "win",
                            "mean_speed", "mean_ke",
                            "spd_win", "spd_win_prev", "spd_win_abs", "spd_win_rel",
                            "spd_rms_win", "spd_rms_abs", "spd_rms_rel",
                            "ke_win", "ke_win_prev", "ke_win_abs", "ke_win_rel",
                            "ke_rms_win", "ke_rms_abs", "ke_rms_rel");
                    fprintf(f, "------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\n");
                    break;
                default: break;
            }
        }
        if (simCtx->continueMode && simCtx->step == simCtx->StartStep + 1) {
            fprintf(f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
        }
 
        switch (simCtx->solutionConvergenceMode) {
            case SOLUTION_CONVERGENCE_STEADY_DETERMINISTIC:
            case SOLUTION_CONVERGENCE_TRANSIENT:
                fprintf(f,
                        "%-10d | %-18.10e | %-22s | %-3d | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e\n",
                        (int)simCtx->step, (double)simCtx->ti, mode_str, has_reference ? 1 : 0,
                        (double)u_abs_l2, (double)u_rel_l2, (double)p_abs_l2, (double)p_rel_l2,
                        (double)mean_speed, (double)mean_speed_reference,
                        (double)mean_speed_abs_drift, (double)mean_speed_rel_drift,
                        (double)mean_ke, (double)mean_ke_reference,
                        (double)mean_ke_abs_drift, (double)mean_ke_rel_drift);
                break;
            case SOLUTION_CONVERGENCE_PERIODIC_DETERMINISTIC:
                fprintf(f,
                        "%-10d | %-18.10e | %-22s | %-3d | %-5d | %-5d | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e\n",
                        (int)simCtx->step, (double)simCtx->ti, mode_str, has_reference ? 1 : 0,
                        (int)phase_step, (int)simCtx->solutionConvergencePeriodSteps,
                        (double)u_abs_l2, (double)u_rel_l2, (double)p_abs_l2, (double)p_rel_l2,
                        (double)mean_speed, (double)mean_speed_reference,
                        (double)mean_speed_abs_drift, (double)mean_speed_rel_drift,
                        (double)mean_ke, (double)mean_ke_reference,
                        (double)mean_ke_abs_drift, (double)mean_ke_rel_drift);
                break;
            case SOLUTION_CONVERGENCE_STATISTICAL_STEADY:
                fprintf(f,
                        "%-10d | %-18.10e | %-22s | %-3d | %-5d | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e | %-18.10e\n",
                        (int)simCtx->step, (double)simCtx->ti, mode_str, has_reference ? 1 : 0,
                        (int)simCtx->solutionConvergenceWindowSteps,
                        (double)mean_speed, (double)mean_ke,
                        (double)mean_speed_window, (double)mean_speed_window_prev,
                        (double)mean_speed_window_abs_drift, (double)mean_speed_window_rel_drift,
                        (double)mean_speed_rms_window,
                        (double)mean_speed_rms_window_abs_drift, (double)mean_speed_rms_window_rel_drift,
                        (double)mean_ke_window, (double)mean_ke_window_prev,
                        (double)mean_ke_window_abs_drift, (double)mean_ke_window_rel_drift,
                        (double)mean_ke_rms_window,
                        (double)mean_ke_rms_window_abs_drift, (double)mean_ke_rms_window_rel_drift);
                break;
            default: break;
        }
        fclose(f);
    }
 
    if (simCtx->solutionConvergenceMode == SOLUTION_CONVERGENCE_PERIODIC_DETERMINISTIC &&
        phase_step >= 0 && phase_step < simCtx->solutionConvergencePeriodSteps) {
        UserCtx *user = simCtx->usermg.mgctx[simCtx->usermg.mglevels - 1].user;
        for (PetscInt bi = 0; bi < simCtx->block_number; ++bi) {
            PetscCall(VecCopy(user[bi].Ucat, user[bi].solutionConvergencePeriodicUcatRef[phase_step]));
            PetscCall(VecCopy(user[bi].P, user[bi].solutionConvergencePeriodicPRef[phase_step]));
        }
    }
 
    simCtx->solutionConvergenceSamplesRecorded = samples_before + 1;
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

ParticleLocationStatusToString()

const char * ParticleLocationStatusToString

(

ParticleLocationStatus

level

)

A function that outputs the name of the current level in the ParticleLocation enum.

Parameters

level

The ParticleLocation enum value.

Returns

A constant character string corresponding to the enum. Returns "UNKNOWN_LEVEL" if the enum value is not recognized.

A function that outputs the name of the current level in the ParticleLocation enum.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ParticleLocationStatusToString()

Definition at line 1858 of file logging.c.

{
    switch (level) {
        case NEEDS_LOCATION:        return "NEEDS_LOCATION";
        case ACTIVE_AND_LOCATED: return "ACTIVE_AND_LOCATED";
        case MIGRATING_OUT:     return "MIGRATING_OUT";
        case LOST:               return "LOST";
        case UNINITIALIZED:      return "UNINITIALIZED";
        default:            return "UNKNOWN_LEVEL";
    }
}

Here is the caller graph for this function:

PrintProgressBar()

void PrintProgressBar	(	PetscInt	step,
		PetscInt	startStep,
		PetscInt	totalSteps,
		PetscReal	currentTime
	)

Prints a progress bar to the console.

This function should only be called by the root process (rank 0). It uses a carriage return \r to overwrite the same line in the terminal, creating a dynamic progress bar.

Parameters

step	The current step index from the loop (e.g., from 0 to N-1).
startStep	The global starting step number of the simulation.
totalSteps	The total number of steps to be run in this simulation instance.
currentTime	The current simulation time to display.

Prints a progress bar to the console.

Local to this translation unit.

Definition at line 2302 of file logging.c.

{
    if (totalSteps <= 0) return;
 
    // --- Configuration ---
    const int barWidth = 50;
 
    // --- Calculation ---
    // Calculate progress as a fraction from 0.0 to 1.0
    PetscReal progress = (PetscReal)(step - startStep + 1) / totalSteps;
    // Ensure progress doesn't exceed 1.0 due to floating point inaccuracies
    if (progress > 1.0) progress = 1.0;
 
    int pos = (int)(barWidth * progress);
 
    // --- Printing ---
    // Carriage return moves cursor to the beginning of the line
    PetscPrintf(PETSC_COMM_SELF, "\rProgress: [");
 
    for (int i = 0; i < barWidth; ++i) {
        if (i < pos) {
            PetscPrintf(PETSC_COMM_SELF, "=");
        } else if (i == pos) {
            PetscPrintf(PETSC_COMM_SELF, ">");
        } else {
            PetscPrintf(PETSC_COMM_SELF, " ");
        }
    }
 
    // Print percentage, step count, and current time
    PetscPrintf(PETSC_COMM_SELF, "] %3d%% (Step %" PetscInt_FMT "/%" PetscInt_FMT ", t=%.4f)",
                (int)(progress * 100.0),
                step + 1,
                startStep + totalSteps,
                currentTime);
 
    // Flush the output buffer to ensure the bar is displayed immediately
    fflush(stdout);
}

Here is the caller graph for this function:

ProfilingInitialize()

PetscErrorCode ProfilingInitialize

(

SimCtx *

simCtx

)

Initializes the custom profiling system using configuration from SimCtx.

This function sets up the internal data structures for tracking function performance. It reads the list of "critical functions" from the provided SimCtx and marks them for per-step logging at LOG_INFO level.

It should be called once at the beginning of the application, after CreateSimulationContext() but before the main time loop.

Parameters

simCtx

The master simulation context, which contains the list of critical function names to always log.

Returns

PetscErrorCode

Initializes the custom profiling system using configuration from SimCtx.

Local to this translation unit.

Definition at line 1928 of file logging.c.

{
    PetscFunctionBeginUser;
    if (!simCtx) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be null for ProfilingInitialize");
 
    // Iterate through the list of critical functions provided in SimCtx
    for (PetscInt i = 0; i < simCtx->nProfilingSelectedFuncs; ++i) {
        PetscInt idx;
        const char *func_name = simCtx->profilingSelectedFuncs[i];
        PetscErrorCode ierr = _FindOrCreateEntry(func_name, &idx); CHKERRQ(ierr);
        g_profiler_registry[idx].always_log = PETSC_TRUE;
 
        LOG_ALLOW(GLOBAL, LOG_DEBUG, "Marked '%s' as a critical function for profiling.\n", func_name);
    }
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

ProfilingResetTimestepCounters()

PetscErrorCode ProfilingResetTimestepCounters

(

void

)

Resets per-timestep profiling counters for the next solver step.

This clears transient counters without discarding cumulative totals used by final profiling summaries.

Returns

PetscErrorCode 0 on success.

Resets per-timestep profiling counters for the next solver step.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ProfilingResetTimestepCounters()

Definition at line 1988 of file logging.c.

{
    PetscFunctionBeginUser;
    for (PetscInt i = 0; i < g_profiler_count; ++i) {
        g_profiler_registry[i].current_step_time = 0.0;
        g_profiler_registry[i].current_step_call_count = 0;
    }
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

ProfilingLogTimestepSummary()

PetscErrorCode ProfilingLogTimestepSummary	(	SimCtx *	simCtx,
		PetscInt	step
	)

Logs the performance summary for the current timestep and resets timers.

Depending on the configured profiling timestep mode, this function writes per-step profiling rows to the configured profiling log file:

• off: writes nothing
• selected: writes only functions marked for per-step reporting
• all: writes every instrumented function that ran in the timestep

It must be called once per timestep, typically at the end of the main loop. After logging, it resets the per-step counters and timers.

Parameters

simCtx	The simulation context holding profiling output settings.
step	The current simulation step number, for logging context.

Returns

PetscErrorCode

Logs the performance summary for the current timestep and resets timers.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ProfilingLogTimestepSummary()

Definition at line 2005 of file logging.c.

{
    PetscBool should_write = PETSC_FALSE;
    FILE *f = NULL;
    char filen[(2 * PETSC_MAX_PATH_LEN) + 16];
 
    PetscFunctionBeginUser;
    if (!simCtx) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be null for ProfilingLogTimestepSummary");
 
    if (strcmp(simCtx->profilingTimestepMode, "off") == 0) {
        for (PetscInt i = 0; i < g_profiler_count; ++i) {
            g_profiler_registry[i].current_step_time = 0.0;
            g_profiler_registry[i].current_step_call_count = 0;
        }
        PetscFunctionReturn(0);
    }
 
    for (PetscInt i = 0; i < g_profiler_count; ++i) {
        if (g_profiler_registry[i].current_step_call_count <= 0) {
            continue;
        }
        if (strcmp(simCtx->profilingTimestepMode, "all") == 0 || g_profiler_registry[i].always_log) {
            should_write = PETSC_TRUE;
            break;
        }
    }
 
    if (should_write && simCtx->rank == 0) {
        snprintf(filen, sizeof(filen), "%s/%s", simCtx->log_dir, simCtx->profilingTimestepFile);
        if (step == simCtx->StartStep + 1 && !simCtx->continueMode) {
            f = fopen(filen, "w");
            if (!f) {
                SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open profiling timestep log file: %s", filen);
            }
            PetscFPrintf(PETSC_COMM_SELF, f, "step,function,calls,step_time_s\n");
        } else {
            f = fopen(filen, "a");
            if (!f) {
                SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open profiling timestep log file: %s", filen);
            }
            if (step == simCtx->StartStep + 1 && ftell(f) == 0) {
                PetscFPrintf(PETSC_COMM_SELF, f, "step,function,calls,step_time_s\n");
            }
        }
        if (simCtx->continueMode && step == simCtx->StartStep + 1) {
            PetscFPrintf(PETSC_COMM_SELF, f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
        }
 
        for (PetscInt i = 0; i < g_profiler_count; ++i) {
            if (g_profiler_registry[i].current_step_call_count <= 0) {
                continue;
            }
            if (strcmp(simCtx->profilingTimestepMode, "all") == 0 || g_profiler_registry[i].always_log) {
                PetscFPrintf(
                    PETSC_COMM_SELF,
                    f,
                    "%d,%s,%lld,%.6f\n",
                    (int)step,
                    g_profiler_registry[i].name,
                    g_profiler_registry[i].current_step_call_count,
                    g_profiler_registry[i].current_step_time
                );
            }
        }
        fclose(f);
    }
 
    // Reset per-step counters for the next iteration
    for (PetscInt i = 0; i < g_profiler_count; ++i) {
        g_profiler_registry[i].current_step_time = 0.0;
        g_profiler_registry[i].current_step_call_count = 0;
    }
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

RuntimeMemoryLogSample()

PetscErrorCode RuntimeMemoryLogSample	(	SimCtx *	simCtx,
		PetscInt	step,
		const char *	event,
		const char *	reason
	)

Append a reduced runtime memory sample to the configured memory log.

The log is intentionally compact: every rank samples process/PETSc allocator memory, one max reduction summarizes the job, and rank 0 appends one terminal-readable row.

Parameters

simCtx	The simulation context holding log directory and memory log settings.
step	The solver/post step associated with the sample.
event	Human-readable event label such as "Step", "Post", "Shutdown", or "Final".
reason	Human-readable reason, or NULL/"-" when not applicable.

Returns

PetscErrorCode

Append a reduced runtime memory sample to the configured memory log.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

RuntimeMemoryLogSample()

Definition at line 2086 of file logging.c.

{
    PetscErrorCode ierr;
    PetscLogDouble process_current_bytes = 0.0;
    PetscLogDouble process_peak_bytes = 0.0;
    PetscLogDouble petsc_current_bytes = 0.0;
    PetscLogDouble petsc_peak_bytes = 0.0;
    PetscReal      local_values[5];
    PetscReal      global_values[5];
    PetscReal      process_current_mb = 0.0;
    PetscReal      process_peak_mb = 0.0;
    PetscReal      petsc_current_mb = 0.0;
    PetscReal      petsc_peak_mb = 0.0;
    PetscReal      process_change_mb = 0.0;
    char           path[(2 * PETSC_MAX_PATH_LEN) + 16];
    FILE           *f = NULL;
 
    PetscFunctionBeginUser;
    if (!simCtx) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be null for RuntimeMemoryLogSample");
    if (!simCtx->runtimeMemoryLogEnabled) PetscFunctionReturn(0);
 
    ierr = PetscMemoryGetCurrentUsage(&process_current_bytes); CHKERRQ(ierr);
    ierr = PetscMemoryGetMaximumUsage(&process_peak_bytes); CHKERRQ(ierr);
    ierr = PetscMallocGetCurrentUsage(&petsc_current_bytes); CHKERRQ(ierr);
    ierr = PetscMallocGetMaximumUsage(&petsc_peak_bytes); CHKERRQ(ierr);
 
    process_current_mb = (PetscReal)(process_current_bytes / (1024.0 * 1024.0));
    process_peak_mb    = (PetscReal)(process_peak_bytes / (1024.0 * 1024.0));
    petsc_current_mb   = (PetscReal)(petsc_current_bytes / (1024.0 * 1024.0));
    petsc_peak_mb      = (PetscReal)(petsc_peak_bytes / (1024.0 * 1024.0));
    if (simCtx->runtimeMemoryLogHasPrevious) {
        process_change_mb = process_current_mb - simCtx->runtimeMemoryLogPreviousProcessMB;
    }
 
    local_values[0] = process_current_mb;
    local_values[1] = process_peak_mb;
    local_values[2] = petsc_current_mb;
    local_values[3] = petsc_peak_mb;
    local_values[4] = process_change_mb;
    ierr = MPI_Allreduce(local_values, global_values, 5, MPIU_REAL, MPI_MAX, PETSC_COMM_WORLD); CHKERRMPI(ierr);
 
    simCtx->runtimeMemoryLogPreviousProcessMB = process_current_mb;
    simCtx->runtimeMemoryLogHasPrevious = PETSC_TRUE;
 
    if (simCtx->rank == 0) {
        ierr = PetscSNPrintf(path, sizeof(path), "%s/%s", simCtx->log_dir, simCtx->runtimeMemoryLogFile); CHKERRQ(ierr);
        f = fopen(path, "a");
        if (!f) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open runtime memory log file: %s", path);
 
        if (!simCtx->runtimeMemoryLogStarted) {
            fprintf(f, "# PICurv runtime memory log\n");
            if (simCtx->continueMode) {
                fprintf(f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
            }
            fprintf(
                f,
                "%-8s %-10s %22s %20s %22s %28s %22s %-18s\n",
                "Step",
                "Event",
                "Process Current MB Max",
                "Process Peak MB Max",
                "PETSc Allocated MB Max",
                "PETSc Peak Allocated MB Max",
                "Process Change MB Max",
                "Reason"
            );
            simCtx->runtimeMemoryLogStarted = PETSC_TRUE;
        }
 
        fprintf(
            f,
            "%-8" PetscInt_FMT " %-10s %22.3f %20.3f %22.3f %28.3f %22.3f %-18s\n",
            step,
            event ? event : "-",
            (double)global_values[0],
            (double)global_values[1],
            (double)global_values[2],
            (double)global_values[3],
            (double)global_values[4],
            (reason && reason[0]) ? reason : "-"
        );
        if ((event && (strcmp(event, "Shutdown") == 0 || strcmp(event, "Final") == 0))) {
            fflush(f);
        }
        fclose(f);
    }
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

ProfilingFinalize()

PetscErrorCode ProfilingFinalize

(

SimCtx *

simCtx

)

the profiling excercise and build a profiling summary which is then printed to a log file.

Parameters

simCtx

The Simulation Context Structure that can contains all the data regarding the simulation.

Returns

PetscErrorCode 0 on success.

the profiling excercise and build a profiling summary which is then printed to a log file.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ProfilingFinalize()

Definition at line 2196 of file logging.c.

{
    PetscErrorCode ierr;
    PetscInt rank = simCtx->rank;
    PetscFunctionBeginUser;
    if (!simCtx->profilingFinalSummary) PetscFunctionReturn(0);
    if (!rank) {
        
        char exec_mode_modifier[32] = "Unknown";
        if(simCtx->exec_mode == EXEC_MODE_SOLVER) PetscCall(PetscStrncpy(exec_mode_modifier, "Solver", sizeof(exec_mode_modifier)));
        else if(simCtx->exec_mode == EXEC_MODE_POSTPROCESSOR) PetscCall(PetscStrncpy(exec_mode_modifier, "PostProcessor", sizeof(exec_mode_modifier)));
        //--- Step 0: Create a file viewer for log file
        FILE *f;
        char filen[PETSC_MAX_PATH_LEN + 128];
        ierr = PetscSNPrintf(filen, sizeof(filen), "%s/ProfilingSummary_%s.log",simCtx->log_dir,exec_mode_modifier); CHKERRQ(ierr);
 
        // Open the log file: append with section label in continue mode, truncate otherwise.
        if (simCtx->continueMode) {
            f = fopen(filen, "a");
            if (!f) {
                SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open log file: %s", filen);
            }
            fprintf(f, "\n=== Continuation from step %" PetscInt_FMT " ===\n", simCtx->StartStep);
        } else {
            f = fopen(filen, "w");
            if (!f) {
                SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open log file: %s", filen);
            }
        }
 
        // --- Step 1: Sort the data for readability ---
        qsort(g_profiler_registry, g_profiler_count, sizeof(ProfiledFunction), _CompareProfiledFunctions);
 
        // --- Step 2: Dynamically determine the width for the function name column ---
        PetscInt max_name_len = strlen("Function"); // Start with the header's length
        for (PetscInt i = 0; i < g_profiler_count; ++i) {
            if (g_profiler_registry[i].total_call_count > 0) {
                PetscInt len = strlen(g_profiler_registry[i].name);
                if (len > max_name_len) {
                    max_name_len = len;
                }
            }
        }
        // Add a little padding
        max_name_len += 2; 
 
        // --- Step 3: Define fixed widths for numeric columns for consistent alignment ---
        const int time_width = 18;
        const int count_width = 15;
        const int avg_width = 22;
 
        // --- Step 4: Print the formatted table ---
        PetscFPrintf(PETSC_COMM_SELF, f, "=================================================================================================================\n");
        PetscFPrintf(PETSC_COMM_SELF, f, "                         FINAL PROFILING SUMMARY (Sorted by Total Time)\n");
        PetscFPrintf(PETSC_COMM_SELF, f, "=================================================================================================================\n");
        
        // Header Row
        PetscFPrintf(PETSC_COMM_SELF, f, "%-*s | %-*s | %-*s | %-*s\n",
                    max_name_len, "Function",
                    time_width, "Total Time (s)",
                    count_width, "Call Count",
                    avg_width, "Avg. Time/Call (ms)");
        
        // Separator Line (dynamically sized)
        for (int i = 0; i < max_name_len; i++) PetscFPrintf(PETSC_COMM_SELF, f, "-");
        PetscFPrintf(PETSC_COMM_SELF, f, "-|-");
        for (int i = 0; i < time_width; i++) PetscFPrintf(PETSC_COMM_SELF, f, "-");
        PetscFPrintf(PETSC_COMM_SELF, f, "-|-");
        for (int i = 0; i < count_width; i++) PetscFPrintf(PETSC_COMM_SELF, f, "-");
        PetscFPrintf(PETSC_COMM_SELF, f, "-|-");
        for (int i = 0; i < avg_width; i++) PetscFPrintf(PETSC_COMM_SELF, f, "-");
        PetscFPrintf(PETSC_COMM_SELF, f, "\n");
 
        // Data Rows
        for (PetscInt i = 0; i < g_profiler_count; ++i) {
            if (g_profiler_registry[i].total_call_count > 0) {
                double avg_time_ms = (g_profiler_registry[i].total_time / g_profiler_registry[i].total_call_count) * 1000.0;
                PetscFPrintf(PETSC_COMM_SELF, f, "%-*s | %*.*f | %*lld | %*.*f\n",
                            max_name_len, g_profiler_registry[i].name,
                            time_width, 6, g_profiler_registry[i].total_time,
                            count_width, g_profiler_registry[i].total_call_count,
                            avg_width, 6, avg_time_ms);
                PetscFPrintf(PETSC_COMM_SELF, f, "------------------------------------------------------------------------------------------------------------------\n");
            }
        }
        PetscFPrintf(PETSC_COMM_SELF, f, "==================================================================================================================\n");
    
        fclose(f);
    }
 
    // --- Final Cleanup ---
    PetscFree(g_profiler_registry);
    g_profiler_registry = NULL;
    g_profiler_count = 0;
    g_profiler_capacity = 0;
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

_ProfilingStart()

void _ProfilingStart

(

const char *

func_name

)

Internal profiling hook invoked by PROFILE_FUNCTION_BEGIN.

Parameters

func_name

Function name used by the profiling helper.

Internal profiling hook invoked by PROFILE_FUNCTION_BEGIN.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

_ProfilingStart()

Definition at line 1952 of file logging.c.

{
    PetscInt idx;
    if (_FindOrCreateEntry(func_name, &idx) != 0) return; // Fail silently
    PetscTime(&g_profiler_registry[idx].start_time);
}

Here is the call graph for this function:

Here is the caller graph for this function:

_ProfilingEnd()

void _ProfilingEnd

(

const char *

func_name

)

Internal profiling hook invoked by PROFILE_FUNCTION_END.

Parameters

func_name

Function name used by the profiling helper.

Internal profiling hook invoked by PROFILE_FUNCTION_END.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

_ProfilingEnd()

Definition at line 1966 of file logging.c.

{
    double end_time;
    PetscTime(&end_time);
 
    PetscInt idx;
    if (_FindOrCreateEntry(func_name, &idx) != 0) return; // Fail silently
 
    double elapsed = end_time - g_profiler_registry[idx].start_time;
    g_profiler_registry[idx].total_time += elapsed;
    g_profiler_registry[idx].current_step_time += elapsed;
    g_profiler_registry[idx].total_call_count++;
    g_profiler_registry[idx].current_step_call_count++;
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_FIELD_MIN_MAX()

PetscErrorCode LOG_FIELD_MIN_MAX	(	UserCtx *	user,
		FieldId	field_id
	)

Computes and logs the local and global min/max values of a 3-component vector field.

This utility function inspects a PETSc Vec associated with a DMDA and calculates the minimum and maximum values for each of its three components (e.g., x, y, z) both for the local data on the current MPI rank and for the entire global domain.

It uses the same "smart" logic as the flow solver, ignoring the padding nodes at the IM, JM, and KM boundaries of the grid. The results are printed to the standard output in a formatted, easy-to-read table.

Parameters

[in]	user	Pointer to the user-defined context. Used for grid information (IM, JM, KM) and MPI rank.
[in]	field_id	Typed identity of the field being analyzed.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Computes and logs the local and global min/max values of a 3-component vector field.

Full API contract is documented with the header declaration in include/logging.h.

See also

LOG_FIELD_MIN_MAX()

Definition at line 2349 of file logging.c.

{
    PetscErrorCode ierr;
    PetscInt       i, j, k;
    DMDALocalInfo  info;
    
    FieldView      view;
    Vec            fieldVec = NULL;
    DM             dm = NULL;
    PetscInt       dof;
    FieldLayout    layout;
    const char    *fieldName = NULL;
    const char    *data_layout = NULL;
 
    PetscFunctionBeginUser;
 
    ierr = FieldGetView(user, field_id, &view); CHKERRQ(ierr);
    fieldName = view.descriptor->canonical_name;
    dm = view.dm;
    dof = view.descriptor->dof;
    layout = view.descriptor->layout;
    data_layout = FieldLayoutName(layout);
    fieldVec = (layout == FIELD_LAYOUT_COMPONENT_STAGGERED) ? view.local_vec : view.global_vec;
 
    ierr = DMDAGetLocalInfo(dm, &info); CHKERRQ(ierr);
 
    // --- 2. Define Architecture-Aware Loop Bounds ---
    PetscInt i_start, i_end, j_start, j_end, k_start, k_end;
 
    if (layout == FIELD_LAYOUT_CELL_CENTERED) {
        // For cell-centered data, the physical values are stored from index 1 to N-1.
        // We find the intersection of the rank's owned range [xs, xe) with the
        // physical data range [1, IM-1).
        i_start = PetscMax(info.xs, 1);          i_end = PetscMin(info.xs + info.xm, user->IM);
        j_start = PetscMax(info.ys, 1);          j_end = PetscMin(info.ys + info.ym, user->JM);
        k_start = PetscMax(info.zs, 1);          k_end = PetscMin(info.zs + info.zm, user->KM);
    } else { // For Node- or Face-Centered data
        // The physical values are stored from index 0 to N-1.
        // We find the intersection of the rank's owned range [xs, xe) with the
        // physical data range [0, IM-1].
        i_start = PetscMax(info.xs, 0);          i_end = PetscMin(info.xs + info.xm, user->IM);
        j_start = PetscMax(info.ys, 0);          j_end = PetscMin(info.ys + info.ym, user->JM);
        k_start = PetscMax(info.zs, 0);          k_end = PetscMin(info.zs + info.zm, user->KM);
    }
 
    // --- 3. Barrier for clean, grouped output ---
    ierr = MPI_Barrier(PETSC_COMM_WORLD); CHKERRQ(ierr);
    if (user->simCtx->rank == 0) {
        PetscPrintf(PETSC_COMM_SELF, "\n--- Field Ranges: [%s] (Layout: %s) ---\n", fieldName, data_layout);
    }
 
    // --- 4. Branch on DoF and perform calculation with correct bounds ---
    if (dof == 1) {
        PetscReal    localMin = PETSC_MAX_REAL, localMax = PETSC_MIN_REAL;
        PetscReal    globalMin, globalMax;
        const PetscScalar  ***array;
 
        ierr = DMDAVecGetArrayRead(dm, fieldVec, &array); CHKERRQ(ierr);
        for (k = k_start; k < k_end; k++) {
            for (j = j_start; j < j_end; j++) {
                for (i = i_start; i < i_end; i++) {
                    localMin = PetscMin(localMin, array[k][j][i]);
                    localMax = PetscMax(localMax, array[k][j][i]);
                }
            }
        }
        ierr = DMDAVecRestoreArrayRead(dm, fieldVec, &array); CHKERRQ(ierr);
 
        ierr = MPI_Allreduce(&localMin, &globalMin, 1, MPIU_REAL, MPI_MIN, PETSC_COMM_WORLD); CHKERRQ(ierr);
        ierr = MPI_Allreduce(&localMax, &globalMax, 1, MPIU_REAL, MPI_MAX, PETSC_COMM_WORLD); CHKERRQ(ierr);
 
        PetscSynchronizedPrintf(PETSC_COMM_WORLD, "  [Rank %d] Local Range:  [ %11.4e , %11.4e ]\n", user->simCtx->rank, localMin, localMax);
        ierr = PetscSynchronizedFlush(PETSC_COMM_WORLD, PETSC_STDOUT); CHKERRQ(ierr);
        if (user->simCtx->rank == 0) {
           PetscPrintf(PETSC_COMM_SELF, "  Global Range:         [ %11.4e , %11.4e ]\n", globalMin, globalMax);
        }
 
    } else if (dof == 3) {
        Cmpnts localMin = {PETSC_MAX_REAL, PETSC_MAX_REAL, PETSC_MAX_REAL};
        Cmpnts localMax = {PETSC_MIN_REAL, PETSC_MIN_REAL, PETSC_MIN_REAL};
        Cmpnts globalMin, globalMax;
        const Cmpnts ***array;
 
        ierr = DMDAVecGetArrayRead(dm, fieldVec, &array); CHKERRQ(ierr);
        for (k = k_start; k < k_end; k++) {
            for (j = j_start; j < j_end; j++) {
                for (i = i_start; i < i_end; i++) {
                    localMin.x = PetscMin(localMin.x, array[k][j][i].x);
                    localMin.y = PetscMin(localMin.y, array[k][j][i].y);
                    localMin.z = PetscMin(localMin.z, array[k][j][i].z);
                    localMax.x = PetscMax(localMax.x, array[k][j][i].x);
                    localMax.y = PetscMax(localMax.y, array[k][j][i].y);
                    localMax.z = PetscMax(localMax.z, array[k][j][i].z);
                }
            }
        }
        ierr = DMDAVecRestoreArrayRead(dm, fieldVec, &array); CHKERRQ(ierr);
 
        ierr = MPI_Allreduce(&localMin, &globalMin, 3, MPIU_REAL, MPI_MIN, PETSC_COMM_WORLD); CHKERRQ(ierr);
        ierr = MPI_Allreduce(&localMax, &globalMax, 3, MPIU_REAL, MPI_MAX, PETSC_COMM_WORLD); CHKERRQ(ierr);
 
        ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "  [Rank %d] Local X-Range: [ %11.4e , %11.4e ]\n", user->simCtx->rank, localMin.x, localMax.x);
        ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "  [Rank %d] Local Y-Range: [ %11.4e , %11.4e ]\n", user->simCtx->rank, localMin.y, localMax.y);
        ierr = PetscSynchronizedPrintf(PETSC_COMM_WORLD, "  [Rank %d] Local Z-Range: [ %11.4e , %11.4e ]\n", user->simCtx->rank, localMin.z, localMax.z);
        ierr = PetscSynchronizedFlush(PETSC_COMM_WORLD, PETSC_STDOUT); CHKERRQ(ierr);
 
        if (user->simCtx->rank == 0) {
            PetscPrintf(PETSC_COMM_SELF, "  [Global] X-Range: [ %11.4e , %11.4e ]\n", globalMin.x, globalMax.x);
            PetscPrintf(PETSC_COMM_SELF, "  [Global] Y-Range: [ %11.4e , %11.4e ]\n", globalMin.y, globalMax.y);
            PetscPrintf(PETSC_COMM_SELF, "  [Global] Z-Range: [ %11.4e , %11.4e ]\n", globalMin.z, globalMax.z);
        }
 
    } else {
        SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONG, "LogFieldStatistics only supports fields with 1 or 3 components, but field '%s' has %" PetscInt_FMT ".", fieldName, dof);
    }
 
    // --- 5. Final barrier for clean output ordering ---
    ierr = MPI_Barrier(PETSC_COMM_WORLD); CHKERRQ(ierr);
    if (user->simCtx->rank == 0) {
        PetscPrintf(PETSC_COMM_SELF, "--------------------------------------------\n\n");
    }
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_FIELD_ANATOMY()

PetscErrorCode LOG_FIELD_ANATOMY	(	UserCtx *	user,
		FieldId	field_id,
		const char *	stage_name
	)

Logs the anatomy of a specified field at key boundary locations, respecting the solver's specific grid and variable architecture.

This intelligent diagnostic function inspects a PETSc Vec and prints its values at critical boundary locations (-Xi/+Xi, -Eta/+Eta, -Zeta/+Zeta). It is "architecture-aware":

• Cell-Centered Fields ("Ucat", "P"): It correctly applies the "Shifted Index Architecture," where the value for geometric Cell i is stored at array index i+1. It labels the output to clearly distinguish between true physical values and ghost values.
• Single-Face-Family Fields: Csi/ICsi/IEta/IZet/Centx belong to the I-face family, with corresponding J- and K-face families.
• Component-Staggered Fields ("Ucont" and histories): x/y/z components live on I/J/K faces respectively.
• Node-Centered Fields ("Coordinates"): It uses a direct index mapping, where the value for Node i is stored at index i.

The output is synchronized across MPI ranks to ensure readability and focuses on a slice through the center of the domain to be concise.

Parameters

user	A pointer to the UserCtx structure containing the DMs and Vecs.
field_id	Typed identity of the persistent Eulerian field to log.
stage_name	A string identifier for the current simulation stage (e.g., "After Advection").

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Logs the anatomy of a specified field at key boundary locations, respecting the solver's specific grid and variable architecture.

See also

LOG_FIELD_ANATOMY()

Definition at line 2752 of file logging.c.

{
    FieldView view;
 
    PetscFunctionBeginUser;
    PetscCall(FieldGetView(user, field_id, &view));
    PetscCall(LogFieldAnatomyView(user, view.descriptor->canonical_name, stage_name,
                                  view.dm, view.local_vec, view.descriptor->dof,
                                  view.descriptor->layout));
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_CORNER_FIELD_ANATOMY()

PetscErrorCode LOG_CORNER_FIELD_ANATOMY	(	UserCtx *	user,
		FieldId	corner_field_id,
		const char *	stage_name
	)

Logs the node-layout anatomy of the transient center-to-corner interpolation field.

Parameters

user	Context owning the corner-staging workspace.
corner_field_id	Which corner workspace the caller populated.
stage_name	Printable simulation stage.

Returns

Zero on success.

Logs the node-layout anatomy of the transient center-to-corner interpolation field.

See also

LOG_CORNER_FIELD_ANATOMY()

Definition at line 2838 of file logging.c.

{
    FieldView view;
 
    PetscFunctionBeginUser;
    PetscCheck(user != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx cannot be NULL.");
    PetscCheck(corner_field_id == FIELD_ID_CELL_SCALAR_AT_CORNER ||
               corner_field_id == FIELD_ID_CELL_VECTOR_AT_CORNER,
               PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
               "Corner anatomy logging expects a corner-staging field identity.");
    /* The caller states which workspace it used, so the degree of freedom and DM
     * come from the catalog instead of being inferred from a cached vector. */
    PetscCall(FieldGetView(user, corner_field_id, &view));
    PetscCall(LogFieldAnatomyView(user, view.descriptor->canonical_name, stage_name, view.dm,
                                  view.local_vec, view.descriptor->dof,
                                  view.descriptor->layout));
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_INTERPOLATION_ERROR()

PetscErrorCode LOG_INTERPOLATION_ERROR

(

UserCtx *

user

)

Logs the interpolation error between the analytical and computed solutions.

Parameters

user	Primary UserCtx input for the operation.

Returns

PetscErrorCode 0 on success.

Logs the interpolation error between the analytical and computed solutions.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_INTERPOLATION_ERROR()

Definition at line 2865 of file logging.c.

{
    SimCtx *simCtx = user->simCtx;
    PetscErrorCode ierr;
    DM swarm = user->swarm;
    Vec positionVec, analyticalvelocityVec, velocityVec, errorVec;
    PetscReal Interpolation_error = 0.0;
    PetscReal Maximum_Interpolation_error = 0.0;
    PetscReal AnalyticalSolution_magnitude = 0.0;
    PetscReal ErrorPercentage = 0.0;
    
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "Creating global vectors.\n");
    ierr = DMSwarmCreateGlobalVectorFromField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_POSITION), &positionVec); CHKERRQ(ierr);
    ierr = DMSwarmCreateGlobalVectorFromField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_VELOCITY), &velocityVec); CHKERRQ(ierr);
    
    ierr = VecDuplicate(positionVec, &analyticalvelocityVec); CHKERRQ(ierr);
    ierr = VecCopy(positionVec, analyticalvelocityVec); CHKERRQ(ierr);
    
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "Computing analytical solution.\n");
    ierr = SetAnalyticalSolutionForParticles(analyticalvelocityVec, simCtx); CHKERRQ(ierr);
    
    ierr = VecDuplicate(analyticalvelocityVec, &errorVec); CHKERRQ(ierr);
    ierr = VecCopy(analyticalvelocityVec, errorVec); CHKERRQ(ierr);
    
    ierr = VecNorm(analyticalvelocityVec, NORM_2, &AnalyticalSolution_magnitude); CHKERRQ(ierr);
    
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "Computing error.\n");
    ierr = VecAXPY(errorVec, -1.0, velocityVec); CHKERRQ(ierr);
    ierr = VecNorm(errorVec, NORM_2, &Interpolation_error); CHKERRQ(ierr);
    ierr = VecNorm(errorVec,NORM_INFINITY,&Maximum_Interpolation_error); CHKERRQ(ierr);
    
    ErrorPercentage = (AnalyticalSolution_magnitude > 0) ?
                      (Interpolation_error / AnalyticalSolution_magnitude * 100.0) : 0.0;
 
    /* --- CSV output (always, rank 0 only) --- */
    if (simCtx->rank == 0) {
        char csv_path[PETSC_MAX_PATH_LEN + 32];
        ierr = PetscSNPrintf(csv_path, sizeof(csv_path), "%s/interpolation_error.csv", simCtx->log_dir); CHKERRQ(ierr);
        FILE *f = fopen(csv_path, "a");
        if (f) {
            if (ftell(f) == 0) {
                fprintf(f, "step,time,L2_error,Linf_error,L2_analytical,error_pct\n");
            }
            if (simCtx->continueMode && simCtx->step == simCtx->StartStep + 1) {
                fprintf(f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
            }
            PetscReal t = (PetscReal)simCtx->ti * simCtx->dt;
            fprintf(f, "%d,%.6e,%.6e,%.6e,%.6e,%.4f\n",
                    (int)simCtx->step, t,
                    Interpolation_error, Maximum_Interpolation_error,
                    AnalyticalSolution_magnitude, ErrorPercentage);
            fclose(f);
        }
    }
 
    /* --- Console output (only at INFO level or above) --- */
    if (get_log_level() >= LOG_INFO) {
        LOG_ALLOW(GLOBAL, LOG_INFO, "Interpolation error (%%): %g\n", ErrorPercentage);
        PetscPrintf(PETSC_COMM_WORLD, "Interpolation error (%%): %g\n", ErrorPercentage);
        LOG_ALLOW(GLOBAL, LOG_INFO, "Maximum Interpolation error: %g\n", Maximum_Interpolation_error);
        PetscPrintf(PETSC_COMM_WORLD, "Maximum Interpolation error: %g\n", Maximum_Interpolation_error);
    }
 
    ierr = VecDestroy(&analyticalvelocityVec); CHKERRQ(ierr);
    ierr = VecDestroy(&errorVec); CHKERRQ(ierr);
    ierr = DMSwarmDestroyGlobalVectorFromField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_POSITION), &positionVec); CHKERRQ(ierr);
    ierr = DMSwarmDestroyGlobalVectorFromField(swarm, ParticleFieldName(PARTICLE_FIELD_ID_VELOCITY), &velocityVec); CHKERRQ(ierr);
    
    return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_SCATTER_METRICS()

PetscErrorCode LOG_SCATTER_METRICS

(

UserCtx *

user

)

Logs particle-to-grid scatter verification metrics for the prescribed scalar truth path.

Parameters

user	Primary UserCtx input for the operation.

Returns

PetscErrorCode 0 on success.

Logs particle-to-grid scatter verification metrics for the prescribed scalar truth path.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_SCATTER_METRICS()

Definition at line 2944 of file logging.c.

{
    PetscErrorCode ierr;
    SimCtx        *simCtx = NULL;
    DMDALocalInfo  info;
    PetscInt       xs, xe, ys, ye, zs, ze, mx, my, mz;
    PetscInt       lxs, lxe, lys, lye, lzs, lze;
    Vec            reference_vec = NULL;
    PetscReal    ***psi = NULL;
    PetscReal    ***psi_ref = NULL;
    PetscReal    ***aj = NULL;
    PetscReal    ***count = NULL;
    PetscReal     *particle_psi = NULL;
    PetscInt       nlocal = 0;
    PetscReal      local_l1 = 0.0, global_l1 = 0.0;
    PetscReal      local_l2_sq = 0.0, global_l2_sq = 0.0;
    PetscReal      local_linf = 0.0, global_linf = 0.0;
    PetscReal      local_ref_l2_sq = 0.0, global_ref_l2_sq = 0.0;
    PetscReal      local_grid_integral = 0.0, global_grid_integral = 0.0;
    PetscReal      local_domain_volume = 0.0, global_domain_volume = 0.0;
    PetscReal      local_particle_sum = 0.0, global_particle_sum = 0.0;
    PetscInt64     local_particle_count = 0, global_particle_count = 0;
    PetscInt64     local_cell_count = 0, global_cell_count = 0;
    PetscInt64     local_occupied_count = 0, global_occupied_count = 0;
    PetscReal      particle_integral = 0.0;
    PetscReal      occupancy_fraction = 0.0;
    PetscReal      mean_particles_per_occupied_cell = 0.0;
    PetscReal      l2_error = 0.0;
    PetscReal      relative_l2_error = 0.0;
 
    PetscFunctionBeginUser;
    if (!user) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx cannot be NULL.");
    simCtx = user->simCtx;
    if (!VerificationScalarOverrideActive(simCtx) || !user->swarm || !user->Psi || !user->ParticleCount) {
        PetscFunctionReturn(0);
    }
 
    info = user->info;
    xs = info.xs; xe = info.xs + info.xm;
    ys = info.ys; ye = info.ys + info.ym;
    zs = info.zs; ze = info.zs + info.zm;
    mx = info.mx; my = info.my; mz = info.mz;
    lxs = (xs == 0) ? xs + 1 : xs; lxe = (xe == mx) ? xe - 1 : xe;
    lys = (ys == 0) ? ys + 1 : ys; lye = (ye == my) ? ye - 1 : ye;
    lzs = (zs == 0) ? zs + 1 : zs; lze = (ze == mz) ? ze - 1 : ze;
 
    ierr = VecDuplicate(user->Psi, &reference_vec); CHKERRQ(ierr);
    ierr = SetAnalyticalScalarFieldAtCellCenters(user, reference_vec); CHKERRQ(ierr);
 
    ierr = DMDAVecGetArrayRead(user->da, user->Psi, &psi); CHKERRQ(ierr);
    ierr = DMDAVecGetArrayRead(user->da, reference_vec, &psi_ref); CHKERRQ(ierr);
    ierr = DMDAVecGetArrayRead(user->da, user->Aj, &aj); CHKERRQ(ierr);
    ierr = DMDAVecGetArrayRead(user->da, user->ParticleCount, &count); CHKERRQ(ierr);
 
    for (PetscInt k = lzs; k < lze; ++k) {
        for (PetscInt j = lys; j < lye; ++j) {
            for (PetscInt i = lxs; i < lxe; ++i) {
                const PetscReal cell_volume = (PetscAbsReal(aj[k][j][i]) > 1.0e-14) ? (1.0 / aj[k][j][i]) : 0.0;
                const PetscReal err = psi[k][j][i] - psi_ref[k][j][i];
                local_cell_count += 1;
                local_domain_volume += cell_volume;
                local_grid_integral += psi[k][j][i] * cell_volume;
                local_l1 += PetscAbsReal(err) * cell_volume;
                local_l2_sq += err * err * cell_volume;
                local_ref_l2_sq += psi_ref[k][j][i] * psi_ref[k][j][i] * cell_volume;
                local_linf = PetscMax(local_linf, PetscAbsReal(err));
                if (count[k][j][i] > 0.0) local_occupied_count += 1;
            }
        }
    }
 
    ierr = DMDAVecRestoreArrayRead(user->da, user->ParticleCount, &count); CHKERRQ(ierr);
    ierr = DMDAVecRestoreArrayRead(user->da, user->Aj, &aj); CHKERRQ(ierr);
    ierr = DMDAVecRestoreArrayRead(user->da, reference_vec, &psi_ref); CHKERRQ(ierr);
    ierr = DMDAVecRestoreArrayRead(user->da, user->Psi, &psi); CHKERRQ(ierr);
    ierr = VecDestroy(&reference_vec); CHKERRQ(ierr);
 
    ierr = DMSwarmGetLocalSize(user->swarm, &nlocal); CHKERRQ(ierr);
    local_particle_count = (PetscInt64)nlocal;
    if (nlocal > 0) {
        ierr = DMSwarmGetField(user->swarm, ParticleFieldName(PARTICLE_FIELD_ID_PSI), NULL, NULL, (void **)&particle_psi); CHKERRQ(ierr);
        for (PetscInt p = 0; p < nlocal; ++p) local_particle_sum += particle_psi[p];
        ierr = DMSwarmRestoreField(user->swarm, ParticleFieldName(PARTICLE_FIELD_ID_PSI), NULL, NULL, (void **)&particle_psi); CHKERRQ(ierr);
    }
 
    ierr = MPI_Allreduce(&local_l1, &global_l1, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_l2_sq, &global_l2_sq, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_linf, &global_linf, 1, MPIU_REAL, MPI_MAX, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_ref_l2_sq, &global_ref_l2_sq, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_grid_integral, &global_grid_integral, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_domain_volume, &global_domain_volume, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_particle_sum, &global_particle_sum, 1, MPIU_REAL, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_particle_count, &global_particle_count, 1, MPIU_INT64, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_cell_count, &global_cell_count, 1, MPIU_INT64, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(&local_occupied_count, &global_occupied_count, 1, MPIU_INT64, MPI_SUM, PETSC_COMM_WORLD); CHKERRMPI(ierr);
 
    l2_error = PetscSqrtReal(global_l2_sq);
    relative_l2_error = (global_ref_l2_sq > 0.0) ? (l2_error / PetscSqrtReal(global_ref_l2_sq)) : 0.0;
    occupancy_fraction = (global_cell_count > 0) ? ((PetscReal)global_occupied_count / (PetscReal)global_cell_count) : 0.0;
    mean_particles_per_occupied_cell =
      (global_occupied_count > 0) ? ((PetscReal)global_particle_count / (PetscReal)global_occupied_count) : 0.0;
    particle_integral =
      (global_particle_count > 0) ? (global_domain_volume * global_particle_sum / (PetscReal)global_particle_count) : 0.0;
 
    if (simCtx->rank == 0) {
        char csv_path[PETSC_MAX_PATH_LEN + 32];
        FILE *f = NULL;
        ierr = PetscSNPrintf(csv_path, sizeof(csv_path), "%s/scatter_metrics.csv", simCtx->log_dir); CHKERRQ(ierr);
        f = fopen(csv_path, "a");
        if (f) {
            if (ftell(f) == 0) {
                fprintf(f,
                        "step,time,total_particles,total_cells,occupied_cells,occupancy_fraction,"
                        "mean_particles_per_occupied_cell,particle_integral,grid_integral,"
                        "conservation_error_abs,L1_error,L2_error,Linf_error,relative_L2_error\n");
            }
            if (simCtx->continueMode && simCtx->step == simCtx->StartStep + 1) {
                fprintf(f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
            }
            fprintf(f, "%d,%.6e,%lld,%lld,%lld,%.6e,%.6e,%.6e,%.6e,%.6e,%.6e,%.6e,%.6e,%.6e\n",
                    (int)simCtx->step,
                    (double)simCtx->ti,
                    (long long)global_particle_count,
                    (long long)global_cell_count,
                    (long long)global_occupied_count,
                    (double)occupancy_fraction,
                    (double)mean_particles_per_occupied_cell,
                    (double)particle_integral,
                    (double)global_grid_integral,
                    (double)PetscAbsReal(global_grid_integral - particle_integral),
                    (double)global_l1,
                    (double)l2_error,
                    (double)global_linf,
                    (double)relative_l2_error);
            fclose(f);
        }
    }
 
    if (get_log_level() >= LOG_INFO) {
        LOG_ALLOW(GLOBAL, LOG_INFO, "Scatter relative L2 error: %.6e\n", (double)relative_l2_error);
        LOG_ALLOW(GLOBAL, LOG_INFO, "Scatter occupancy fraction: %.6e\n", (double)occupancy_fraction);
    }
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

ResetSearchMetrics()

PetscErrorCode ResetSearchMetrics

(

SimCtx *

simCtx

)

Resets the aggregate per-timestep search instrumentation counters.

Parameters

simCtx

Simulation context whose search metrics should be zeroed.

Returns

PetscErrorCode 0 on success.

Resets the aggregate per-timestep search instrumentation counters.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

ResetSearchMetrics()

Definition at line 3098 of file logging.c.

{
    PetscFunctionBeginUser;
    if (!simCtx) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "SimCtx cannot be NULL for ResetSearchMetrics.");
 
    simCtx->searchMetrics.searchAttempts = 0;
    simCtx->searchMetrics.searchPopulation = 0;
    simCtx->searchMetrics.searchLocatedCount = 0;
    simCtx->searchMetrics.searchLostCount = 0;
    simCtx->searchMetrics.traversalStepsSum = 0;
    simCtx->searchMetrics.reSearchCount = 0;
    simCtx->searchMetrics.maxTraversalSteps = 0;
    simCtx->searchMetrics.maxTraversalFailCount = 0;
    simCtx->searchMetrics.tieBreakCount = 0;
    simCtx->searchMetrics.boundaryClampCount = 0;
    simCtx->searchMetrics.bboxGuessSuccessCount = 0;
    simCtx->searchMetrics.bboxGuessFallbackCount = 0;
    simCtx->searchMetrics.maxParticlePassDepth = 0;
    simCtx->searchMetrics.currentSettlementPass = 0;
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

CalculateAdvancedParticleMetrics()

PetscErrorCode CalculateAdvancedParticleMetrics

(

UserCtx *

user

)

Computes advanced particle statistics and stores them in SimCtx.

This function calculates:

• Particle load imbalance across MPI ranks.
• The total number of grid cells occupied by at least one particle.

It requires that CalculateParticleCountPerCell() has been called prior to its execution. It uses collective MPI operations and must be called by all ranks.

Parameters

user	Pointer to the UserCtx.

Returns

PetscErrorCode 0 on success.

Computes advanced particle statistics and stores them in SimCtx.

Local to this translation unit.

Definition at line 3283 of file logging.c.

{
    PetscErrorCode ierr;
    SimCtx         *simCtx = user->simCtx;
    PetscMPIInt    size, rank;
 
    PetscFunctionBeginUser;
    ierr = MPI_Comm_size(PETSC_COMM_WORLD, &size); CHKERRQ(ierr);
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
 
    // --- 1. Particle Load Imbalance ---
    PetscInt nLocal, nGlobal, nLocalMax;
    ierr = DMSwarmGetLocalSize(user->swarm, &nLocal); CHKERRQ(ierr);
    ierr = DMSwarmGetSize(user->swarm, &nGlobal); CHKERRQ(ierr);
    ierr = MPI_Allreduce(&nLocal, &nLocalMax, 1, MPIU_INT, MPI_MAX, PETSC_COMM_WORLD); CHKERRQ(ierr);
 
    PetscReal avg_per_rank = (size > 0) ? ((PetscReal)nGlobal / size) : 0.0;
    // Handle division by zero if there are no particles
    simCtx->particleLoadImbalance = (avg_per_rank > 1e-9) ? (nLocalMax / avg_per_rank) : 1.0;
 
 
    // --- 2. Number of Occupied Cells ---
    // This part requires access to the user->ParticleCount vector.
    PetscInt       local_occupied_cells = 0;
    PetscInt       global_occupied_cells;
    const PetscScalar *count_array;
    PetscInt       vec_local_size;
 
    ierr = VecGetLocalSize(user->ParticleCount, &vec_local_size); CHKERRQ(ierr);
    ierr = VecGetArrayRead(user->ParticleCount, &count_array); CHKERRQ(ierr);
 
    for (PetscInt i = 0; i < vec_local_size; ++i) {
        if (count_array[i] > 0.5) { // Use 0.5 to be safe with floating point
            local_occupied_cells++;
        }
    }
    ierr = VecRestoreArrayRead(user->ParticleCount, &count_array); CHKERRQ(ierr);
 
    ierr = MPI_Allreduce(&local_occupied_cells, &global_occupied_cells, 1, MPIU_INT, MPI_SUM, PETSC_COMM_WORLD); CHKERRQ(ierr);
    simCtx->occupiedCellCount = global_occupied_cells;
 
    LOG_ALLOW_SYNC(GLOBAL, LOG_INFO, "[Rank %d] Advanced Metrics: Imbalance=%.2f, OccupiedCells=%d\n", rank, simCtx->particleLoadImbalance, simCtx->occupiedCellCount);
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

LOG_SEARCH_METRICS()

PetscErrorCode LOG_SEARCH_METRICS

(

UserCtx *

user

)

Writes compact runtime search metrics to CSV and optionally to console.

The CSV artifact is always written for particle-enabled runs. Console output remains gated by normal logging level and function allow-listing.

Parameters

user	Pointer to the UserCtx.

Returns

PetscErrorCode 0 on success.

Writes compact runtime search metrics to CSV and optionally to console.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_SEARCH_METRICS()

Definition at line 3129 of file logging.c.

{
    PetscErrorCode ierr;
    SimCtx         *simCtx = NULL;
    PetscInt       totalParticles = 0;
    PetscReal      local_metrics[SEARCH_METRIC_REDUCTION_LEN] = {0.0};
    PetscReal      global_metrics[SEARCH_METRIC_REDUCTION_LEN] = {0.0};
    PetscReal      meanTraversalSteps = 0.0;
    PetscReal      searchFailureFraction = 0.0;
    PetscReal      searchWorkIndex = 0.0;
    PetscReal      reSearchFraction = 0.0;
    long long      searchAttempts = 0;
    long long      searchPopulation = 0;
    long long      searchLocatedCount = 0;
    long long      searchLostCount = 0;
    long long      traversalStepsSum = 0;
    long long      reSearchCount = 0;
    long long      tieBreakCount = 0;
    long long      boundaryClampCount = 0;
    long long      bboxGuessSuccessCount = 0;
    long long      bboxGuessFallbackCount = 0;
    long long      maxTraversalFailCount = 0;
    long long      maxTraversalSteps = 0;
    long long      maxPassDepth = 0;
    MPI_Op         reduction_op = MPI_OP_NULL;
 
    PetscFunctionBeginUser;
    if (!user || !user->simCtx) {
        SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx and SimCtx are required for LOG_SEARCH_METRICS.");
    }
    simCtx = user->simCtx;
 
    if (simCtx->np <= 0) {
        PetscFunctionReturn(0);
    }
 
    ierr = DMSwarmGetSize(user->swarm, &totalParticles); CHKERRQ(ierr);
 
    local_metrics[SEARCH_METRIC_SUM_SEARCH_ATTEMPTS] = (PetscReal)simCtx->searchMetrics.searchAttempts;
    local_metrics[SEARCH_METRIC_SUM_SEARCH_POPULATION] = (PetscReal)simCtx->searchMetrics.searchPopulation;
    local_metrics[SEARCH_METRIC_SUM_SEARCH_LOCATED] = (PetscReal)simCtx->searchMetrics.searchLocatedCount;
    local_metrics[SEARCH_METRIC_SUM_SEARCH_LOST] = (PetscReal)simCtx->searchMetrics.searchLostCount;
    local_metrics[SEARCH_METRIC_SUM_TRAVERSAL_STEPS] = (PetscReal)simCtx->searchMetrics.traversalStepsSum;
    local_metrics[SEARCH_METRIC_SUM_RESEARCH] = (PetscReal)simCtx->searchMetrics.reSearchCount;
    local_metrics[SEARCH_METRIC_SUM_TIE_BREAKS] = (PetscReal)simCtx->searchMetrics.tieBreakCount;
    local_metrics[SEARCH_METRIC_SUM_BOUNDARY_CLAMPS] = (PetscReal)simCtx->searchMetrics.boundaryClampCount;
    local_metrics[SEARCH_METRIC_SUM_BBOX_GUESS_SUCCESS] = (PetscReal)simCtx->searchMetrics.bboxGuessSuccessCount;
    local_metrics[SEARCH_METRIC_SUM_BBOX_GUESS_FALLBACK] = (PetscReal)simCtx->searchMetrics.bboxGuessFallbackCount;
    local_metrics[SEARCH_METRIC_SUM_MAX_TRAVERSAL_FAILS] = (PetscReal)simCtx->searchMetrics.maxTraversalFailCount;
    local_metrics[SEARCH_METRIC_MAX_TRAVERSAL_STEPS] = (PetscReal)simCtx->searchMetrics.maxTraversalSteps;
    local_metrics[SEARCH_METRIC_MAX_PASS_DEPTH] = (PetscReal)simCtx->searchMetrics.maxParticlePassDepth;
 
    ierr = MPI_Op_create(SearchMetricsReduceOp, PETSC_TRUE, &reduction_op); CHKERRMPI(ierr);
    ierr = MPI_Allreduce(local_metrics, global_metrics, SEARCH_METRIC_REDUCTION_LEN, MPIU_REAL, reduction_op, PETSC_COMM_WORLD); CHKERRMPI(ierr);
    ierr = MPI_Op_free(&reduction_op); CHKERRMPI(ierr);
    reduction_op = MPI_OP_NULL;
 
    searchAttempts = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_SEARCH_ATTEMPTS] + 0.5);
    searchPopulation = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_SEARCH_POPULATION] + 0.5);
    searchLocatedCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_SEARCH_LOCATED] + 0.5);
    searchLostCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_SEARCH_LOST] + 0.5);
    traversalStepsSum = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_TRAVERSAL_STEPS] + 0.5);
    reSearchCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_RESEARCH] + 0.5);
    tieBreakCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_TIE_BREAKS] + 0.5);
    boundaryClampCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_BOUNDARY_CLAMPS] + 0.5);
    bboxGuessSuccessCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_BBOX_GUESS_SUCCESS] + 0.5);
    bboxGuessFallbackCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_BBOX_GUESS_FALLBACK] + 0.5);
    maxTraversalFailCount = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_SUM_MAX_TRAVERSAL_FAILS] + 0.5);
    maxTraversalSteps = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_MAX_TRAVERSAL_STEPS] + 0.5);
    maxPassDepth = (long long)PetscFloorReal(global_metrics[SEARCH_METRIC_MAX_PASS_DEPTH] + 0.5);
 
    if (searchAttempts > 0) {
        meanTraversalSteps = (PetscReal)traversalStepsSum / (PetscReal)searchAttempts;
    }
    if (searchPopulation > 0) {
        searchFailureFraction = (PetscReal)searchLostCount / (PetscReal)searchPopulation;
        searchWorkIndex = (PetscReal)traversalStepsSum / (PetscReal)searchPopulation;
        reSearchFraction = (PetscReal)reSearchCount / (PetscReal)searchPopulation;
    }
 
    if (simCtx->rank == 0) {
        char csv_path[PETSC_MAX_PATH_LEN + 32];
        FILE *f = NULL;
 
        ierr = PetscSNPrintf(csv_path, sizeof(csv_path), "%s/search_metrics.csv", simCtx->log_dir); CHKERRQ(ierr);
        f = fopen(csv_path, "a");
        if (!f) {
            LOG_ALLOW(GLOBAL, LOG_WARNING, "LOG_SEARCH_METRICS: could not open '%s' for writing.\n", csv_path);
        } else {
            if (ftell(f) == 0) {
                fprintf(f,
                        "step,time,total_particles,lost,lost_cumulative,migrated,migration_passes,search_attempts,"
                        "mean_traversal_steps,max_traversal_steps,tie_break_count,boundary_clamp_count,"
                        "bbox_guess_success_count,bbox_guess_fallback_count,max_particle_pass_depth,load_imbalance,"
                        "search_population,search_located_count,search_lost_count,traversal_steps_sum,re_search_count,"
                        "max_traversal_fail_count,search_failure_fraction,search_work_index,re_search_fraction\n");
            }
            if (simCtx->continueMode && simCtx->step == simCtx->StartStep + 1) {
                fprintf(f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
            }
            fprintf(f,
                    "%d,%.6e,%d,%d,%d,%d,%d,%lld,%.6e,%lld,%lld,%lld,%lld,%lld,%lld,%.6e,%lld,%lld,%lld,%lld,%lld,%lld,%.6e,%.6e,%.6e\n",
                    (int)simCtx->step,
                    (double)simCtx->ti,
                    (int)totalParticles,
                    (int)simCtx->particlesLostLastStep,
                    (int)simCtx->particlesLostCumulative,
                    (int)simCtx->particlesMigratedLastStep,
                    (int)simCtx->migrationPassesLastStep,
                    searchAttempts,
                    (double)meanTraversalSteps,
                    maxTraversalSteps,
                    tieBreakCount,
                    boundaryClampCount,
                    bboxGuessSuccessCount,
                    bboxGuessFallbackCount,
                    maxPassDepth,
                    (double)simCtx->particleLoadImbalance,
                    searchPopulation,
                    searchLocatedCount,
                    searchLostCount,
                    traversalStepsSum,
                    reSearchCount,
                    maxTraversalFailCount,
                    (double)searchFailureFraction,
                    (double)searchWorkIndex,
                    (double)reSearchFraction);
            fclose(f);
        }
    }
 
    LOG_ALLOW(GLOBAL, LOG_DEBUG,
              "Search metrics: sff=%.3e swi=%.3e re_search=%.3e lost(step/total)=%d/%d migrated=%d passes=%d traversal(mean/max)=%.2f/%lld tie_breaks=%lld max_pass_depth=%lld\n",
              (double)searchFailureFraction,
              (double)searchWorkIndex,
              (double)reSearchFraction,
              (int)simCtx->particlesLostLastStep,
              (int)simCtx->particlesLostCumulative,
              (int)simCtx->particlesMigratedLastStep,
              (int)simCtx->migrationPassesLastStep,
              (double)meanTraversalSteps,
              maxTraversalSteps,
              tieBreakCount,
              maxPassDepth);
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

LOG_PARTICLE_METRICS()

PetscErrorCode LOG_PARTICLE_METRICS	(	UserCtx *	user,
		const char *	stageName
	)

Logs particle swarm metrics, adapting its behavior based on a boolean flag in SimCtx.

This function serves a dual purpose:

1. If simCtx->isInitializationPhase is PETSC_TRUE, it logs settlement diagnostics to "Initialization_Metrics.log", using the provided stageName.
2. If simCtx->isInitializationPhase is PETSC_FALSE, it logs regular timestep metrics to "Particle_Metrics.log".

Parameters

user	A pointer to the UserCtx.
stageName	A descriptive label recorded in the metrics log (for example, initialization stage name or "Timestep Metrics").

Returns

PetscErrorCode 0 on success.

Logs particle swarm metrics, adapting its behavior based on a boolean flag in SimCtx.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/logging.h.

See also

LOG_PARTICLE_METRICS()

Definition at line 3337 of file logging.c.

{
    PetscErrorCode ierr;
    PetscMPIInt    rank;
    SimCtx         *simCtx = user->simCtx;
    const char     *stage_label = (stageName && stageName[0] != '\0') ? stageName : "N/A";
 
    PetscFunctionBeginUser;
    ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
 
    PetscInt totalParticles;
    ierr = DMSwarmGetSize(user->swarm, &totalParticles); CHKERRQ(ierr);
 
    if (!rank) {
        FILE *f;
        char filen[PETSC_MAX_PATH_LEN + 64];
        ierr = PetscSNPrintf(filen, sizeof(filen), "%s/Particle_Metrics.log", simCtx->log_dir); CHKERRQ(ierr);
        f = fopen(filen, "a");
        if (!f) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_FILE_OPEN, "Cannot open particle log file: %s", filen);
 
        if (ftell(f) == 0) {
            PetscFPrintf(PETSC_COMM_SELF, f, "%-18s | %-10s | %-12s | %-10s | %-10s | %-10s | %-15s | %-10s | %-10s\n",
                            "Stage", "Timestep", "Total Ptls", "Lost", "Lost Total", "Migrated", "Occupied Cells", "Imbalance", "Mig Passes");
            PetscFPrintf(PETSC_COMM_SELF, f, "-------------------------------------------------------------------------------------------------------------------------------------------\n");
        }
        if (simCtx->continueMode && simCtx->step == simCtx->StartStep + 1) {
            PetscFPrintf(PETSC_COMM_SELF, f, "# Continuation from step %" PetscInt_FMT "\n", simCtx->StartStep);
        }
 
        PetscFPrintf(PETSC_COMM_SELF, f, "%-18s | %-10d | %-12d | %-10d | %-10d | %-10d | %-15d | %-10.2f | %-10d\n",
                        stage_label, (int)simCtx->step, (int)totalParticles, (int)simCtx->particlesLostLastStep,
                        (int)simCtx->particlesLostCumulative, (int)simCtx->particlesMigratedLastStep, (int)simCtx->occupiedCellCount,
                        (double)simCtx->particleLoadImbalance, (int)simCtx->migrationPassesLastStep);
        fclose(f);
    }
    PetscFunctionReturn(0);
}

Here is the caller graph for this function: