Date: 2026-07-30T21:13:58+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: /*S
     52:   PetscIntStack - Opaque PETSc stack-of-`int` data structure used internally for performance logging (for example, to track nested log stage and event pushes)

     54:   Level: developer

     56: .seealso: `PetscIntStackCreate()`, `PetscIntStackDestroy()`, `PetscIntStackPush()`, `PetscIntStackPop()`, `PetscIntStackTop()`, `PetscIntStackEmpty()`
     57: S*/
     58: typedef struct _n_PetscIntStack *PetscIntStack;

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

     64:     Level: intermediate

     66: .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage`
     67: M*/
     68: typedef int PetscLogEvent;

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

     73:     Level: intermediate

     75: .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent`
     76: M*/
     77: typedef int PetscLogStage;

     79: /*MC
     80:     PetscLogClass - id used to identify classes for logging purposes only.  It
     81:     is not equal to its `PetscClassId`, which is the identifier used for other
     82:     purposes.

     84:     Level: developer

     86: .seealso: [](ch_profiling), `PetscLogStateClassRegister()`
     87: M*/
     88: typedef int PetscLogClass;

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

     98:   Example Usage:
     99: .vb
    100: #include <petscsys.h>

    102: int main() {
    103:   UserCtx             ctx;
    104:   PetscLogHandlerType handler_type;

    106:   PetscInitialize(...);
    107:   // ... fill in ctx
    108:   PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler);
    109:   PetscLogHandlerSetType(handler, handler_type);
    110:   PetscLogHandlerStart(handler); // connect your handler to global logging state
    111:   // ... run code to be profiled
    112:   PetscLogHandlerStop(handler); // disconnect your handler from the global logging state
    113:   PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results
    114:   PetscLogHandlerDestroy(&handler);
    115:   PetscFinalize();
    116: }
    117: .ve

    119:   Level: developer

    121: .seealso: [](ch_profiling),
    122:           `PetscLogHandlerCreate()`,
    123:           `PetscLogHandlerStart()`, `PetscLogHandlerStop()`,
    124:           `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`,
    125:           `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`,
    126:           `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`,
    127:           `PetscLogHandlerEventSync()`,
    128:           `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`,
    129:           `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`,
    130:           `PetscLogHandlerView()`,
    131:           `PetscLogHandlerDestroy()`
    132: S*/
    133: typedef struct _p_PetscLogHandler *PetscLogHandler;

    135: /*J
    136:   PetscLogHandlerType - String with the name of a `PetscLogHandler` type

    138:   Level: Developer

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

    151: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`
    152: J*/
    153: typedef const char *PetscLogHandlerType;

    155: #define PETSCLOGHANDLERDEFAULT   "default"
    156: #define PETSCLOGHANDLERNESTED    "nested"
    157: #define PETSCLOGHANDLERTRACE     "trace"
    158: #define PETSCLOGHANDLERMPE       "mpe"
    159: #define PETSCLOGHANDLERPERFSTUBS "perfstubs"
    160: #define PETSCLOGHANDLERLEGACY    "legacy"
    161: #define PETSCLOGHANDLERNVTX      "nvtx"
    162: #define PETSCLOGHANDLERROCTX     "roctx"

    164: /*S
    165:   PetscLogRegistry - Opaque PETSc registry of logging events, stages and classes that is shared by all `PetscLogHandler`s attached to a given `PetscLogState`

    167:   Level: developer

    169: .seealso: `PetscLogState`, `PetscLogStateGetRegistry()`, `PetscLogHandler`, `PetscLogEventRegister()`, `PetscLogStageRegister()`
    170: S*/
    171: typedef struct _n_PetscLogRegistry *PetscLogRegistry;

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

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

    180:    Level: developer

    182:    Notes:
    183:    `PetscLogState` holds a registry of events (`PetscLogStateEventRegister()`), stages
    184:    (`PetscLogStateStageRegister()`), and classes (`PetscLogStateClassRegister()`).
    185:    It keeps track of when the user has activated events (`PetscLogStateEventSetActive()`) and
    186:    stages (`PetscLogStateStageSetActive()`).  It also keeps a stack of running stages
    187:    (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`).

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

    194: .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()`
    195: S*/
    196: typedef struct _n_PetscLogState *PetscLogState;
    197: struct _n_PetscLogState {
    198:   PetscLogRegistry registry;
    199:   PetscBT          active;
    200:   PetscIntStack    stage_stack;
    201:   int              current_stage;
    202:   int              bt_num_stages;
    203:   int              bt_num_events;
    204:   int              refct;
    205: };

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

    210:   Level: developer

    212: .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()`
    213: S*/
    214: typedef struct {
    215:   char        *name;       /* The name of this event */
    216:   PetscClassId classid;    /* The class the event is associated with */
    217:   PetscBool    collective; /* Flag this event as collective */
    218: } PetscLogEventInfo;

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

    223:   Level: developer

    225: .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()`
    226: S*/
    227: typedef struct {
    228:   char        *name;    /* The class name */
    229:   PetscClassId classid; /* The integer identifying this class */
    230: } PetscLogClassInfo;

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

    235:   Level: developer

    237: .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()`
    238: S*/
    239: typedef struct {
    240:   char *name; /* The stage name */
    241: } PetscLogStageInfo;