1 #pragma once 2 #include <petscsystypes.h> 3 4 /* MANSEC = Sys */ 5 /* SUBMANSEC = Log */ 6 7 /*S 8 PetscEventPerfInfo - statistics on how many times the event is used, how much time it takes, etc. 9 10 Level: advanced 11 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()`. 15 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; 50 51 typedef struct _n_PetscIntStack *PetscIntStack; 52 53 /*MC 54 PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable) 55 code. 56 57 Level: intermediate 58 59 .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage` 60 M*/ 61 typedef int PetscLogEvent; 62 63 /*MC 64 PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging 65 66 Level: intermediate 67 68 .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent` 69 M*/ 70 typedef int PetscLogStage; 71 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. 76 77 Level: developer 78 79 .seealso: [](ch_profiling), `PetscLogStateClassRegister()` 80 M*/ 81 typedef int PetscLogClass; 82 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()`. 90 91 Example Usage: 92 .vb 93 #include <petscsys.h> 94 95 int main() { 96 UserCtx ctx; 97 PetscLogHandlerType handler_type; 98 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 111 112 Level: developer 113 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; 127 128 /*J 129 PetscLogHandlerType - String with the name of a `PetscLogHandler` type 130 131 Level: Developer 132 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 143 144 .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()` 145 J*/ 146 typedef const char *PetscLogHandlerType; 147 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" 156 157 typedef struct _n_PetscLogRegistry *PetscLogRegistry; 158 159 /*S 160 PetscLogState - Interface for the shared state information used by `PetscLogHandler`s. 161 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()`. 165 166 Level: developer 167 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()`). 174 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. 179 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 }; 192 193 /*S 194 PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`. 195 196 Level: developer 197 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; 205 206 /*S 207 PetscLogClassInfo - A registry entry about a class for `PetscLogState`. 208 209 Level: developer 210 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; 217 218 /*S 219 PetscLogStageInfo - A registry entry about a class for `PetscLogState`. 220 221 Level: developer 222 223 .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()` 224 S*/ 225 typedef struct { 226 char *name; /* The stage name */ 227 } PetscLogStageInfo; 228