sc_statistics.h File Reference

Computation of average and mean values etc. More...

#include <sc_keyvalue.h>

Include dependency graph for sc_statistics.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	sc_statinfo
	Store information of one random variable. More...
struct	sc_stats
	The statistics container allows dynamically adding random variables. More...

Typedefs
typedef struct sc_statinfo	sc_statinfo_t
	Store information of one random variable.
typedef struct sc_stats	sc_statistics_t
	The statistics container allows dynamically adding random variables.

Functions
void	sc_stats_set1 (sc_statinfo_t *stats, double value, const char *variable)
	Populate a sc_statinfo_t structure assuming count=1 and mark it dirty. More...
void	sc_stats_set1_ext (sc_statinfo_t *stats, double value, const char *variable, int copy_variable, int stats_group, int stats_prio)
	Populate a sc_statinfo_t structure assuming count=1 and mark it dirty. More...
void	sc_stats_init (sc_statinfo_t *stats, const char *variable)
	Initialize a sc_statinfo_t structure assuming count=0 and mark it dirty. More...
void	sc_stats_init_ext (sc_statinfo_t *stats, const char *variable, int copy_variable, int stats_group, int stats_prio)
	Initialize a sc_statinfo_t structure assuming count=0 and mark it dirty. More...
void	sc_stats_reset (sc_statinfo_t *stats, int reset_vgp)
	Reset all values to zero, optionally unassign name, group, and priority. More...
void	sc_stats_set_group_prio (sc_statinfo_t *stats, int stats_group, int stats_prio)
	Set/update the group and priority information for a stats item. More...
void	sc_stats_accumulate (sc_statinfo_t *stats, double value)
	Add an instance of the random variable. More...
void	sc_stats_compute (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t *stats)
	Compute global average and standard deviation. More...
void	sc_stats_compute1 (sc_MPI_Comm mpicomm, int nvars, sc_statinfo_t *stats)
	Version of sc_statistics_statistics that assumes count=1. More...
void	sc_stats_print (int package_id, int log_priority, int nvars, sc_statinfo_t *stats, int full, int summary)
	Print measured statistics. More...
void	sc_stats_print_ext (int package_id, int log_priority, int nvars, sc_statinfo_t *stats, int stats_group, int stats_prio, int full, int summary)
	Print measured statistics, filter by group and/or priority. More...
sc_statistics_t *	sc_statistics_new (sc_MPI_Comm mpicomm)
	Create a new statistics structure that can grow dynamically.
void	sc_statistics_destroy (sc_statistics_t *stats)
	Destroy a statistics structure. More...
void	sc_statistics_add (sc_statistics_t *stats, const char *name)
	Register a statistics variable by name and set its value to 0. More...
void	sc_statistics_add_empty (sc_statistics_t *stats, const char *name)
	Register a statistics variable by name and set its count to 0. More...
int	sc_statistics_has (sc_statistics_t *stats, const char *name)
	Returns true if the stats include a variable with the given name.
void	sc_statistics_set (sc_statistics_t *stats, const char *name, double value)
	Set the value of a statistics variable, see sc_stats_set1. More...
void	sc_statistics_accumulate (sc_statistics_t *stats, const char *name, double value)
	Add an instance of a statistics variable, see sc_stats_accumulate The variable must previously be added with sc_statistics_add_empty.
void	sc_statistics_compute (sc_statistics_t *stats)
	Compute statistics for all variables, see sc_stats_compute.
void	sc_statistics_print (sc_statistics_t *stats, int package_id, int log_priority, int full, int summary)
	Print all statistics variables, see sc_stats_print.

Variables
const int	sc_stats_group_all
	This special group number (negative) will refer to any group.
const int	sc_stats_prio_all
	This special group number (negative) will refer to any priority.

Detailed Description

Computation of average and mean values etc.

between parallel processes.

Function Documentation

sc_statistics_add()

void sc_statistics_add	(	sc_statistics_t *	stats,
		const char *	name
	)

Register a statistics variable by name and set its value to 0.

This variable must not exist already.

sc_statistics_add_empty()

void sc_statistics_add_empty	(	sc_statistics_t *	stats,
		const char *	name
	)

Register a statistics variable by name and set its count to 0.

This variable must not exist already.

sc_statistics_destroy()

void sc_statistics_destroy

(

sc_statistics_t *

stats

)

Destroy a statistics structure.

Parameters

[in,out]

stats

Valid object is invalidated.

sc_statistics_set()

void sc_statistics_set	(	sc_statistics_t *	stats,
		const char *	name,
		double	value
	)

Set the value of a statistics variable, see sc_stats_set1.

The variable must previously be added with sc_statistics_add. This assumes count=1 as in the sc_stats_set1 function above.

sc_stats_accumulate()

void sc_stats_accumulate	(	sc_statinfo_t *	stats,
		double	value
	)

Add an instance of the random variable.

The counter of the variable is increased by one. The value is added into the present values of the variable.

Parameters

[out]	stats	Must be dirty. We bump count and values.
[in]	value	Value used to update statistics information.

sc_stats_compute()

void sc_stats_compute	(	sc_MPI_Comm	mpicomm,
		int	nvars,
		sc_statinfo_t *	stats
	)

Compute global average and standard deviation.

Only updates dirty variables. Then removes the dirty flag.

Parameters

[in]	mpicomm	MPI communicator to use.
[in]	nvars	Number of variables to be examined.
[in,out]	stats	Set of statisics items for each variable. On input, set the following fields for each variable separately. count Number of values for each process. sum_values Sum of values for each process. sum_squares Sum of squares for each process. min, max Minimum and maximum of values for each process. variable String describing the variable, or NULL. On output, the fields have the following meaning. count Global number of values. sum_values Global sum of values. sum_squares Global sum of squares. min, max Global minimum and maximum values. min_at_rank, max_at_rank The ranks that attain min and max. average, variance, standev Global statistical measures. variance_mean, standev_mean Statistical measures of the mean.

sc_stats_compute1()

void sc_stats_compute1	(	sc_MPI_Comm	mpicomm,
		int	nvars,
		sc_statinfo_t *	stats
	)

Version of sc_statistics_statistics that assumes count=1.

On input, the field sum_values needs to be set to the value and the field variable must contain a valid string or NULL. Only updates dirty variables. Then removes the dirty flag.

sc_stats_init()

void sc_stats_init	(	sc_statinfo_t *	stats,
		const char *	variable
	)

Initialize a sc_statinfo_t structure assuming count=0 and mark it dirty.

This is useful if stats will be used to sc_stats_accumulate instances locally before global statistics are computed. We set sc_stats_group_all and sc_stats_prio_all internally.

Parameters

[out]	stats	Will be filled with count 0 and values of 0.
[in]	variable	String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use.

sc_stats_init_ext()

void sc_stats_init_ext	(	sc_statinfo_t *	stats,
		const char *	variable,
		int	copy_variable,
		int	stats_group,
		int	stats_prio
	)

Initialize a sc_statinfo_t structure assuming count=0 and mark it dirty.

This is useful if stats will be used to sc_stats_accumulate instances locally before global statistics are computed.

Parameters

[out]	stats	Will be filled with count 0 and values of 0.
[in]	variable	String to be reported by sc_stats_print.
[in]	copy_variable	If true, make internal copy of variable. Otherwise just assign the pointer.
[in]	stats_group	Non-negative number or sc_stats_group_all.
[in]	stats_prio	Non-negative number or sc_stats_prio_all. Values increase by importance.

sc_stats_print()

void sc_stats_print	(	int	package_id,
		int	log_priority,
		int	nvars,
		sc_statinfo_t *	stats,
		int	full,
		int	summary
	)

Print measured statistics.

This function uses the SC_LC_GLOBAL log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler. All groups and priorities are printed.

Parameters

[in]	package_id	Registered package id or -1.
[in]	log_priority	Log priority for output according to sc.h.
[in]	nvars	Number of stats items in input array.
[in]	stats	Input array of stats variable items.
[in]	full	Print full information for every variable.
[in]	summary	Print summary information all on 1 line.

sc_stats_print_ext()

void sc_stats_print_ext	(	int	package_id,
		int	log_priority,
		int	nvars,
		sc_statinfo_t *	stats,
		int	stats_group,
		int	stats_prio,
		int	full,
		int	summary
	)

Print measured statistics, filter by group and/or priority.

This function uses the SC_LC_GLOBAL log category. That means the default action is to print only on rank 0. Applications can change that by providing a user-defined log handler.

Parameters

[in]	package_id	Registered package id or -1.
[in]	log_priority	Log priority for output according to sc.h.
[in]	nvars	Number of stats items in input array.
[in]	stats	Input array of stats variable items.
[in]	stats_group	Print only this group. Non-negative or sc_stats_group_all. We skip printing a variable if neither this parameter nor the item's group is all and if the item's group does not match this.
[in]	stats_prio	Print this and higher priorities. Non-negative or sc_stats_prio_all. We skip printing a variable if neither this parameter nor the item's prio is all and if the item's prio is less than this.
[in]	full	Print full information for every variable. This produces multiple lines including minimum, maximum, and standard deviation. If this is false, print one line per variable.
[in]	summary	Print summary information all on 1 line. This always contains all variables. Not affected by stats_group and stats_prio.

sc_stats_reset()

void sc_stats_reset	(	sc_statinfo_t *	stats,
		int	reset_vgp
	)

Reset all values to zero, optionally unassign name, group, and priority.

Parameters

[in,out]	stats	Variables are zeroed. They can be set again by set1 or accumulate.
[in]	reset_vgp	If true, the variable name string is zeroed and if we did a copy, the copy is freed. If true, group and priority are set to all. If false, we don't touch any of the above.

sc_stats_set1()

void sc_stats_set1	(	sc_statinfo_t *	stats,
		double	value,
		const char *	variable
	)

Populate a sc_statinfo_t structure assuming count=1 and mark it dirty.

We set sc_stats_group_all and sc_stats_prio_all internally.

Parameters

[out]	stats	Will be filled with count=1 and the value.
[in]	value	Value used to fill statistics information.
[in]	variable	String to be reported by sc_stats_print. This string is assigned by pointer, not copied. Thus, it must stay alive while stats is in use.

sc_stats_set1_ext()

void sc_stats_set1_ext	(	sc_statinfo_t *	stats,
		double	value,
		const char *	variable,
		int	copy_variable,
		int	stats_group,
		int	stats_prio
	)

Populate a sc_statinfo_t structure assuming count=1 and mark it dirty.

Parameters

[out]	stats	Will be filled with count=1 and the value.
[in]	value	Value used to fill statistics information.
[in]	variable	String to be reported by sc_stats_print.
[in]	copy_variable	If true, make internal copy of variable. Otherwise just assign the pointer.
[in]	stats_group	Non-negative number or sc_stats_group_all.
[in]	stats_prio	Non-negative number or sc_stats_prio_all.

sc_stats_set_group_prio()

void sc_stats_set_group_prio	(	sc_statinfo_t *	stats,
		int	stats_group,
		int	stats_prio
	)

Set/update the group and priority information for a stats item.

Parameters

[out]	stats	Only group and stats entries are updated.
[in]	stats_group	Non-negative number or sc_stats_group_all.
[in]	stats_prio	Non-negative number or sc_stats_prio_all. Values increase by importance.