A class used to store time, memory and additional values statistics related to the simulation loading and execution. More...

#include <gmRunProgressStats.h>

Inheritance diagram for GmRunProgressStats:

[legend]

Collaboration diagram for GmRunProgressStats:

[legend]

Public Types
enum	Level { GM_RUNPROG_DISABLED , GM_RUNPROG_NS_SP , GM_RUNPROG_NS_DP , GM_RUNPROG_DS_SP , GM_RUNPROG_DS_DP , GM_RUNPROG_NUM_LEVELS }

enum	TrackOptions { GM_RUNPROG_TRACK_TIME = 0x0001 , GM_RUNPROG_TRACK_MEM = 0x0002 , GM_RUNPROG_TRACK_REPORT_AT_END = 0x0004 , GM_RUNPROG_TRACK_REPORT_STATS = 0x0008 , GM_RUNPROG_TRACK_STATS_MIN = 0x0010 , GM_RUNPROG_TRACK_STATS_MAX = 0x0020 , GM_RUNPROG_TRACK_STATS_AVG = 0x0040 , GM_RUNPROG_TRACK_STATS_TOTAL = 0x0080 , GM_RUNPROG_TRACK_STATS_ALL = 0x00F0 , GM_RUNPROG_TRACK_ATTR_DEFAULT = 0x0100 , GM_RUNPROG_TRACK_DEFAULT }

Public Types inherited from QObject
typedef	QObjectList

Public Slots
void	removeRegisteredItems (QObject *owner)
	Removes all the items belonging to the given owner.

Public Member Functions
	GmRunProgressStats (GmResultsData *resultsData)
	The constructor.

	~GmRunProgressStats ()
	Destructor.

int	registerItem (const QObject *owner, int fatherItemId, QString name, int options=GM_RUNPROG_TRACK_DEFAULT, QString autoId="")
	Registers a NEW item identified by its name. Returns the item id or -1 in case of errors. The full item name is composed by the given name prefixed by its father name (if there is a father) and, if necessary, suffixed by an auto id that makes the name unique. See the details below.

QString	itemName (int itemId) const
	Returns the given item name.

int	findItem (int fatherItemId, QString name) const
	Returns the item id if a registered item composed by the father name and the given name already exists, -1 otherwise.

bool	renameItem (int itemId, QString autoId)
	Renames an item, if possible, to include the given autoId on its name. Expects that the item doesn't already has an autoId part. Returns false if it does. Also, if the added autoId turns the name into an existing name, returns false. Renaming also affects all of the item attributes and is also applied recursively to any item child and their attributes.

bool	validItemId (int itemId) const
	Returns true if the given id is a valid item id.

const QObject *	itemOwner (int itemId) const
	Returns the item owner, if any.

void	setItemData (int itemId, void *data)
	Stores on item the given user data. Can be used by report user functions to inferr an item "semantics".

void	registerNestedItem (int trackingItemId, int trackedItemId)
	Defines that the father item (identified by trackingItemId) will automatically track totals for the attributes existing in the given nested item (trackedItemId).

int	registerAttribute (int itemId, QString name, QString description, Unit unit, int nlin, int ncol, QString format, int statOptions=GM_RUNPROG_TRACK_ATTR_DEFAULT)
	Registers a new value attribute for the given item.

int	registerScalarAttribute (int itemId, QString name, QString description, Unit unit, QString format, int statOptions=GM_RUNPROG_TRACK_ATTR_DEFAULT)
	Registers a scalar attribute.

int	registerCounterAttribute (int itemId, QString name, QString description, int statOptions=GM_RUNPROG_TRACK_ATTR_DEFAULT)
	Registers a counter attribute, always printed as an integer value.

int	registerStringAttribute (int itemId, QString name, QString description, int statOptions=GM_RUNPROG_TRACK_ATTR_DEFAULT)
	Registers a string attribute.

int	attr (int itemId, int attrId) const
	Returns the global results data attribute id for the given item id, local attribute id pair.

GmAttributeResultsManager *	attrManager () const
	Returns the global attribute manager.

int	findAttribute (int itemId, QString name) const
	Returns the LOCAL id of the attribute identified by its parent item and attribute name. Returns -1 if not found.

int	findAttribute (int itemId, int nestedId, QString name) const
	Returns the id of the attribute identified by its parent item, nested item id and attribute name. Returns - 1 if not found or if nestedId is - 1.

int	autoTimeItemAttribute (int itemId) const
	Returns the LOCAL attribute id for the automatic time attribute or -1 if there is none.

int	autoMemItemAttribute (int itemId) const
	Returns the LOCAL attribute id for the automatic memory attribute or -1 if there is none.

GmRunProgressReport *	addNewReport (QString title, QString fileName, bool itemColumn=false)
	Creates a new report to be saved on the given file.

void	addReportToItem (GmRunProgressReport *report, int itemId, QString itemReportDescription)
	Defines that the given item provides data for the given report.

GmRunProgressReport *	report (QString fileName) const
	Returns a pointer to the report saving information to the given file. Returns NULL if there is none.

void	itemStart (int itemId)
	Notifies the progress object that the operation tied to the given item is about to start.

void	itemEnd (int itemId)
	Notifies the progress object that the operation tied to the given item has just finished.

QString	strAttributeValue (int itemId, int attrId) const
	Returns the current value for a string attribute.

const double *	numericAttributeValue (int itemId, int attrId) const
	Returns the current value for a numeric attribute.

void	setAttributeValue (int itemId, int attrId, double val)
	Sets the value for a scalar result attribute identified by its id (returned by registerAttribute())

void	setAttributeValue (int itemId, int attrId, double val1, double val2)
	Sets the value for a vector[2] result attribute identified by its id (returned by registerAttribute())

void	setAttributeValue (int itemId, int attrId, double val1, double val2, double val3)
	Sets the value for a vector[3] result attribute identified by its id (returned by registerAttribute())

void	setAttributeValue (int itemId, int attrId, const double *val)
	Sets the value for a multi valued attribute identified by its id (returned by registerAttribute()). Assumes that the given vector has size equal to the registered size. The values are copied.

void	setAttributeValue (int itemId, int attrId, const GmVector &val)
	Sets the value for a vector valued attribute identified by its id (returned by registerAttribute()). Assumes that the given vector has size equal to the registered size. The values are copied.

void	setAttributeValue (int itemId, int attrId, const GmMatrix &val)
	Sets the value for a matrix valued attribute identified by its id (returned by registerAttribute()). Assumes that the given vector has size equal to the registered size. The values are copied.

void	setAttributeValue (int itemId, int attrId, int val)
	Sets the value for a counter attribute identified by its id (returned by registerCounterAttribute())

void	setAttributeValue (int itemId, int attrId, unsigned val)
	Sets the value for a counter attribute identified by its id (returned by registerCounterAttribute())

void	setAttributeValue (int itemId, int attrId, QString val)
	Sets the value for a string attribute identified by its id (returned by registerStringAttribute())

void	setAttributeValue (int itemId, int attrId, const char *val)
	Sets the value for a string attribute identified by its id (returned by registerStringAttribute())

void	incAttributeValue (int itemId, int attrId)
	Increments the current value of a "counter" attribute, doing the equivalent of attr = attr + 1.

void	decAttributeValue (int itemId, int attrId)
	Decrements the current value of a "counter" attribute, doing the equivalent of attr = attr - 1.

void	reportStats (QString finalStatusStr, qint64 runTime)
	Shows the final statistics report for all the configured items.

void	csvStats (QString csvFile, bool add, bool totalOnly, const QStringList &filters, QString simName, qint64 runTime)
	Saves the contents of the statistics report to a csv file.

void	removeRegisteredItem (int itemId)
	Removes the given registered item.

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

	Q_DISABLE_COPY (Class)

	Q_DISABLE_MOVE (Class)

	Q_DISABLE_COPY_MOVE (Class)

T	qobject_cast (QObject *object)

T	qobject_cast (const QObject *object)

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

	Q_CLASSINFO (Name, Value)

	Q_INTERFACES (...)

	Q_PROPERTY (...)

	Q_ENUMS (...)

	Q_FLAGS (...)

	Q_ENUM (...)

	Q_FLAG (...)

	Q_ENUM_NS (...)

	Q_FLAG_NS (...)

	Q_OBJECT Q_OBJECT

	Q_GADGET Q_GADGET

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_SIGNALS Q_SIGNALS

	Q_SIGNAL Q_SIGNAL

	Q_SLOTS Q_SLOTS

	Q_SLOT Q_SLOT

	Q_EMIT Q_EMIT

	Q_INVOKABLE Q_INVOKABLE

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Static Public Member Functions
static void	setLevelConfiguration (QString item, Level level)
	Sets the level configuration for an item. Should be called before item creation. Intended usage is to define defaults for the item level on simulator startup. If item is equal to ":default", an invalid item name, updates the global default value.

static Level	defLevel ()
	Returns the default level.

static Level	configuredLevel (QString item)
	The configured level for the given item. Can be used to choose the appropriate track options depending on the requested level.

static int	itemOptionsFromLevel (QString item, bool mem=false, bool *detailedStats=NULL)
	Returns the default Track options adjusted by the item level. If detailedStats is not NULL, it will be filled with true for DS_SP or DS_DP levels, false otherwise.

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Private Member Functions
	Q_DISABLE_COPY (GmRunProgressStats)

int	attr (const GmRunProgressStatsItem *item, int attrId) const
	Returns the global results data attribute id for the given item id, local attribute id pair.

QString	parseItemName (int fatherId, QString name, QString autoId) const
	Helper function used by registerItem() to produce the adjusted item name due to its father and autoId, following the rules documented on registerItem().

int	registerAttribute (GmRunProgressStatsItem *item, QString name, QString description, Unit unit, int nlin, int ncol, QString format, int statOptions)
	Registers a new value attribute for the given item.

void	csvStatsFillReportData (bool totalOnly, const QStringList &filters, qint64 runTime, QStringList &attrList, QStringList &unitList, QStringList &dataList) const
	Helper function to produce the data from this simulation that will be exported to the csv file.

bool	csvStatsParseReportData (QString fileName, QString attrHeader, QString unitHeader, int numDataCols, QString dataHeader, QStringList &attrList, QStringList &unitList, QStringList &dataList, QStringList &nameList) const
	Helper function to parse existing data from a previous csv file that will be appended to.

QString	itemStr (const GmRunProgressStatsItem *item, int attrId) const
	Returns a formatted string with the value for an item attribute. Format: name = value unit.

QString	itemStatStr (const GmRunProgressStatsItem *item, int attrId) const
	Returns a formated string with the stored statistics for an item attribute. Format: name = {total=val, avg=val, min=val, max=val} unit.

void	addReportTraillers () const
	Add closing trailler data to existing reports.

Private Attributes
GmResultsData *	_resultsData
	The results data object storing item attributes.

GmAttributeResultsManager *	_attrm
	The attribute manager (from _resultsData)

GmLogCategory	_logger
	The logger object used to emit messages when logging to the standard log file.

QtPtrList< GmRunProgressStatsItem >	_items
	The set of registered items. Might include NULL entries!

QMap< QString, int >	_itemsMap
	Maps item names to their position on _items.

QVector< GmRunProgressReport * >	_reports
	The set of added reports, owned by the progress object.

Static Private Attributes
static QMap< QString, Level >	_levelMap
	The map with item level configuration. Filled BEFORE item creation and used to init item levels.

static Level	_defLevel = GmRunProgressStats::GM_RUNPROG_NS_SP
	The default level for entries that are not present on _levelMap.

Additional Inherited Members
Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties inherited from QObject
	objectName

Detailed Description

A class used to store time, memory and additional values statistics related to the simulation loading and execution.

The progress stats object is composed by a set of items. An item represents an operation that we want to track the execution time and/or values associated with the item. As an example, think of a fem step. It is an item that we want to track the time taken each time it is executed, and also has associated values like the number of non-linear iterations that where executed, the error value, etc
Each item stores a variable number of attribute values. The time taken on each execution and the possible increase of used memory are standard values that can be monitored for each item.
For each item, once the item execution ends, we can log its associated values (including time and memory). That log can be done to the standard logger and/or to an independent report file. A running statistics with the number of times that an item was executed together with the sum, minimum, average and maximum of each value is stored for printing at the end of the simulation. Only the LAST value for each attribute is kept by the progress stat object.
The execution start and end for an item are explicitly informed by the user. That can be automated with a RAII class. Attribute values are zeroed at the item start and the considered values for logging and computed statistics should be explicitly set before the end of the item.
Attribute values should follow the rules for result attributes
- Today result attributes can be scalar values, vector values, matrices or strings.
- They also have a description, a unit and a format
- We can change that, mainly for explicit int or bool attributes, but if that is needed, the results module should follow. Changing is probably unnecessary since we can use the format string to ensure that integer attributes are shown without decimal places.
The presence of the standard time and memory attributes can be controlled when creating the item, together with controls to define if the item data should be logged at each execution or not and if statistics should be kept or not.
Each item has a unique name (maybe hierarchical like fem.step) and a system attributed index number
Items can form a tree hierarchy with an item being a children from another item. Maybe we can use the "." for establishing implicit parenthood among items.
When an item has child items, its printing can include the statistics for the child items. Also, its attributes can be included on the set of the father statistics. Those can be controlled by creation parameters.

Member Enumeration Documentation

◆ Level

enum GmRunProgressStats::Level

Enumerator
GM_RUNPROG_DISABLED	No statistics at all.
GM_RUNPROG_NS_SP	Normal statistics, Summary printing. The default if not changed by a call to setLevelConfiguration()
GM_RUNPROG_NS_DP	Normal statistics, Detailed printing.
GM_RUNPROG_DS_SP	Detailed statistics, Summary printing.
GM_RUNPROG_DS_DP	Detailed statistics, Detailed printing.

◆ TrackOptions

enum GmRunProgressStats::TrackOptions

Enumerator
GM_RUNPROG_TRACK_TIME	Should we track the item execution time (between calls to itemStart() and itemEnd())?
GM_RUNPROG_TRACK_MEM	Should we track the memory used by the item?
GM_RUNPROG_TRACK_REPORT_AT_END	Should the item report values at the call to itemEnd()?
GM_RUNPROG_TRACK_REPORT_STATS	Should the item collect statistics?
GM_RUNPROG_TRACK_STATS_MIN	Should the minimum value be reported on the attribute statistics? For items, represents the attribute default.
GM_RUNPROG_TRACK_STATS_MAX	Should the maximum value be reported on the attribute statistics? For items, represents the attribute default.
GM_RUNPROG_TRACK_STATS_AVG	Should the average value be reported on the attribute statistics? For items, represents the attribute default.
GM_RUNPROG_TRACK_STATS_TOTAL	Should the sum of the values be reported on the attribute statistics? For items, represents the attribute default.
GM_RUNPROG_TRACK_STATS_ALL	Equivalent to the stat flags: MIN + MAX + AVG + TOTAL.
GM_RUNPROG_TRACK_ATTR_DEFAULT	For attribute registration, defines that its should follow the item default.
GM_RUNPROG_TRACK_DEFAULT	The default track settings.

Member Function Documentation

◆ addNewReport()

GmRunProgressReport * GmRunProgressStats::addNewReport	(	QString	title,
		QString	fileName,
		bool	itemColumn = false )

Creates a new report to be saved on the given file.

The given file name can contain path macros. The itemColumn flag define if the report includes a first column with the item name or not.

◆ csvStats()

void GmRunProgressStats::csvStats	(	QString	csvFile,
		bool	add,
		bool	totalOnly,
		const QStringList &	filters,
		QString	simName,
		qint64	runTime )

Saves the contents of the statistics report to a csv file.

Parameters

csvFile	The file name. Can contain path macros.
add	If set to true, instead of creating a new file, adds the data columns to an existing file, matching the lines against existing lines and creating new ones when needed. param totalOnly If set to true, only the total statistics will be addede to the set of data columns
filters	If not empty, only the item attributes present on the given list will be saved
simName	The "name" of the current simulation to be used as "header" for the new columns
runTime	The total time (in ms) of the simulation run.

◆ itemOptionsFromLevel()

int GmRunProgressStats::itemOptionsFromLevel	(	QString	item,
		bool	mem = false,
		bool *	detailedStats = NULL )

static

Returns the default Track options adjusted by the item level. If detailedStats is not NULL, it will be filled with true for DS_SP or DS_DP levels, false otherwise.

For DISABLED, returns 0 For NS_SP, returns DEFAULT For NS_DP, returns DEFAULT | REPORT_AT_END For DS_SP, returns DEFAULT ored with MEM if mem is true For DS_DP, returns DEFAULT | REPORT_AT_END ored with MEM if mem is true

◆ parseItemName()

QString GmRunProgressStats::parseItemName	(	int	fatherId,
		QString	name,
		QString	autoId ) const

private

Helper function used by registerItem() to produce the adjusted item name due to its father and autoId, following the rules documented on registerItem().

Returns the new item name already made unique. If the name is invalid (badly formed), or on error making it unique, returns the empty string.

◆ registerAttribute() [1/2]

int GmRunProgressStats::registerAttribute	(	GmRunProgressStatsItem *	item,
		QString	name,
		QString	description,
		Unit	unit,
		int	nlin,
		int	ncol,
		QString	format,
		int	statOptions )

private

Registers a new value attribute for the given item.

Follows the protocol for attribute registering defined by GmResultsData::registerResultAttribute(). Please see that method description. Uses the item object referenced by itemId as the attribute owner.

Returns an attribute index that is LOCAL to the item.

◆ registerAttribute() [2/2]

int GmRunProgressStats::registerAttribute	(	int	itemId,
		QString	name,
		QString	description,
		Unit	unit,
		int	nlin,
		int	ncol,
		QString	format,
		int	statOptions = GM_RUNPROG_TRACK_ATTR_DEFAULT )

inline

Registers a new value attribute for the given item.

Follows the protocol for attribute registering defined by GmResultsData::registerResultAttribute(). Please see that method description. Uses the item object referenced by itemId as the attribute owner.

Returns an attribute index that is LOCAL to the item.

◆ registerItem()

int GmRunProgressStats::registerItem	(	const QObject *	owner,
		int	fatherItemId,
		QString	name,
		int	options = GM_RUNPROG_TRACK_DEFAULT,
		QString	autoId = "" )

Registers a NEW item identified by its name. Returns the item id or -1 in case of errors. The full item name is composed by the given name prefixed by its father name (if there is a father) and, if necessary, suffixed by an auto id that makes the name unique. See the details below.

To make item names unique, an "[auto_id]" suffix is appended to the name when necessary to make it unique. The auto_id suffix is given by the autoId parameter. If autoId is empty or the name with the previous suffix is still not unique, a unique numeric value is inserted into the autoId string. If that is still not unique, returns -1 on error.

If the autoId parameter is not empty, the autoId will always be added to the name in order to provide previsibility to the resulting name.

Parameters

owner	The object that contains this item. If owner is different from NULL, the item will be automatically removed from the item list when the owner object is destroyed.
name	The item name. If a father item was provided, the item name will be composed by the father name + '.' + given name + the optional auto id part as explained above. Names should NOT contain ., :, [ or ] characters.
fatherItemId	The id of the father item or -1 if there is none.
options	The item options. It is a or of the desired flags from the TrackOptions enum.
autoId	The additional id added to the item name, as explained above

Returns: Returns the new item id or -1 on error (unknown father item, for example)

◆ registerNestedItem()

void GmRunProgressStats::registerNestedItem	(	int	trackingItemId,
		int	trackedItemId )

Defines that the father item (identified by trackingItemId) will automatically track
totals for the attributes existing in the given nested item (trackedItemId).

If the trackedItemId is -1, the call is silently ignored. No checking is done for duplicate calls, so don't do it!

◆ reportStats()

void GmRunProgressStats::reportStats	(	QString	finalStatusStr,
		qint64	runTime )

Shows the final statistics report for all the configured items.

Given parameters are extra information presented at the summary at the end of the report: The final simulation status and the total time (in ms) of the simulation run.

The documentation for this class was generated from the following files:

inc/results/gmRunProgressStats.h
src/results/gmRunProgressStats.cpp

Public Types

Public Slots

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members