Util

Histogram.h

class Cubism::Util::Histogram : public Cubism::Util::Sampler

MPI profiling using histograms.

Collects samples for a profiled quantity of interest on individual ranks. Can be used to detect inhomogeneities among MPI ranks.

Public Functions

inline Histogram(const MPI_Comm comm, const std::string &name, const bool active = true)

Main histogram constructor.

Extends the Sampler.h class with MPI consolidation during destruction of the object. The consolidation generates a binary file that can be post-processed using the histbin tool. The activator switch can be used to disable sample collection for large scale runs. The size of the binary files can become large depending on the number of ranks involved and the number of different quantities that are being sampled.

Parameters

  • comm: MPI communicator used for the profiling

  • name: Name of the histogram

  • active: Activator switch

INIParser.h

class Cubism::Util::INIParser

INI config file parser.

Simple configuration file parser for use on the application level. CubismNova does not depend on this parser. The .ini file format is explained in more detail on Wikipedia for example. The python configparser module supports this format for convenient simulation case setup using python.

Public Functions

explicit INIParser(const std::string &filename)

Construct INIParser and parse given filename.

Parameters

  • filename: Configuration file path

explicit INIParser(const char *buffer, size_t buffer_size)

Construct INIParser and parse given buffer.

Parameters

  • buffer: Configuration character buffer

  • buffer_size: Number of bytes in buffer

bool parseError() const

Return the global result of ini_parse() for all files.

Return

False if no errors occurred during parsing

std::map<std::string, int> fileErrors() const

Return the result of ini_parse()

For each key in the map: 0 on success, line number of first error or -1 on file open error.

Return

Map for each INI file found in the main configuration

std::string get(const std::string &section, const std::string &name) const

Get a raw string value from INI file.

Throws a runtime error if not found.

Return

String value related to section and name

Parameters

  • section: Section name

  • name: Key name

std::string getString(const std::string &section, const std::string &name) const

Get a parsed string value from INI file.

Throws a runtime error if not found.

Return

Parsed string key value

Parameters

  • section: Section name

  • name: Key name

std::vector<std::string> getStringArray(const std::string &section, const std::string &name) const

Get a parsed array of string values from INI file.

Throws a runtime error if not found.

Return

Parsed array of strings

Parameters

  • section: Section name

  • name: Key name

long getInteger(const std::string &section, const std::string &name) const

Get a parsed integer (long) value from INI file.

Valid integers are decimal 1234, -1234, or hex 0x4d2. Throws a runtime error if not found.

Return

Parsed integer key value

Parameters

  • section: Section name

  • name: Key name

std::vector<long> getIntegerArray(const std::string &section, const std::string &name) const

Get a parsed array of integer values (long) from INI file.

Valid integers are decimal 1234, -1234, or hex 0x4d2. Throws a runtime error if not found.

Return

Parsed array of integers

Parameters

  • section: Section name

  • name: Key name

double getReal(const std::string &section, const std::string &name) const

Get a parsed real (double) value from INI file.

Valid floating point values according to strtod(). Throws a runtime error if not found.

Return

Parsed floating point key value

Parameters

  • section: Section name

  • name: Key name

std::vector<double> getRealArray(const std::string &section, const std::string &name) const

Get a parsed array of real (double) values from INI file.

Valid floating point values according to strtod(). Throws a runtime error if not found.

Return

Parsed array of floating point values

Parameters

  • section: Section name

  • name: Key name

bool getBoolean(const std::string &section, const std::string &name) const

Get a parsed boolean (bool) value from INI file.

Valid true values are true, yes, on, 1, and valid false values are false, no, off, 0 (not case sensitive). Throws a runtime error if not found.

Return

Parsed boolean value

Parameters

  • section: Section name

  • name: Key name

std::vector<bool> getBooleanArray(const std::string &section, const std::string &name) const

Get a parsed array of boolean (bool) values from INI file.

Valid true values are true, yes, on, 1, and valid false values are false, no, off, 0 (not case sensitive). Throws a runtime error if not found.

Return

Parsed array of boolean values

Parameters

  • section: Section name

  • name: Key name

bool hasSection(const std::string &section) const

Return true if the given section exists.

The section must contain at least one name=value pair.

Parameters

  • section: Section name

bool hasValue(const std::string &section, const std::string &name) const

Return true if a value exists.

Parameters

  • section: Section name

  • name: Key name

void write(const std::string &filename = "runtime.ini") const

Write currently loaded configuration to INI file format.

Parameters

  • filename: Output file path

Friends

friend friend std::ostream & operator<< (std::ostream &os, const INIParser &p)

Redirection to std::ostream

Parameters

  • os: Output stream

  • p: INI parser instance

Profiler.h

class Cubism::Util::Profiler : public Cubism::Util::Sampler

Runtime profiler.

Used to collect runtime samples for a code section that is enclosed by the push() and pop() methods. Used for profiling.

Public Functions

inline Profiler(const std::string &name = "default", const MPI_Comm comm = MPI_COMM_WORLD)

Main constructor.

Parameters

  • name: Name of the profiler

  • comm: MPI communicator associated to the profiler

inline void push(const std::string &name)

Push a new profiling agent on the stack.

Starts a timer for a new profiling agent.

Parameters

  • name: Name of the agent

inline void pop()

Pop the top profiling agent.

Pops the top (most recent) profiling agent from the stack and collects the time measurement.

void printReport()

Print profiling report to standard output.

Sampler.h

class Cubism::Util::Sampler

Sample collector.

Used to collect time samples (by default) for a code section that is enclosed by the seedSample() and collectSample() methods. Used for profiling.

Subclassed by Cubism::Util::Histogram, Cubism::Util::Profiler

Public Functions

inline explicit Sampler(const bool active = true)

Default constructor.

Parameters

  • active: Activator switch

inline void seedSample()

Seed new sample.

Pushes a new timer on the stack.

inline void collectSample(const std::string &name)

Collect a sample.

Pops the top timer off the stack and collects the measured time sample for the given name.

Parameters

  • name: Name of the collected sample

inline void popLast(const std::string &name)

Pop a sample.

Pops the last (most recent) sample of name from the sample container.

Parameters

  • name: Name of the sample

inline void append(const Sampler &s)

Append samples.

Inserts all samples from s into this sampler.

Parameters

  • s: Sampler to take samples from

inline void appendSample(const std::string &name, const double samp)

Append single sample.

Appends the sample samp to the list of samples with name.

Parameters

  • name: Name of the sample

  • samp: Sample value

inline void insert(const std::string &name, const std::vector<double> &data)

Insert vector of samples.

Parameters

  • name: Name of the samples

  • data: Vector of samples to be inserted

inline void addTo(const std::string &addto, const std::vector<double> &yours)

Perform addition with sample values.

The number of samples in yours must be the same as the number of samples in addto, otherwise a runtime error is thrown.

Parameters

  • addto: Name of samples to be added to

  • yours: Vector of samples to be arithmetically added

inline void subtractFrom(const std::string &from, const std::vector<double> &yours)

Perform subtraction with sample values.

The number of samples in yours must be the same as the number of samples in from, otherwise a runtime error is thrown.

Parameters

  • from: Name of samples to be subtracted from (minuend)

  • yours: Vector of samples to be arithmetically subtracted (subtrahend)

inline const SampleMap &getSamples() const

Get the sample container.

Return

const reference to sample map

inline void clear()

Clear the sampler data.

After this method is called the sampler will contain zero samples.

Timer.h

class Cubism::Util::Timer

Simple timer class.

Public Functions

inline Timer()

Default constructor.

Starts the timer

inline void start()

Restart the timer.

inline double stop() const

Get the currently elapsed seconds.

Return

Elapsed seconds since construction or start

Version.h

const char *Cubism::Util::CubismVersion

Cubism version at build time. Falls back to VERSION for a release.

Command:

git describe --long --dirty --broken

Example: v1.1.8-5-g824e676-dirty

The string starts with the version number, followed by the number of commits ahead of tagged commit (5 in this case), followed by g and the short hash (SHA-1) of HEAD, followed by the state of the working tree (if any).

Warning

doxygenvariable: Cannot find variable “Cubism::Util::CubismVersionHEAD” in doxygen xml output for project “CubismNova” from directory: ../doxygen/xml

Warning

doxygenvariable: Cannot find variable “Cubism::Util::CubismBranch” in doxygen xml output for project “CubismNova” from directory: ../doxygen/xml