Common module (common.h)

Functions

PetscErrorCode printHeader()

Prints the formatted PETGEM header banner.

Prints the formatted PETGEM header banner.

This function prints a formatted header to standard output containing basic information about the PETGEM project, including:

  • Project name and expanded acronym

  • GitHub repository URL

  • Developer name

  • Institutional affiliations

The header is printed using PETSc-based printing utilities and formatting helpers (separators, centered text), ensuring consistent and collective output across all MPI processes associated with PETSC_COMM_WORLD.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on successful completion, or a PETSc error code otherwise.

PetscErrorCode printFooter()

Prints the PETGEM closing banner with run timestamp and author.

Prints the PETGEM closing banner with run timestamp and author.

Called once at the end of every kernel run (fm.csem, im.csem, petgem) to mark the end of stdout output. Output goes to PETSC_COMM_WORLD via the centered-text helpers, so it is collectively printed by rank 0 only.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on successful completion, or a PETSc error code if any of the underlying print helpers fail.

PetscErrorCode createDirectory(const char *path)

Ensures that a directory exists, creating it if necessary.

This function checks whether the specified path exists. If the path already exists and refers to a directory, the function returns successfully. If the path exists but is not a directory, an error is raised.

If the path does not exist, the function attempts to create the directory with POSIX permissions 0755. Any errors encountered during directory creation are reported using PETSc error handling mechanisms.

Parameters:

  • path – [in] Directory path to create (no-op if it already exists).

  • path – [in] Path to the directory to be checked or created.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code if the path exists but is not a directory, or if directory creation fails.

PetscErrorCode printTimers(const PetscLogDouble timers[])

Prints execution-time statistics for the main PETGEM stages.

Reports per-stage absolute time (hh:mm:ss.sss) and percentage of the total runtime, collectively across PETSC_COMM_WORLD.

Prints execution-time statistics for the main PETGEM stages.

This function receives an array of timers containing the elapsed execution times (in seconds) for the different phases of the PETGEM execution. It computes the total elapsed time as the sum of all stages and prints a formatted timing report to standard output, including the absolute time (hh:mm:ss.sss) and the percentage of the total runtime for each stage.

The reported stages are:

  • Reading user parameters

  • Load input data

  • Grid setup

  • Assembly

  • Solver

  • Postprocessing

Output is produced using PETSc parallel printing routines, ensuring consistent and collective reporting across all MPI processes associated with PETSC_COMM_WORLD.

Parameters:

  • timers – [in] Array of length 6 of per-stage elapsed times (s): [0] read params, [1] load input, [2] grid setup, [3] assembly, [4] solver, [5] postprocessing.

  • timers – [in] Array of length 6 containing execution times (in seconds) for each stage, in the following order: timers[0] = Read user parameters timers[1] = Load input data timers[2] = Grid setup timers[3] = Assembly timers[4] = Solver timers[5] = Postprocessing

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on successful completion, or a PETSc error code otherwise.

PetscErrorCode parseModeArg(const char *s, PetscInt *mode)

Parses the dispatcher mode argument into a numeric code.

Accepts the synonyms “modeling”/”forward”/”fm” (mode 0) and “inverse”/”im” (mode 1); anything else yields mode -1 (unknown).

Parses the dispatcher mode argument into a numeric code.

Accepts the user-friendly synonyms for each kernel:

  • ”modeling”, “forward”, “fm” : *mode = 0 (forward)

  • ”inverse”, “im” : *mode = 1 (inverse)

  • anything else : *mode = -1 (unknown; caller can then call printUsage())

Parameters:

  • s – [in] Mode string from argv (must be non-NULL).

  • mode – [out] Receives the numeric mode code (0, 1, or -1).

  • s – [in] Mode string from argv. Must be non-NULL.

  • mode – [out] Receives the numeric mode code (see above).

Returns:

PetscErrorCode PETSC_SUCCESS, or PETSC_ERR_ARG_NULL when s is NULL.

Returns:

PetscErrorCode PETSC_SUCCESS, or PETSC_ERR_ARG_NULL when s is NULL.

PetscErrorCode printUsage(const char *progname)

Prints a one-screen CLI usage summary for the petgem dispatcher.

Prints a one-screen CLI usage summary for the petgem dispatcher.

Lists the positional-subcommand form (petgem modeling | inverse), the equivalent -mode <m> PETSc-option form, and --version. Called when the dispatcher in src/petgem.c receives no recognized subcommand, or when --help is requested.

Parameters:

  • progname – [in] Executable basename (typically argv[0]).

  • progname – [in] Executable basename (typically argv[0]) used as the leading word of each example line.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success.