SST  13.0.0
StructuralSimulationToolkit
statoutput.h
1 // Copyright 2009-2023 NTESS. Under the terms
2 // of Contract DE-NA0003525 with NTESS, the U.S.
3 // Government retains certain rights in this software.
4 //
5 // Copyright (c) 2009-2023, NTESS
6 // All rights reserved.
7 //
8 // This file is part of the SST software package. For license
9 // information, see the LICENSE file in the top level directory of the
10 // distribution.
11 
12 #ifndef SST_CORE_STATAPI_STATOUTPUT_H
13 #define SST_CORE_STATAPI_STATOUTPUT_H
14 
15 #include "sst/core/eli/elementinfo.h"
16 #include "sst/core/module.h"
17 #include "sst/core/params.h"
18 #include "sst/core/sst_types.h"
19 #include "sst/core/statapi/statbase.h"
20 #include "sst/core/statapi/statfieldinfo.h"
21 #include "sst/core/warnmacros.h"
22 
23 #include <mutex>
24 #include <unordered_map>
25 
26 // Default Settings for Statistic Output and Load Level
27 #define STATISTICSDEFAULTOUTPUTNAME "sst.statOutputConsole"
28 #define STATISTICSDEFAULTLOADLEVEL 0
29 #define STATISTICLOADLEVELUNINITIALIZED 0xff
30 
31 namespace SST {
32 class BaseComponent;
33 class Simulation;
34 namespace Statistics {
35 class StatisticProcessingEngine;
36 class StatisticGroup;
37 
38 ////////////////////////////////////////////////////////////////////////////////
39 
40 /**
41  \class StatisticOutput
42 
43  Forms the base class for statistics output generation within the SST core.
44  Statistics are gathered by the statistic objects and then processed sent to
45  the derived output object either periodically or by event and/or also at
46  the end of the simulation. A single statistic output will be created by the
47  simulation (per node) and will collect the data per its design.
48 */
50 {
51 public:
52  SST_ELI_DECLARE_BASE(StatisticOutput)
53  SST_ELI_DECLARE_INFO_EXTERN(ELI::ProvidesParams)
54  SST_ELI_DECLARE_CTOR_EXTERN(SST::Params&)
55 
56  using fieldType_t = StatisticFieldInfo::fieldType_t;
57  using fieldHandle_t = StatisticFieldInfo::fieldHandle_t;
58  using FieldInfoArray_t = std::vector<StatisticFieldInfo*>;
59  using FieldNameMap_t = std::unordered_map<std::string, fieldHandle_t>;
60 
61 public:
62  ~StatisticOutput();
63 
64  /** Return the Statistic Output name */
65  std::string& getStatisticOutputName() { return m_statOutputName; }
66 
67  /** Return the parameters for the StatisticOutput */
68  Params& getOutputParameters() { return m_outputParameters; }
69 
70  /** True if this StatOutput can handle StatisticGroups */
71  virtual bool acceptsGroups() const { return false; }
72 
73  virtual void output(StatisticBase* statistic, bool endOfSimFlag) = 0;
74 
75  virtual bool supportsDynamicRegistration() const { return false; }
76 
77  /////////////////
78  // Methods for Registering Fields (Called by Statistic Objects)
79 public:
80  // by default, no params to return
81  static const std::vector<SST::ElementInfoParam>& ELI_getParams()
82  {
83  static std::vector<SST::ElementInfoParam> var {};
84  return var;
85  }
86 
87 protected:
88  friend class SST::Simulation;
90 
91  // Routine to have Output Check its options for validity
92  /** Have the Statistic Output check its parameters
93  * @return True if all parameters are ok; False if a parameter is missing or incorrect.
94  */
95  virtual bool checkOutputParameters() = 0;
96 
97  /** Have Statistic Object print out its usage and parameter info.
98  * Called when checkOutputParameters() returns false */
99  virtual void printUsage() = 0;
100 
101  // Simulation Events
102  /** Indicate to Statistic Output that simulation has started.
103  * Allows object to perform any setup required. */
104  virtual void startOfSimulation() = 0;
105 
106  /** Indicate to Statistic Output that simulation has ended.
107  * Allows object to perform any shutdown required. */
108  virtual void endOfSimulation() = 0;
109 
110 private:
111  // Start / Stop of register Fields
112  virtual void registerStatistic(StatisticBase* stat) = 0;
113 
114  void registerGroup(StatisticGroup* group);
115  void outputGroup(StatisticGroup* group, bool endOfSimFlag);
116 
117  virtual void startOutputGroup(StatisticGroup* group) = 0;
118  virtual void stopOutputGroup() = 0;
119 
120  virtual void startRegisterGroup(StatisticGroup* group) = 0;
121  virtual void stopRegisterGroup() = 0;
122 
123  void castError();
124 
125 protected:
126  /** Construct a base StatisticOutput
127  * @param outputParameters - The parameters for the statistic Output.
128  */
129  StatisticOutput(Params& outputParameters);
130  StatisticOutput() { ; } // For serialization only
131  void setStatisticOutputName(const std::string& name) { m_statOutputName = name; }
132 
133  void lock() { m_lock.lock(); }
134  void unlock() { m_lock.unlock(); }
135 
136 private:
137  std::string m_statOutputName;
138  Params m_outputParameters;
139  std::recursive_mutex m_lock;
140 };
141 
143 {
144 public:
145  void registerStatistic(StatisticBase* stat) override;
146 
147  // Start / Stop of output
148  void output(StatisticBase* statistic, bool endOfSimFlag) override;
149 
150  void startOutputGroup(StatisticGroup* group) override;
151  void stopOutputGroup() override;
152 
153  void startRegisterGroup(StatisticGroup* group) override;
154  void stopRegisterGroup() override;
155 
156  // Start / Stop of output
157  /** Indicate to Statistic Output that a statistic is about to send data to be output
158  * Allows object to perform any initialization before output. */
159  virtual void implStartOutputEntries(StatisticBase* statistic) = 0;
160 
161  /** Indicate to Statistic Output that a statistic is finished sending data to be output
162  * Allows object to perform any cleanup. */
163  virtual void implStopOutputEntries() = 0;
164 
165  // /** Adjust the hierarchy of the fields (FUTURE SUPPORT)
166  // * @param fieldHandle - The handle of the field to adjust.
167  // * @param Level - The level of the field.
168  // * @param parent - The parent field of the field.
169  // */
170  // void setFieldHierarchy(fieldHandle_t fieldHandle, uint32_t Level, fieldHandle_t parent);
171 
172  /** Return the information on a registered field via the field handle.
173  * @param fieldHandle - The handle of the registered field.
174  * @return Pointer to the registered field info.
175  */
176  // Get the Field Information object, NULL is returned if not found
177  StatisticFieldInfo* getRegisteredField(fieldHandle_t fieldHandle);
178 
179  /** Return the information on a registered field via known names.
180  * @param componentName - The name of the component.
181  * @param statisticName - The name of the statistic.
182  * @param fieldName - The name of the field .
183  * @return Pointer to the registered field info.
184  */
185  // Get Registered Fields
186  // ONLY SUPPORTED TYPES ARE int32_t, uint32_t, int64_t, uint64_t, float, double
187  template <typename T>
188  StatisticFieldInfo* getRegisteredField(const char* statisticName, const char* fieldName)
189  {
190  StatisticFieldInfo* NewStatFieldInfo;
191  StatisticFieldInfo* ExistingStatFieldInfo;
192  StatisticFieldInfo::fieldType_t FieldType =
193  StatisticFieldInfo::StatisticFieldInfo::getFieldTypeFromTemplate<T>();
194 
195  NewStatFieldInfo = new StatisticFieldInfo(statisticName, fieldName, FieldType);
196 
197  // Now search the FieldNameMap_t of type for a matching entry
198  FieldNameMap_t::const_iterator found = m_outputFieldNameMap.find(NewStatFieldInfo->getFieldUniqueName());
199  if ( found != m_outputFieldNameMap.end() ) {
200  // We found a map entry, now get the StatFieldInfo from the m_outputFieldInfoArray at the index given by the
201  // map and then delete the NewStatFieldInfo to prevent a leak
202  ExistingStatFieldInfo = m_outputFieldInfoArray[found->second];
203  delete NewStatFieldInfo;
204  return ExistingStatFieldInfo;
205  }
206 
207  delete NewStatFieldInfo;
208  return nullptr;
209  }
210 
211  /** Return the array of registered field infos. */
212  FieldInfoArray_t& getFieldInfoArray() { return m_outputFieldInfoArray; }
213 
214  /////////////////
215  // Methods for Outputting Fields (Called by Statistic Objects)
216  // Output fields (will call virtual functions of Derived Output classes)
217  // These aren't really part of a generic interface - optimization purposes only
218  /** Output field data.
219  * @param fieldHandle - The handle of the registered field.
220  * @param data - The data to be output.
221  */
222  virtual void outputField(fieldHandle_t fieldHandle, int32_t data);
223  virtual void outputField(fieldHandle_t fieldHandle, uint32_t data);
224  virtual void outputField(fieldHandle_t fieldHandle, int64_t data);
225  virtual void outputField(fieldHandle_t fieldHandle, uint64_t data);
226  virtual void outputField(fieldHandle_t fieldHandle, float data);
227  virtual void outputField(fieldHandle_t fieldHandle, double data);
228 
229  /** Register a field to be output (templated function)
230  * @param fieldName - The name of the field.
231  * @return The handle of the registered field or -1 if type is not supported.
232  * Note: Any field names (of the same data type) that are previously
233  * registered by a statistic will return the previously
234  * handle.
235  */
236  // Field Registration
237  // ONLY SUPPORTED TYPES ARE int32_t, uint32_t, int64_t, uint64_t, float, double
238  template <typename T>
239  fieldHandle_t registerField(const char* fieldName)
240  {
241  StatisticFieldInfo::fieldType_t FieldType =
242  StatisticFieldInfo::StatisticFieldInfo::getFieldTypeFromTemplate<T>();
243 
244  auto res = generateFieldHandle(addFieldToLists(fieldName, FieldType));
245  implRegisteredField(res);
246  return res;
247  }
248 
249  /** Output field data.
250  * @param type - The field type to get name of.
251  * @return String name of the field type.
252  */
253  const char* getFieldTypeShortName(fieldType_t type);
254 
255 protected:
256  /** Construct a base StatisticOutput
257  * @param outputParameters - The parameters for the statistic Output.
258  */
259  StatisticFieldsOutput(Params& outputParameters);
260 
261  // For Serialization
263 
264 private:
265  // Other support functions
266  StatisticFieldInfo* addFieldToLists(const char* fieldName, fieldType_t fieldType);
267  fieldHandle_t generateFieldHandle(StatisticFieldInfo* FieldInfo);
268  virtual void implRegisteredField(fieldHandle_t UNUSED(fieldHandle)) {}
269 
270  FieldInfoArray_t m_outputFieldInfoArray;
271  FieldNameMap_t m_outputFieldNameMap;
272  fieldHandle_t m_highestFieldHandle;
273  std::string m_currentFieldStatName;
274 
275 protected:
276  /** These can be overriden, if necessary, but must be callable
277  * by the derived class */
278  virtual void startRegisterFields(StatisticBase* statistic);
279  virtual void stopRegisterFields();
280 
281  virtual void startOutputEntries(StatisticBase* statistic);
282  virtual void stopOutputEntries();
283 };
284 
285 } // namespace Statistics
286 } // namespace SST
287 
288 #endif // SST_CORE_STATAPI_STATOUTPUT_H
Main control class for a SST Simulation.
Definition: simulation.h:38
std::string & getStatisticOutputName()
Return the Statistic Output name.
Definition: statoutput.h:65
The class for representing Statistic Output Fields.
Definition: statfieldinfo.h:93
Forms the base class for statistics output generation within the SST core.
Definition: statoutput.h:49
virtual void implStopOutputEntries()=0
Indicate to Statistic Output that a statistic is finished sending data to be output Allows object to ...
Forms the base class for statistics gathering within SST.
Definition: statbase.h:63
Definition: action.cc:18
virtual void implStartOutputEntries(StatisticBase *statistic)=0
Indicate to Statistic Output that a statistic is about to send data to be output Allows object to per...
FieldInfoArray_t & getFieldInfoArray()
Return the array of registered field infos.
Definition: statoutput.h:212
virtual bool checkOutputParameters()=0
Have the Statistic Output check its parameters.
const char * getFieldTypeShortName(fieldType_t type)
Output field data.
Definition: statoutput.cc:203
fieldHandle_t registerField(const char *fieldName)
Register a field to be output (templated function)
Definition: statoutput.h:239
Definition: paramsInfo.h:40
virtual void startOfSimulation()=0
Indicate to Statistic Output that simulation has started.
virtual void outputField(fieldHandle_t fieldHandle, int32_t data)
Output field data.
virtual void printUsage()=0
Have Statistic Object print out its usage and parameter info.
Definition: statoutput.h:142
StatisticOutput(Params &outputParameters)
Construct a base StatisticOutput.
Definition: statoutput.cc:26
Params & getOutputParameters()
Return the parameters for the StatisticOutput.
Definition: statoutput.h:68
Parameter store.
Definition: params.h:55
An SST core component that handles timing and event processing informing all registered Statistics to...
Definition: statengine.h:51
StatisticFieldInfo * getRegisteredField(fieldHandle_t fieldHandle)
Adjust the hierarchy of the fields (FUTURE SUPPORT)
Definition: statoutput.cc:104
Definition: statgroup.h:28
virtual void startRegisterFields(StatisticBase *statistic)
These can be overriden, if necessary, but must be callable by the derived class.
Definition: statoutput.cc:218
StatisticFieldInfo * getRegisteredField(const char *statisticName, const char *fieldName)
Return the information on a registered field via known names.
Definition: statoutput.h:188
virtual bool acceptsGroups() const
True if this StatOutput can handle StatisticGroups.
Definition: statoutput.h:71
virtual void endOfSimulation()=0
Indicate to Statistic Output that simulation has ended.