1 #pragma once 2 #include <petscsystypes.h> 3 4 /* SUBMANSEC = Profiling */ 5 6 /*S 7 PetscEventPerfInfo - statistics on how many times the event is used, how much time it takes, etc. 8 9 Level: advanced 10 11 Note: 12 This is the data structure that describes profiling statsitics collected for an event from 13 the default log handler (`PetscLogDefaultBegin()`) using `PetscLogEventGetPerfInfo()`. 14 15 .seealso(): [](ch_profiling) 16 S*/ 17 typedef struct { 18 int id; /* The integer identifying this event / stage */ 19 PetscBool active; /* Deprecated */ 20 PetscBool visible; /* The flag to print info in summary */ 21 int depth; /* The nesting depth of the event call */ 22 int count; /* The number of times this event was executed */ 23 PetscLogDouble flops; /* The flops used in this event */ 24 PetscLogDouble flops2; /* The square of flops used in this event */ 25 PetscLogDouble flopsTmp; /* The accumulator for flops used in this event */ 26 PetscLogDouble time; /* The time taken for this event */ 27 PetscLogDouble time2; /* The square of time taken for this event */ 28 PetscLogDouble timeTmp; /* The accumulator for time taken for this event */ 29 PetscLogDouble syncTime; /* The synchronization barrier time */ 30 PetscLogDouble dof[8]; /* The number of degrees of freedom associated with this event */ 31 PetscLogDouble errors[8]; /* The errors (user-defined) associated with this event */ 32 PetscLogDouble numMessages; /* The number of messages in this event */ 33 PetscLogDouble messageLength; /* The total message lengths in this event */ 34 PetscLogDouble numReductions; /* The number of reductions in this event */ 35 PetscLogDouble memIncrease; /* How much the resident memory has increased in this event */ 36 PetscLogDouble mallocIncrease; /* How much the maximum malloced space has increased in this event */ 37 PetscLogDouble mallocSpace; /* How much the space was malloced and kept during this event */ 38 PetscLogDouble mallocIncreaseEvent; /* Maximum of the high water mark with in event minus memory available at the end of the event */ 39 #if defined(PETSC_HAVE_DEVICE) 40 PetscLogDouble CpuToGpuCount; /* The total number of CPU to GPU copies */ 41 PetscLogDouble GpuToCpuCount; /* The total number of GPU to CPU copies */ 42 PetscLogDouble CpuToGpuSize; /* The total size of CPU to GPU copies */ 43 PetscLogDouble GpuToCpuSize; /* The total size of GPU to CPU copies */ 44 PetscLogDouble GpuFlops; /* The flops done on a GPU in this event */ 45 PetscLogDouble GpuTime; /* The time spent on a GPU in this event */ 46 #endif 47 } PetscEventPerfInfo; 48 49 typedef struct _n_PetscIntStack *PetscIntStack; 50 51 /*MC 52 PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable) 53 code. 54 55 Level: intermediate 56 57 .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage` 58 M*/ 59 typedef int PetscLogEvent; 60 61 /*MC 62 PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging 63 64 Level: intermediate 65 66 .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent` 67 M*/ 68 typedef int PetscLogStage; 69 70 /*MC 71 PetscLogClass - id used to identify classes for logging purposes only. It 72 is not equal to its `PetscClassId`, which is the identifier used for other 73 purposes. 74 75 Level: developer 76 77 .seealso: [](ch_profiling), `PetscLogStateClassRegister()` 78 M*/ 79 typedef int PetscLogClass; 80 81 /*S 82 PetscLogHandler - Interface for performance logging. A log handler receives a `PetscLogState` that has 83 information about the events (`PetscLogEvent`) and stages (`PetscLogStage`) in the logging environment. 84 When a handler is connected to PETSc's global logging stream (`PetscLogHandlerStart()`), it receives 85 updates about events (`PetscLogEventBegin()` / `PetscLogEventEnd()`), stages (`PetscLogStagePush()` / 86 `PetscLogStagePop()`), and objects (`PetscLogObjectCreate()` / `PetscLogObjectDestroy()`). After 87 collecting information the logger can summarize its data with `PetscLogHandlerView()`. 88 89 Example Usage: 90 .vb 91 #include <petscsys.h> 92 93 int main() { 94 UserCtx ctx; 95 PetscLogHandlerType handler_type; 96 97 PetscInitialize(...); 98 // ... fill in ctx 99 PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler); 100 PetscLogHandlerSetType(handler, handler_type); 101 PetscLogHandlerStart(handler); // connect your handler to global logging state 102 // ... run code to be profiled 103 PetscLogHandlerStop(handler); // disconnect your handler from the global logging state 104 PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results 105 PetscLogHandlerDestroy(&handler); 106 PetscFinalize(); 107 } 108 .ve 109 110 Level: developer 111 112 .seealso: [](ch_profiling), 113 `PetscLogHandlerCreate()`, 114 `PetscLogHandlerStart()`, `PetscLogHandlerStop()`, 115 `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`, 116 `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`, 117 `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`, 118 `PetscLogHandlerEventSync()`, 119 `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`, 120 `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`, 121 `PetscLogHandlerView()`, 122 `PetscLogHandlerDestroy()`, 123 S*/ 124 typedef struct _p_PetscLogHandler *PetscLogHandler; 125 126 /*J 127 PetscLogHandlerType - String with the name of a `PetscLogHandler` type 128 129 Level: Developer 130 131 Note: 132 Implementations included with PETSc include\: 133 + `PETSCLOGHANDLERDEFAULT` (`PetscLogDefaultBegin()`) - formats data for PETSc's default summary (`PetscLogView()`) and data-dump (`PetscLogDump()`) formats. 134 . `PETSCLOGHANDLERNESTED` (`PetscLogNestedBegin()`) - formats data for XML or flamegraph output 135 . `PETSCLOGHANDLERTRACE` (`PetscLogTraceBegin()`) - traces profiling events in an output stream 136 . `PETSCLOGHANDLERMPE` (`PetscLogMPEBegin()`) - outputs parallel performance visualization using MPE 137 . `PETSCLOGHANDLERPERFSTUBS` (`PetscLogPerfstubsBegin()`) - outputs instrumentation data for PerfStubs/TAU 138 . `PETSCLOGHANDLERLEGACY` (`PetscLogLegacyCallbacksBegin()`) - adapts legacy callbacks to the `PetscLogHandler` interface 139 - `PETSCLOGHANDLERNVTX` - creates NVTX ranges for events that are visible in Nsight 140 141 .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()` 142 J*/ 143 typedef const char *PetscLogHandlerType; 144 145 #define PETSCLOGHANDLERDEFAULT "default" 146 #define PETSCLOGHANDLERNESTED "nested" 147 #define PETSCLOGHANDLERTRACE "trace" 148 #define PETSCLOGHANDLERMPE "mpe" 149 #define PETSCLOGHANDLERPERFSTUBS "perfstubs" 150 #define PETSCLOGHANDLERLEGACY "legacy" 151 #define PETSCLOGHANDLERNVTX "nvtx" 152 153 typedef struct _n_PetscLogRegistry *PetscLogRegistry; 154 155 /*S 156 PetscLogState - Interface for the shared state information used by `PetscLogHandler`s. 157 158 Most users will not need to reference a `PetscLogState` directly: global logging routines 159 like `PetscLogEventRegister()` and `PetscLogStagePush()` implicitly manipulate PETSc's global 160 logging state, `PetscLogGetState()`. 161 162 Level: developer 163 164 Notes: 165 `PetscLogState` holds a registry of events (`PetscLogStateEventRegister()`), stages 166 (`PetscLogStateStageRegister()`), and classes (`PetscLogStateClassRegister()`). 167 It keeps track of when the user has activated events (`PetscLogStateEventSetActive()`) and 168 stages (`PetscLogStateStageSetActive()`). It also keeps a stack of running stages 169 (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`). 170 171 The struct defining `PetscLogState` is in a public header so that `PetscLogEventBegin()`, 172 `PetscLogEventEnd()`, `PetscLogObjectCreate()`, and `PetscLogObjectDestroy()` can be defined 173 as macros rather than function calls, but users are discouraged from directly accessing 174 the struct's fields, which are subject to change. 175 176 .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()` 177 S*/ 178 typedef struct _n_PetscLogState *PetscLogState; 179 struct _n_PetscLogState { 180 PetscLogRegistry registry; 181 PetscBT active; 182 PetscIntStack stage_stack; 183 int current_stage; 184 int bt_num_stages; 185 int bt_num_events; 186 int refct; 187 }; 188 189 /*S 190 PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`. 191 192 Level: developer 193 194 .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()` 195 S*/ 196 typedef struct { 197 char *name; /* The name of this event */ 198 PetscClassId classid; /* The class the event is associated with */ 199 PetscBool collective; /* Flag this event as collective */ 200 } PetscLogEventInfo; 201 202 /*S 203 PetscLogClassInfo - A registry entry about a class for `PetscLogState`. 204 205 Level: developer 206 207 .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()` 208 S*/ 209 typedef struct { 210 char *name; /* The class name */ 211 PetscClassId classid; /* The integer identifying this class */ 212 } PetscLogClassInfo; 213 214 /*S 215 PetscLogStageInfo - A registry entry about a class for `PetscLogState`. 216 217 Level: developer 218 219 .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()` 220 S*/ 221 typedef struct _PetscLogStageInfo { 222 char *name; /* The stage name */ 223 } PetscLogStageInfo; 224