Date: 2026-03-31T05:46:03+00:00

Actual source code: petsclogtypes.h

      1: #pragma once
      2: #include <petscsystypes.h>

      4: /* MANSEC = Sys */
      5: /* SUBMANSEC = Log */

      7: /*S
      8:   PetscEventPerfInfo - statistics on how many times the event is used, how much time it takes, etc.

     10:   Level: advanced

     12:   Note:
     13:   This is the data structure that describes profiling statsitics collected for an event from
     14:   the default log handler (`PetscLogDefaultBegin()`) using `PetscLogEventGetPerfInfo()`.

     16: .seealso: [](ch_profiling)
     17: S*/
     18: typedef struct {
     19:   int            id;                  /* The integer identifying this event / stage */
     20:   PetscBool      active;              /* Deprecated */
     21:   PetscBool      visible;             /* The flag to print info in summary */
     22:   int            depth;               /* The nesting depth of the event call */
     23:   int            count;               /* The number of times this event was executed */
     24:   PetscLogDouble flops;               /* The flops used in this event */
     25:   PetscLogDouble flops2;              /* The square of flops used in this event */
     26:   PetscLogDouble flopsTmp;            /* The accumulator for flops used in this event */
     27:   PetscLogDouble time;                /* The time taken for this event */
     28:   PetscLogDouble time2;               /* The square of time taken for this event */
     29:   PetscLogDouble timeTmp;             /* The accumulator for time taken for this event */
     30:   PetscLogDouble syncTime;            /* The synchronization barrier time */
     31:   PetscLogDouble dof[8];              /* The number of degrees of freedom associated with this event */
     32:   PetscLogDouble errors[8];           /* The errors (user-defined) associated with this event */
     33:   PetscLogDouble numMessages;         /* The number of messages in this event */
     34:   PetscLogDouble messageLength;       /* The total message lengths in this event */
     35:   PetscLogDouble numReductions;       /* The number of reductions in this event */
     36:   PetscLogDouble memIncrease;         /* How much the resident memory has increased in this event */
     37:   PetscLogDouble mallocIncrease;      /* How much the maximum malloced space has increased in this event */
     38:   PetscLogDouble mallocSpace;         /* How much the space was malloced and kept during this event */
     39:   PetscLogDouble mallocIncreaseEvent; /* Maximum of the high water mark with in event minus memory available at the end of the event */
     40: #if defined(PETSC_HAVE_DEVICE)
     41:   PetscLogDouble CpuToGpuCount; /* The total number of CPU to GPU copies */
     42:   PetscLogDouble GpuToCpuCount; /* The total number of GPU to CPU copies */
     43:   PetscLogDouble CpuToGpuSize;  /* The total size of CPU to GPU copies */
     44:   PetscLogDouble GpuToCpuSize;  /* The total size of GPU to CPU copies */
     45:   PetscLogDouble GpuFlops;      /* The flops done on a GPU in this event */
     46:   PetscLogDouble GpuTime;       /* The time spent on a GPU in this event */
     47:   PetscLogDouble GpuEnergy;     /* The energy consumed on a GPU in this event */
     48: #endif
     49: } PetscEventPerfInfo;

     51: typedef struct _n_PetscIntStack *PetscIntStack;

     53: /*MC
     54:     PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable)
     55:     code.

     57:     Level: intermediate

     59: .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage`
     60: M*/
     61: typedef int PetscLogEvent;

     63: /*MC
     64:     PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging

     66:     Level: intermediate

     68: .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent`
     69: M*/
     70: typedef int PetscLogStage;

     72: /*MC
     73:     PetscLogClass - id used to identify classes for logging purposes only.  It
     74:     is not equal to its `PetscClassId`, which is the identifier used for other
     75:     purposes.

     77:     Level: developer

     79: .seealso: [](ch_profiling), `PetscLogStateClassRegister()`
     80: M*/
     81: typedef int PetscLogClass;

     83: /*S
     84:   PetscLogHandler - Interface for performance logging.  A log handler receives a `PetscLogState` that has
     85:   information about the events (`PetscLogEvent`) and stages (`PetscLogStage`) in the logging environment.
     86:   When a handler is connected to PETSc's global logging stream (`PetscLogHandlerStart()`), it receives
     87:   updates about events (`PetscLogEventBegin()` / `PetscLogEventEnd()`), stages (`PetscLogStagePush()` /
     88:   `PetscLogStagePop()`), and objects (`PetscLogObjectCreate()` / `PetscLogObjectDestroy()`).  After
     89:   collecting information the logger can summarize its data with `PetscLogHandlerView()`.

     91:   Example Usage:
     92: .vb
     93: #include <petscsys.h>

     95: int main() {
     96:   UserCtx             ctx;
     97:   PetscLogHandlerType handler_type;

     99:   PetscInitialize(...);
    100:   // ... fill in ctx
    101:   PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler);
    102:   PetscLogHandlerSetType(handler, handler_type);
    103:   PetscLogHandlerStart(handler); // connect your handler to global logging state
    104:   // ... run code to be profiled
    105:   PetscLogHandlerStop(handler); // disconnect your handler from the global logging state
    106:   PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results
    107:   PetscLogHandlerDestroy(&handler);
    108:   PetscFinalize();
    109: }
    110: .ve

    112:   Level: developer

    114: .seealso: [](ch_profiling),
    115:           `PetscLogHandlerCreate()`,
    116:           `PetscLogHandlerStart()`, `PetscLogHandlerStop()`,
    117:           `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`,
    118:           `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`,
    119:           `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`,
    120:           `PetscLogHandlerEventSync()`,
    121:           `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`,
    122:           `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`,
    123:           `PetscLogHandlerView()`,
    124:           `PetscLogHandlerDestroy()`
    125: S*/
    126: typedef struct _p_PetscLogHandler *PetscLogHandler;

    128: /*J
    129:   PetscLogHandlerType - String with the name of a `PetscLogHandler` type

    131:   Level: Developer

    133:   Note:
    134:   Implementations included with PETSc include\:
    135: + `PETSCLOGHANDLERDEFAULT` (`PetscLogDefaultBegin()`)        - formats data for PETSc's default summary (`PetscLogView()`) and data-dump (`PetscLogDump()`) formats.
    136: . `PETSCLOGHANDLERNESTED` (`PetscLogNestedBegin()`)          - formats data for XML or flamegraph output
    137: . `PETSCLOGHANDLERTRACE` (`PetscLogTraceBegin()`)            - traces profiling events in an output stream
    138: . `PETSCLOGHANDLERMPE` (`PetscLogMPEBegin()`)                - outputs parallel performance visualization using MPE
    139: . `PETSCLOGHANDLERPERFSTUBS` (`PetscLogPerfstubsBegin()`)    - outputs instrumentation data for PerfStubs/TAU
    140: . `PETSCLOGHANDLERLEGACY` (`PetscLogLegacyCallbacksBegin()`) - adapts legacy callbacks to the `PetscLogHandler` interface
    141: - `PETSCLOGHANDLERNVTX`                                      - creates NVTX ranges for events that are visible in Nsight
    142: - `PETSCLOGHANDLERROCTX`                                     - creates ROCTx ranges for events that are visible in rocprof

    144: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`
    145: J*/
    146: typedef const char *PetscLogHandlerType;

    148: #define PETSCLOGHANDLERDEFAULT   "default"
    149: #define PETSCLOGHANDLERNESTED    "nested"
    150: #define PETSCLOGHANDLERTRACE     "trace"
    151: #define PETSCLOGHANDLERMPE       "mpe"
    152: #define PETSCLOGHANDLERPERFSTUBS "perfstubs"
    153: #define PETSCLOGHANDLERLEGACY    "legacy"
    154: #define PETSCLOGHANDLERNVTX      "nvtx"
    155: #define PETSCLOGHANDLERROCTX     "roctx"

    157: typedef struct _n_PetscLogRegistry *PetscLogRegistry;

    159: /*S
    160:    PetscLogState - Interface for the shared state information used by `PetscLogHandler`s.

    162:    Most users will not need to reference a `PetscLogState` directly: global logging routines
    163:    like `PetscLogEventRegister()`  and `PetscLogStagePush()` implicitly manipulate PETSc's global
    164:    logging state, `PetscLogGetState()`.

    166:    Level: developer

    168:    Notes:
    169:    `PetscLogState` holds a registry of events (`PetscLogStateEventRegister()`), stages
    170:    (`PetscLogStateStageRegister()`), and classes (`PetscLogStateClassRegister()`).
    171:    It keeps track of when the user has activated events (`PetscLogStateEventSetActive()`) and
    172:    stages (`PetscLogStateStageSetActive()`).  It also keeps a stack of running stages
    173:    (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`).

    175:    The struct defining `PetscLogState` is in a public header so that `PetscLogEventBegin()`,
    176:    `PetscLogEventEnd()`, `PetscLogObjectCreate()`, and `PetscLogObjectDestroy()` can be defined
    177:    as macros rather than function calls, but users are discouraged from directly accessing
    178:    the struct's fields, which are subject to change.

    180: .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()`
    181: S*/
    182: typedef struct _n_PetscLogState *PetscLogState;
    183: struct _n_PetscLogState {
    184:   PetscLogRegistry registry;
    185:   PetscBT          active;
    186:   PetscIntStack    stage_stack;
    187:   int              current_stage;
    188:   int              bt_num_stages;
    189:   int              bt_num_events;
    190:   int              refct;
    191: };

    193: /*S
    194:   PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`.

    196:   Level: developer

    198: .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()`
    199: S*/
    200: typedef struct {
    201:   char        *name;       /* The name of this event */
    202:   PetscClassId classid;    /* The class the event is associated with */
    203:   PetscBool    collective; /* Flag this event as collective */
    204: } PetscLogEventInfo;

    206: /*S
    207:   PetscLogClassInfo - A registry entry about a class for `PetscLogState`.

    209:   Level: developer

    211: .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()`
    212: S*/
    213: typedef struct {
    214:   char        *name;    /* The class name */
    215:   PetscClassId classid; /* The integer identifying this class */
    216: } PetscLogClassInfo;

    218: /*S
    219:   PetscLogStageInfo - A registry entry about a class for `PetscLogState`.

    221:   Level: developer

    223: .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()`
    224: S*/
    225: typedef struct {
    226:   char *name; /* The stage name */
    227: } PetscLogStageInfo;