API

Anomaly Detection Algorithm Parameters

Parameters of the anomaly detection algorithm.

ParamInterface

namespace chimbuko
class ParamInterface
#include <param.hpp>

The general interface for storing function statistics for anomaly detection.

Subclassed by chimbuko::CopodParam, chimbuko::HbosParam, chimbuko::SstdParam

Public Functions

ParamInterface()
inline virtual ~ParamInterface()
virtual void clear() = 0

Clear all statistics.

virtual size_t size() const = 0

Get the number of models for which statistics are being collected.

virtual std::string serialize() const = 0

Convert internal models to string format for IO.

Returns:

Run statistics in string format

virtual std::string update(const std::string &parameters, bool return_update = false) = 0

Update the internal models with those included in the serialized input map.

Note: we combine update and serialize here in order to avoid having to acquire 2 successive mutex locks on the pserver

Parameters:

  • parameters – The parameters in serialized format

  • return_update – Indicates that the function should return a serialized copy of the updated parameters

Returns:

An empty string or a serialized copy of the updated parameters depending on return_update

virtual void update(const ParamInterface &other) = 0

Update the internal run statistics with those from another instance.

The instance will be dynamically cast to the derived type internally, and will throw an error if the types do not match The other instance will be locked during the process for thread safety

virtual void update(const std::vector<ParamInterface*> &other)

Update the internal run statistics with those from multiple other instances.

The instance will be dynamically cast to the derived type internally, and will throw an error if the types do not match The other instance will be locked during the process for thread safety

virtual void assign(const std::string &parameters) = 0

Set the internal run statistics to match those included in the serialized input model. Overwrite performed only for those model indices in te input.

Parameters:

parameters – The serialized input model

virtual void show(std::ostream &os) const = 0
virtual nlohmann::json get_algorithm_params(const unsigned long model_idx) const = 0

Get the algorithm parameters associated with a given model index. Format is algorithm dependent.

virtual std::unordered_map<unsigned long, nlohmann::json> get_all_algorithm_params() const = 0

Get the algorithm parameters for all model indices. Returns a map of model index to JSON-formatted parameters. Parameter format is algorithm dependent.

virtual nlohmann::json serialize_json() const = 0

Serialize the set of algorithm parameters in JSON form for purpose of inter-run persistence, format may differ from the above.

virtual void deserialize_json(const nlohmann::json &from) = 0

De-serialize the set of algorithm parameters from JSON form created by serialize_json.

Public Static Functions

static ParamInterface *set_AdParam(const std::string &ad_algorithm)

Return a pointer to a new instance of the ParamInterface derived class associated with the given algorithm.

Protected Attributes

mutable std::mutex m_mutex
class NetPayloadUpdateParams : public chimbuko::NetPayloadBase
#include <param.hpp>

Net payload for pserver updating params from AD.

Public Functions

inline NetPayloadUpdateParams(ParamInterface *param, bool freeze = false)

Construct the NetPayloadUpdateParams object.

Parameters:

  • param – A pointer to an instance of ParamInterface

  • freeze – If true the state will not be modified by the update command

inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

inline virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

Private Members

ParamInterface *m_param
bool m_freeze

If set to true, the additional data from the AD will be ignored and the parameter state will not change

class NetPayloadGetParams : public chimbuko::NetPayloadBase
#include <param.hpp>

Net payload for AD updating params from pserver.

Public Functions

inline NetPayloadGetParams(ParamInterface const *param)
inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

inline virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

Private Members

ParamInterface const *m_param

CopodParam

namespace chimbuko
class CopodFuncParam
#include <copod_param.hpp>

The algorithm parameters for a given model.

Public Functions

CopodFuncParam()
inline const Histogram &getHistogram() const
inline Histogram &getHistogram()
inline double getInternalGlobalThreshold() const
inline void setInternalGlobalThreshold(double to)
void merge(const CopodFuncParam &other)

Merge another instance of HbosFuncParam into this one.

Parameters:

other – The other instance

nlohmann::json get_json() const
template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal.

inline bool operator==(const CopodFuncParam &other) const
inline bool operator!=(const CopodFuncParam &other) const

Private Members

Histogram m_histogram

The function runtime histogram

double m_internal_global_threshold

An internal global threshold used by the algorithm

class CopodParam : public chimbuko::ParamInterface
#include <copod_param.hpp>

@brief Implementation of ParamInterface for COPOD based anomaly detection

Public Functions

CopodParam()
~CopodParam()
virtual void clear() override

Clear all statistics.

inline void copy(const CopodParam &r)

Copy an existing HbosParam.

const int find(const unsigned long model_id)

Check if the statistics for a model exist in the histogram.

inline const std::unordered_map<unsigned long, CopodFuncParam> &get_copodstats() const

Get the internal map between model index and statistics.

inline void set_copodstats(const std::unordered_map<unsigned long, CopodFuncParam> &to)

Set the internal map between model index and statistics to the provided input.

inline virtual size_t size() const override

Get the number of functions for which statistics are being collected.

virtual std::string serialize() const override

Convert internal Histogram to string format for IO.

Returns:

Histogram in string format

virtual std::string update(const std::string &parameters, bool return_update = false) override

Update the internal Histogram with those included in the serialized input map.

Parameters:

  • parameters – The parameters in serialized format

  • return_update – Controls return format

Returns:

An empty string if return_update==False, otherwise the serialized updated parameters

virtual void assign(const std::string &parameters) override

Set the internal Histogram to match those included in the serialized input map. Overwrite performed only for those keys in input.

Parameters:

parameters – The serialized input map

virtual void show(std::ostream &os) const override
void assign(const CopodParam &other)

Set the internal data to match those included in the input. Overwrite performed only for those keys in input.

Parameters:

params – The input data

inline CopodFuncParam &operator[](unsigned long id)

Get an element of the internal map.

Parameters:

id – The model index

void update(const CopodParam &other)

Update the internal Histogram with those included in another CopodParam instance.

The other instance is locked during the process

Parameters:

other – [in] The other CopodParam instance

inline virtual void update(const ParamInterface &other) override

Update the internal model from another instance.

The instance will be dynamically cast to the derived type internally, and will throw an error if the types do not match

void update_and_return(CopodParam &other)

Update the internal histogram with those included in another CopodParam instance. Other CopodParam is then updated to reflect new state.

Parameters:

other – [inout] The other CopodParam instance

virtual nlohmann::json get_algorithm_params(const unsigned long model_idx) const override

Get the parameters (histogram) associated with a specific model index in JSON format.

virtual std::unordered_map<unsigned long, nlohmann::json> get_all_algorithm_params() const override

Get the algorithm parameters for all model indices. Returns a map of model index to JSON-formatted parameters. Parameter format is algorithm dependent.

virtual nlohmann::json serialize_json() const override

Serialize the set of algorithm parameters in JSON form for purpose of inter-run persistence, format may differ from the above.

virtual void deserialize_json(const nlohmann::json &from) override

De-serialize the set of algorithm parameters from JSON form created by serialize_json.

Public Static Functions

static std::string serialize_cerealpb(const CopodParam &param)

Convert a CopodParam into a Cereal portable binary representration.

Parameters:

param – The CopodParam instance

Returns:

Histogram in string format

static void deserialize_cerealpb(const std::string &parameters, CopodParam &p)

Deserialize a CopodParam instance.

Parameters:

  • parameters – [in] The parameter string

  • p – [out] The CopodParam instance

Private Members

std::unordered_map<unsigned long, CopodFuncParam> m_copodstats

Map of model index and corresponding Histogram

HbosParam

namespace chimbuko
class HbosFuncParam
#include <hbos_param.hpp>

The algorithm parameters for a given model.

Public Functions

HbosFuncParam()
inline const Histogram &getHistogram() const
inline Histogram &getHistogram()
inline double getInternalGlobalThreshold() const
inline void setInternalGlobalThreshold(double to)
void merge(const HbosFuncParam &other, const binWidthSpecifier &bw)

Merge another instance of HbosFuncParam into this one.

Parameters:

  • other – The other instance

  • bw – The specifier for the bin width used in the histogram merge

nlohmann::json get_json() const
template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal.

inline bool operator==(const HbosFuncParam &other) const
inline bool operator!=(const HbosFuncParam &other) const

Private Members

Histogram m_histogram

The function runtime histogram

double m_internal_global_threshold

An internal global threshold used by the algorithm

class HbosParam : public chimbuko::ParamInterface
#include <hbos_param.hpp>

Implementation of ParamInterface for HBOS based anomaly detection.

Public Functions

HbosParam()
~HbosParam()
void copy(const HbosParam &r)

Copy an existing HbosParam.

Thread safe

virtual void clear() override

Clear all statistics.

bool find(const unsigned long model_id) const

Check if the statistics for a model exist in the histogram.

inline const std::unordered_map<unsigned long, HbosFuncParam> &get_hbosstats() const

Get the internal map between model index and statistics.

inline void set_hbosstats(const std::unordered_map<unsigned long, HbosFuncParam> &to)

Set the internal map between model index and statistics to the provided input.

inline virtual size_t size() const override

Get the number of models for which statistics are being collected.

virtual std::string serialize() const override

Convert internal Histogram to string format for IO.

Returns:

Histogram in string format

virtual std::string update(const std::string &parameters, bool return_update = false) override

Update the internal Histogram with those included in the serialized input map.

Parameters:

  • parameters – The parameters in serialized format

  • return_update – Controls return format

Returns:

An empty string if return_update==False, otherwise the serialized updated parameters

virtual void assign(const std::string &parameters) override

Set the internal Histogram to match those included in the serialized input map. Overwrite performed only for those keys in input.

Parameters:

parameters – The serialized input data

virtual void show(std::ostream &os) const override
void assign(const HbosParam &params)

Set the internal data to match those included in the input. Overwrite performed only for those keys in input.

Parameters:

params – The input data

inline HbosFuncParam &operator[](unsigned long id)

Get an element of the internal map.

Parameters:

id – The model index

void update(const HbosParam &other)

Update the internal histogram with those included in the input data.

The other instance is locked during the process

Parameters:

param – [in] The input HbosParam object

inline virtual void update(const ParamInterface &other) override

Update the internal run statistics with those from another instance.

The instance will be dynamically cast to the derived type internally, and will throw an error if the types do not match

void update_and_return(HbosParam &from_into)

Update the internal data with those included in the input. The input is then updated to reflect new state.

Parameters:

from_into – [inout] The input/output data

virtual nlohmann::json get_algorithm_params(const unsigned long model_idx) const override

Get the parameters (histogram) associated with a specific model index in JSON format.

virtual std::unordered_map<unsigned long, nlohmann::json> get_all_algorithm_params() const override

Get the algorithm parameters for all model indices. Returns a map of model index to JSON-formatted parameters. Parameter format is algorithm dependent.

inline int getMaxBins() const

Get the maximum number of bins.

inline void setMaxBins(const int b)

Set the maximum number of bins.

void generate_histogram(const unsigned long model_id, const std::vector<double> &values, double global_threshold_init, HbosParam const *global_param = nullptr)

Generate the histogram for a particular function based on the batch of runtimes.

Parameters:

  • model_id – The model index

  • values – The data used to generate the model

  • global_param – A pointer to the current global histogram. If non-null both the global model and the values dataset will be used to determine the optimal bin width

  • global_threshold_init – The initial value of the internal, global threshold

virtual nlohmann::json serialize_json() const override

Serialize the set of algorithm parameters in JSON form for purpose of inter-run persistence, format may differ from the above.

virtual void deserialize_json(const nlohmann::json &from) override

De-serialize the set of algorithm parameters from JSON form created by serialize_json.

bool operator==(const HbosParam &r) const
inline bool operator!=(const HbosParam &r) const

Public Static Functions

static std::string serialize_cerealpb(const HbosParam &params)

Convert a HbosParam into a string representration.

static void deserialize_cerealpb(const std::string &parameters, HbosParam &into)

Deserialize a serialized HbosParam object Histogram Cereal portable binary representation string into a map.

Parameters:

  • parameters – [in] The serialized object

  • into – [out] The deserialized object

Private Functions

void update_internal(const HbosParam &other)

Common functionality between update and update_and_return; assumed a mutex lock exists on this and other.

Private Members

std::unordered_map<unsigned long, HbosFuncParam> m_hbosstats

Map of model id and corresponding Histogram

int m_maxbins

Maximum number of bins to use in the histograms

SstdParam

namespace chimbuko
class SstdParam : public chimbuko::ParamInterface
#include <sstd_param.hpp>

@brief Implementation of ParamInterface for anomaly detection based on function time distribution (mean, std. dev., etc)

Public Functions

SstdParam()
~SstdParam()
virtual void clear() override

Clear all statistics.

inline virtual size_t size() const override

Get the number of models for which statistics are being collected.

virtual std::string serialize() const override

Convert internal run statistics to string format for IO.

Returns:

Run statistics in string format

virtual std::string update(const std::string &parameters, bool return_update = false) override

Update the internal run statistics with those included in the serialized input map.

Parameters:

  • parameters – The parameters in serialized format

  • return_update – Indicates that the function should return a serialized copy of the updated parameters

Returns:

An empty string or a serialized copy of the updated parameters depending on return_update

virtual void assign(const std::string &parameters) override

Set the internal run statistics to match those included in the serialized input map. Overwrite performed only for those keys in input.

Parameters:

runstats – The serialized input map

virtual void show(std::ostream &os) const override
void update(const std::unordered_map<unsigned long, RunStats> &runstats)

Update the internal run statistics with those included in the input map.

Parameters:

runstats – [in] The map between global function index and statistics

void update(const SstdParam &other)

Update the internal statistics with those included in another SstdParam instance.

The other instance is locked during the process

Parameters:

other – [in] The other SstdParam instance

inline virtual void update(const ParamInterface &other) override

Update the internal run statistics with those from another instance.

The instance will be dynamically cast to the derived type internally, and will throw an error if the types do not match

void update_and_return(std::unordered_map<unsigned long, RunStats> &runstats)

Update the internal run statistics with those included in the input map. Input map is then updated to reflect new state.

Parameters:

runstats – [inout] The map between global function index and statistics

inline void update_and_return(SstdParam &other)

Update the internal statistics with those included in another SstdParam instance. Other SstdParam is then updated to reflect new state.

Parameters:

other – [inout] The other SstdParam instance

void assign(const std::unordered_map<unsigned long, RunStats> &runstats)

Set the internal run statistics to match those included in the input map. Overwrite performed only for those keys in input.

Parameters:

runstats – The input map between global function index and statistics

inline RunStats &operator[](unsigned long id)

Get an element of the internal map.

Parameters:

id – The model index

inline const std::unordered_map<unsigned long, RunStats> &get_runstats() const

Get the internal map between model index and statistics.

virtual nlohmann::json get_algorithm_params(const unsigned long model_idx) const override

Get the algorithm parameters associated with a given model index.

virtual std::unordered_map<unsigned long, nlohmann::json> get_all_algorithm_params() const override

Get the algorithm parameters for all model indices. Returns a map of model index to JSON-formatted parameters. Parameter format is algorithm dependent.

virtual nlohmann::json serialize_json() const override

Serialize the set of algorithm parameters in JSON form for purpose of inter-run persistence, format may differ from the above.

virtual void deserialize_json(const nlohmann::json &from) override

De-serialize the set of algorithm parameters from JSON form created by serialize_json.

Public Static Functions

static std::string serialize_cerealpb(const std::unordered_map<unsigned long, RunStats> &runstats)

Convert a run statistics mapping into a Cereal portable binary representration.

Parameters:

The – run stats mapping

Returns:

Run statistics in string format

static void deserialize_cerealpb(const std::string &parameters, std::unordered_map<unsigned long, RunStats> &runstats)

Convert a run statistics Cereal portable binary representation string into a map.

Parameters:

  • parameters – [in] The parameter string

  • runstats – [out] The map between global function index and statistics

Protected Functions

inline std::unordered_map<unsigned long, RunStats> &access_runstats()

Get the internal map of model index to statistics.

Private Members

std::unordered_map<unsigned long, RunStats> m_runstats

Map of model index to statistics

Parameter Server

The parameter server runs on the head node and aggregates function anomaly and counter statistics for visualization. Aggregated statistics for function executions are also maintained and synchronized back to the AD instances such that the anomaly detection algorithm uses the most complete statistics to identify anomalies.

AnomalyStat

Warning

doxygenfile: Cannot find file “AnomalyStat.hpp

global_anomaly_stats

Warning

doxygenfile: Cannot find file “global_anomaly_stats.hpp

global_counter_stats

Warning

doxygenfile: Cannot find file “global_counter_stats.hpp

PSglobalFunctionIndexMap

namespace chimbuko
namespace modules
namespace performance_analysis
class PSglobalFunctionIndexMap
#include <PSglobalFunctionIndexMap.hpp>

A class that maintains a global mapping between function name and an index, which is to be synchronized over the nodes.

Public Functions

inline PSglobalFunctionIndexMap()

< Next unassigned index

unsigned long lookup(unsigned long pid, const std::string &func_name)

Lookup a function by name and return the index. A new index will be assigned if the function has not been encountered before.

Parameters:

  • pid – The program index

  • func_name – The function name

bool contains(unsigned long pid, const std::string &func_name) const

Check if the map contains the specified function.

Parameters:

  • pid – The program index

  • func_name – The function name

std::unordered_map<unsigned long, std::pair<unsigned long, std::string>> getFunctionIndexMap() const

Get a map between the function index and the pid /function name.

Returns:

A map of function index -> (program index, function name)

nlohmann::json serialize() const

Serialize the map to a JSON object.

void deserialize(const nlohmann::json &fmap)

Set the map to the contents of the JSON object.

Private Members

std::unordered_map<unsigned long, std::unordered_map<std::string, unsigned long>> m_fmap

The map between the program index and function name to the unique global index: [pid][func_name] -> fid

mutable std::mutex m_mutex
unsigned long m_idx
class NetPayloadGlobalFunctionIndexMap : public chimbuko::NetPayloadBase
#include <PSglobalFunctionIndexMap.hpp>

Net payload for communicating function index pserver->AD.

Public Functions

inline NetPayloadGlobalFunctionIndexMap(PSglobalFunctionIndexMap *idxmap)
inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

Private Members

PSglobalFunctionIndexMap *m_idxmap
class NetPayloadGlobalFunctionIndexMapBatched : public chimbuko::NetPayloadBase
#include <PSglobalFunctionIndexMap.hpp>

Net payload for communicating function index pserver->AD in batches.

Public Functions

inline NetPayloadGlobalFunctionIndexMapBatched(PSglobalFunctionIndexMap *idxmap)
inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

Private Members

PSglobalFunctionIndexMap *m_idxmap

PSProvenanceDBclient

Warning

doxygenfile: Cannot find file “PSProvenanceDBclient.hpp

PSstatSender

namespace chimbuko
struct PSstatSenderPayloadBase
#include <PSstatSender.hpp>

Base class for wrappers around objects/object pointers that return JSON objects that are sent to the parameter server.

The JSON objects are collected into a single object whose members are tagged according to the “tag” provided by the wrapper Nothing will be sent if the resulting JSON object is empty

Subclassed by chimbuko::PSstatSenderCreatedAtTimestampPayload, chimbuko::PSstatSenderVersionPayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalAnomalyMetricsCombinePayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalAnomalyMetricsPayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalAnomalyStatsCombinePayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalAnomalyStatsPayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalCounterStatsCombinePayload, chimbuko::modules::performance_analysis::PSstatSenderGlobalCounterStatsPayload

Public Functions

virtual void add_json(nlohmann::json &into) const = 0

Add the JSON object payload to ‘into’ as a new member with an appropriate tag (user should ensure no duplicate tags!)

inline virtual bool do_fetch() const

Whether to request a callback to process the response (optional)

Parameters:

  • packet – The string packet returned by the previous call to get_json()

  • returned – The string returned in response

inline virtual void process_callback(const std::string &packet, const std::string &returned) const

If a callback is requested, this function is called after it is returned.

inline virtual ~PSstatSenderPayloadBase()
struct PSstatSenderCreatedAtTimestampPayload : public chimbuko::PSstatSenderPayloadBase
#include <PSstatSender.hpp>

A payload to insert a “created_at” timestamp entry into the record.

Public Functions

virtual void add_json(nlohmann::json &into) const override

Add the timestamp into the ‘into’.

struct PSstatSenderVersionPayload : public chimbuko::PSstatSenderPayloadBase
#include <PSstatSender.hpp>

A payload to insert a “version” entry into the record.

Public Functions

virtual void add_json(nlohmann::json &into) const override

Add the version number into the ‘into’.

class PSstatSender
#include <PSstatSender.hpp>

A class that periodically sends aggregate statistics to the visualization module via curl using a background thread.

Public Functions

PSstatSender(size_t send_freq = 1000)

Constructpr.

Parameters:

send_freq – The frequency (in milliseconds) at which sends are performed to the viz module

~PSstatSender()
inline void set_send_freq(const size_t freq)

Change the frequency (in milliseconds) at which sends are performed to the viz module. Must be set prior to calling run_stat_sender.

void run_stat_sender(const std::string &url, const std::string &stat_save_dir = "")

Start sending global anomaly stats to the visualization module (curl)

Parameters:

  • url – The URL of the visualization module

  • stat_save_dir – Optionally output the stats to disk in this directory alongside/instead of to the viz module

void stop_stat_sender(int wait_msec = 0)

Stop sending global anomaly stats to the visualization module (curl)

inline void add_payload(PSstatSenderPayloadBase *payload)

Add a payload. Takes ownership of pointer, which is freed.

inline bool bad() const

If an exception is caught in the thread loop, the thread will stop issuing sends and set this bool to true.

Private Members

size_t m_send_freq

Number of seconds between sends to viz

std::thread *m_stat_sender
std::atomic_bool m_stop_sender
std::atomic_bool m_bad

If an exception is caught in the thread loop, the thread will stop issuing sends and set this bool to true

std::vector<PSstatSenderPayloadBase*> m_payloads

Vector of payload wrappers defining the sets of data sent to the parameter server

Network

The network is the communication pathway between the AD instances and the parameter server. The default implementation, ZMQnet uses zeroMQ, and a deprecated interface via MPI is also provided and can be selected at compile time.

NetInterface

namespace chimbuko

Enums

enum class NetThreadLevel

enum network thread level (for MPI)

Values:

enumerator THREAD_MULTIPLE
class NetPayloadBase

Subclassed by chimbuko::NetPayloadGetParams, chimbuko::NetPayloadGetParamsFromManager, chimbuko::NetPayloadHandShake, chimbuko::NetPayloadPing, chimbuko::NetPayloadUpdateParamManager, chimbuko::NetPayloadUpdateParams, chimbuko::modules::performance_analysis::NetPayloadGlobalFunctionIndexMap, chimbuko::modules::performance_analysis::NetPayloadGlobalFunctionIndexMapBatched, chimbuko::modules::performance_analysis::NetPayloadRecvCombinedADdata, chimbuko::modules::performance_analysis::NetPayloadRecvCombinedADdataArray, chimbuko::modules::performance_analysis::NetPayloadUpdateAnomalyMetrics, chimbuko::modules::performance_analysis::NetPayloadUpdateAnomalyStats, chimbuko::modules::performance_analysis::NetPayloadUpdateCounterStats

Public Functions

virtual int kind() const = 0

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

virtual MessageType type() const = 0

The message type to which the payload is to be bound.

virtual void action(Message &response, const Message &message) = 0

Act on the message and formulate a response.

inline void check(const Message &msg) const

Helper function to ensure the message is of the correct kind/type.

inline virtual ~NetPayloadBase()
class NetPayloadHandShake : public chimbuko::NetPayloadBase
#include <net.hpp>

Default handshake response; this is bound automatically to the network.

Public Functions

inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

inline virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

class NetPayloadPing : public chimbuko::NetPayloadBase
#include <net.hpp>

Ping command.

Public Functions

inline virtual int kind() const override

The message kind to which the payload is to be bound.

Chimbuko core reserves range -1…-infty, modules must use range 0..+infty

inline virtual MessageType type() const override

The message type to which the payload is to be bound.

inline virtual void action(Message &response, const Message &message) override

Act on the message and formulate a response.

class NetInterface
#include <net.hpp>

Network interface class.

Subclassed by chimbuko::LocalNet, chimbuko::ZMQMENet, chimbuko::ZMQNet

Public Types

typedef std::unordered_map<int, std::unordered_map<MessageType, std::unique_ptr<NetPayloadBase>>> PayloadMapType

Map of message kind/type to payloads

typedef std::unordered_map<int, PayloadMapType> WorkerPayloadMapType

Map of worker index and message type to payloads

Public Functions

NetInterface()

Construct a new Net Interface object.

virtual ~NetInterface()

Destroy the Net Interface object.

virtual void init(int *argc = nullptr, char ***argv = nullptr, int nt = 1) = 0

(virtual) initialize network interface

Parameters:

  • argc – command line argc

  • argv – command line argv

  • nt – the number of threads for a thread pool

virtual void finalize() = 0

(virtual) finalize network

virtual void run() = 0

(virtual) Run network server

virtual void stop() = 0

(virtual) stop network server

virtual std::string name() const = 0

(virtual) name of network server

Returns:

std::string name of network server

void add_payload(NetPayloadBase *payload, int worker_idx = 0)

Add a payload to the receiver bound to particular message kind/type specified internally.

Assumes ownership of the NetPayloadBase object and deletes in constructor worker_idx: ZMQNet - worker_idx corresponds to the worker thread. Payloads must be assigned to each thread MPINet - use 0 always ZMQMENet - worker_idx corresponds to the endpoint thread

Parameters:

  • payload – The payload

  • worker_idx – The worker index to which the payload is bound (implementation defined, see below)

void list_payloads(std::ostream &os) const

Print information on the payloads.

Public Static Functions

static void find_and_perform_action(int worker_id, Message &msg_reply, const Message &msg, const WorkerPayloadMapType &payloads)

Find the action associated with the given worker_id and message type and perform the action.

Parameters:

  • worker_id – The worker index

  • msg_reply – The reply message

  • msg – The input message

  • payloads – The map of worker/message type to payload

static void find_and_perform_action(Message &msg_reply, const Message &msg, const PayloadMapType &payloads)

Find the action associated with the given message type and perform the action.

Parameters:

  • msg_reply – The reply message

  • msg – The input message

  • payloads – The map of worker/message type to payload

Protected Functions

virtual void init_thread_pool(int nt) = 0

initialize thread pool

Parameters:

nt – the number threads in the pool

Protected Attributes

int m_nt

The number of threads in the pool

WorkerPayloadMapType m_payloads

Map of worker index (implementation defined), message kind and message type to a payload

namespace DefaultNetInterface

Functions

NetInterface &get()

get default network interface for easy usages

Returns:

NetInterface& default network

MPINet

ZMQNet

namespace chimbuko
class ZMQNet : public chimbuko::NetInterface
#include <zmq_net.hpp>

A network interface using ZeroMQ.

Public Types

enum class Status

Values:

enumerator NotStarted
enumerator StartingUp
enumerator Running
enumerator ShuttingDown
enumerator StoppedByRequest
enumerator StoppedBySignal
enumerator StoppedByTimeOut
enumerator StoppedByError
enumerator StoppedAutomatically

Public Functions

ZMQNet()
~ZMQNet()
virtual void init(int *argc, char ***argv, int nt) override

(virtual) initialize network interface

Parameters:

  • argc – command line argc

  • argv – command line argv

  • nt – the number of threads for a thread pool

virtual void finalize() override

Finalize network.

virtual void run() override

(virtual) Run network server

virtual void stop() override

Stop network server.

inline virtual std::string name() const override

Name of network server.

Returns:

std::string name of network server

inline void setMaxMsgPerPollCycle(const int max_msg)

Set the maximum number of messages that the router thread will route front->back and back->front per poll cycle.

inline void setIOthreads(const int nt)

Set the number of IO threads used by ZeroMQ (default 1). Must be called prior to init(…)

inline void setPort(const int port)

Set the port upon which the connection is made. Must be called prior to run(..). Default 5559.

inline void setAutoShutdown(const bool to)

Set the rule for automatic shutdown once all clients have disconnected (default true)

inline void setTimeOut(const long time_ms)

Set the timeout on polling for client requests or responses from worker threads (-1 = no timeout [default])

inline Status getStatus() const

Query the status of the network endpoint (presumably from another thread)

Public Static Functions

static int send(void *socket, const std::string &strmsg)

Send the data packet to the server on the provided socket.

static int recv(void *socket, std::string &strmsg)

Receive the data packet to the server from the provided socket.

Protected Functions

virtual void init_thread_pool(int nt) override

initialize thread pool

Parameters:

nt – the number threads in the pool

Private Functions

int recvAndSend(void *skFrom, void *skTo, int max_msg)

Route a message to/from worker thread pool.

Parameters:

  • skFrom – ZMQ origin socket

  • skTo – ZMQ destination socket

  • max_msg – The maximum number of messages this function will attempt to drain from the queue (including disconnect message)

Returns:

the number of messages routed

Private Members

void *m_context

ZeroMQ context pointer

long long m_n_requests

Accumulated number of RPC requests

std::vector<std::thread> m_threads

The pool of thread workers

PerfStats m_perf

Performance monitoring

std::vector<PerfStats> m_perf_thr

Performance monitoring for worker threads; will be combined with m_perf before write

mutable std::vector<std::mutex> m_thr_mutex

Mutexes for locking between main thread and individual worker threads

int m_max_pollcyc_msg

Maximum number of front->back and back->front messages that will be routed per poll cycle. Too many and we risk starving a socket, too few and might hit perf issues

int m_io_threads

Set the number of IO threads used by ZeroMQ (default 1)

mutable std::mutex m_mutex
int m_clients

Number of connected clients

bool m_client_has_connected

At least one client has connected previously

int m_port

The port upon which the net connects

bool m_autoshutdown

The network will shutdown once all clients have disconnected

Status m_status

Monitoring of status

long m_poll_timeout

The timeout (in ms) after which on no activity the network with shutdown (default -1: infinite)

bool m_remote_stop_cmd

Registration of requests for server to stop issued by clients

ZMQMENet

namespace chimbuko
class ZMQMENet : public chimbuko::NetInterface
#include <zmqme_net.hpp>

A multi-endpoint, multi-threaded interface using ZeroMQ.

Public Functions

ZMQMENet()
~ZMQMENet()
virtual void init(int *argc, char ***argv, int nt) override

(virtual) initialize network interface

Parameters:

  • argc – command line argc

  • argv – command line argv

  • nt – the number of endpoint threads

virtual void finalize() override

Finalize network; blocking wait for worker threads to finish.

virtual void run() override

(virtual) Run network server

virtual void stop() override

Stop network server.

inline virtual std::string name() const override

Name of network server.

Returns:

std::string name of network server

inline void setBasePort(const int port)

Set the base port upon which the connection is made (thread ports are offset by thread index). Must be called prior to run(..). Default 5559.

Public Static Functions

static int recv_NB(void *socket, std::string &strmsg)

Receive the data packet to the server from the provided socket with a non-blocking receive.

Returns:

-1 if no messages on the queue, otherwise the byte size of the message

Protected Functions

virtual void init_thread_pool(int nt) override

initialize thread pool

Parameters:

nt – the number threads in the pool

Private Members

int m_base_port

Port of first endpoint

int m_nthread

Number of endpoint threads

std::vector<std::thread> m_threads

The pool of thread workers

PerfStats m_perf

Performance monitoring

std::vector<PerfStats> m_perf_thr

Performance monitoring for worker threads; will be combined with m_perf before write

std::vector<int> m_clients_thr

Tracker of number of connected clients, used to determine when a thread exits

std::vector<int> m_client_has_connected

Has a client previously connected to this worker?

bool m_finalized

Has previously been finalized

Message

namespace chimbuko

Enums

enum MessageType

Enum of the message “type” or action.

Values:

enumerator REQ_ADD
enumerator REQ_GET
enumerator REQ_CMD
enumerator REQ_QUIT
enumerator REQ_ECHO
enumerator REP_ADD
enumerator REP_GET
enumerator REP_CMD
enumerator REP_QUIT
enumerator REP_ECHO
enum BuiltinMessageKind

Enum of the message “kind” describing the context of the action for builtin actions.

NOTE: Builtin actions will reserve the range -1 .. -infty for values; modules must use range 0…+infty for defined functionality

Values:

enumerator DEFAULT
enumerator CMD
enumerator PARAMETERS
enum MessageCmd

Values:

enumerator QUIT
enumerator ECHO

Functions

std::string toString(const MessageType m)
std::string toString(const BuiltinMessageKind m)
std::string toString(const MessageCmd m)
class Message
#include <message.hpp>

A class containing a message and header that can be serialized in JSON form for communication.

Public Functions

inline Message()

Construct a new Message object.

inline ~Message()

Destroy the Message object.

void set_info(int src, int dst, int type, int kind, int frame = 0, int size = 0)

Set the message information (header)

Parameters:

  • src – source rank

  • dst – destination rank

  • type – message type

  • kind – message kind

  • frame – frame index

  • size – message size

std::string serializeMessage() const

Return the message in string serialized form.

void deserializeMessage(const std::string &from)

Unpack the string into this object, setting the header and content as appropriate.

void setContent(const std::string &to)

Set the message contents.

inline const std::string &getContent() const

Return the message contents as a string.

inline int src() const

Get the origin rank.

inline int dst() const

Get the destination rank.

inline int type() const

Get the message type.

inline int kind() const

Get the message kind.

inline int size() const

Get the message size in bytes.

inline int frame() const

Get the message io frame (step)

inline void clear()

clear data buffer

Message createReply() const

Create a message reply with the source, destination, type and kind appropriately filled.

inline void show(std::ostream &os) const

Write the message to the output stream in JSON form.

template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal.

Private Members

Header m_head

Message header

std::string m_buf

Message content

class Header

Public Functions

inline Header()

header size in bytes

inline int &src()

source rank

Returns:

int& reference to the source rank

inline int src() const
inline int &dst()

desination rank

Returns:

int& reference to the destination rank

inline int dst() const
inline int &type()

message type

Returns:

int& reference to the message type

inline int type() const
inline int &kind()

message kind

Returns:

int& reference to the message kind

inline int kind() const
inline int &size()

message size

Returns:

int& reference to the message size

inline int size() const
inline int &frame()

message frame index

Returns:

int& reference to the message frame index

inline int frame() const
nlohmann::json get_json() const
void set_header(const nlohmann::json &j)
void set_header(const std::string &s)
template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal.

Private Members

int m_h[8]

header information

0: src rank 1: dst rank 2: message type 3: message kind 4: message size (except header) in bytes 5: frame index (or step index) 6: reserved 7: reserved

Utils

Utility functions and classes.

ADIOS2parseUtils

namespace chimbuko

Functions

std::ostream &operator<<(std::ostream &os, const mapPrint &mp)

ostream output of a map using mapPrint wrapper

template<typename T>
std::ostream &operator<<(std::ostream &os, const vecPrint<T> &mp)

ostream output of a vector using vecPrint wrapper

varBase *parseVariable(const std::string &name, const std::map<std::string, std::string> &varinfo, adios2::IO &io, adios2::Engine &eng)

A factory for generating varBase derived class instances that contain the data read from the input stream.

Returns a NULL ptr if the type is not supported The name/varinfo data can be obtained using the adios2::IO::AvailableVariables method

struct mapPrint
#include <ADIOS2parseUtils.hpp>

Wrapper allowing ostream output of a string map object.

Public Functions

inline mapPrint(const std::map<std::string, std::string> &mp)

Public Members

const std::map<std::string, std::string> &mp
template<typename T>
struct vecPrint
#include <ADIOS2parseUtils.hpp>

Wrapper allowing ostream output of a vector object.

Public Functions

inline vecPrint(const std::vector<T> &mp)

Public Members

const std::vector<T> &mp
struct varBase
#include <ADIOS2parseUtils.hpp>

Abstract interface for an object that reads, stores and outputs data or arrays of data from ADIOS2 streams.

Subclassed by chimbuko::varPOD< T >, chimbuko::varTensor< T >

Public Functions

inline varBase(const std::string &name)

Construct object with variable name ‘name’.

inline virtual std::string value() const

Get the value as a human-readable string.

inline virtual void get(adios2::IO &io, adios2::Engine &eng)

Read the variable from the ADIOS2 stream.

inline virtual void put(adios2::IO &io, adios2::Engine &eng)

Write the variable to the ADIOS2 stream.

inline virtual ~varBase()

Public Members

std::string name
template<typename T>
class varPOD : public chimbuko::varBase
#include <ADIOS2parseUtils.hpp>

Capture POD (single-value) data.

Public Functions

inline varPOD(const std::string &name)
inline varPOD(const std::string &name, adios2::IO &io, adios2::Engine &eng)
inline virtual void get(adios2::IO &io, adios2::Engine &eng)

Read the variable from the ADIOS2 stream.

inline virtual void put(adios2::IO &io, adios2::Engine &eng)

Write the variable to the ADIOS2 stream.

inline virtual std::string value() const

Get the value as a human-readable string.

Private Members

T val
template<typename T>
class varTensor : public chimbuko::varBase
#include <ADIOS2parseUtils.hpp>

Capture multi-dimensional tensor data.

Public Functions

inline varTensor(const std::string &name)
inline varTensor(const std::string &name, const std::vector<unsigned long> &shape, adios2::IO &io, adios2::Engine &eng)
inline virtual void get(adios2::IO &io, adios2::Engine &eng)

Read the variable from the ADIOS2 stream.

inline virtual void put(adios2::IO &io, adios2::Engine &eng)

Write the variable to the ADIOS2 stream.

inline virtual std::string value() const

Get the value as a human-readable string.

inline T &operator()(const std::vector<unsigned long> &coord)

Get the value at given coordinate (non-const)

inline const T &operator()(const std::vector<unsigned long> &coord) const

Get the value at given coordinate (const)

inline const std::vector<unsigned long> &getShape() const

Get the shape of the tensor.

Private Functions

template<typename listType>
inline size_t map(const listType &c) const

Compute the lexicographic offset for coordinate ‘c’ assuming row-major order.

inline void unmap(std::vector<unsigned long> &c, size_t o) const

Unmap an offset into a coordinate.

Private Members

std::vector<unsigned long> shape

The “shape” of the tensor

std::vector<T> val

Anomalies

Warning

doxygenfile: Cannot find file “Anomalies.hpp

barrier

namespace chimbuko
class Barrier
#include <barrier.hpp>

Thread barrier.

Public Functions

inline explicit Barrier(std::size_t iCount)

Constructor.

Parameters:

iCount – The number of threads in the barrier

inline void wait()

Wait for all threads to reach the barrier.

Private Members

std::mutex mMutex
std::condition_variable mCond
std::size_t mThreshold
std::size_t mCount
std::size_t mGeneration

commandLineParser

Defines

_WRP_P_0(PARENT, CHILD)

Macros for generating the structure list needed for addOptionalArgMultiArg.

_WRP_P_1(PARENT, CHILD)
_WRP_P_2(PARENT, CHILD, ...)
_WRP_P_3(PARENT, CHILD, ...)
_WRP_P_4(PARENT, CHILD, ...)
_WRP_P_5(PARENT, CHILD, ...)
_WRP_P_GET_MACRO(_0, _1, _2, _3, _4, _5, NAME, ...)
WRAP_PARENT(PARENT, ...)
addOptionalCommandLineArg(PARSER, PARENT, NAME, HELP_STR)

Helper macro to add an optional command line arg to the parser PARSER for member with given name NAME, PARENT struct instance, and help string HELP_STR. Option enabled by “-NAME” on command line.

addOptionalCommandLineArgWithDefault(PARSER, PARENT, NAME, DEFAULT, HELP_STR)

Helper macro to add an optional command line arg to the parser PARSER for member with given name NAME default value DEFAULT, PARENT struct instance, and help string HELP_STR. Option enabled by “-NAME” on command line.

addOptionalCommandLineArgDefaultHelpString(PARSER, PARENT, NAME)

Helper macro to add an optional command line arg to the parser PARSER for member with given name NAME, PARENT struct instance, and default help string “Provide the value for NAME”.

addOptionalCommandLineArgWithFlag(PARSER, PARENT, NAME, FLAGNAME, HELP_STR)

Helper macro to add an optional command line arg to the parser PARSER for member with given name NAME and flag with FLAGNAME both belonging to PARENT struct instance, and help string HELP_STR. Option enabled by “-NAME” on command line. FLAGNAME will be set true if parsed.

addOptionalCommandLineArgMultiValue(PARSER, PARENT, ARG_NAME, HELP_STR, ...)

Helper macro to add an optional command line arg to the parser PARSER with argument name -${ARG_NAME} which sets multiple variables.

Macro supports up to 5 members

Example usage: addOptionalCommandLineArgMultiValue(parser_instance, struct_instance, set_2vals, “the help”, a, b) called with -set_2vals 1 2 will set structure_instance members a and b to 1 and 2, respectively

addOptionalCommandLineArgOptArg(PARSER, PARENT, NAME, OPT_ARG, HELP_STR)

Helper macro to add an optional command line arg to the parser PARSER with given member name NAME, PARENT struct instance, and help string HELP_STR. Option enabled by “-OPT_ARG” on command line.

addOptionalCommandLineArgOptArgWithDefault(PARSER, PARENT, NAME, OPT_ARG, DEFAULT, HELP_STR)

Helper macro to add an optional command line arg to the parser PARSER with given member name NAME, default value DEFAULT, PARENT struct instance, and help string HELP_STR. Option enabled by “-OPT_ARG” on command line.

addMandatoryCommandLineArg(PARSER, PARENT, NAME, HELP_STR)

Helper macro to add a mandatory command line arg to the parser PARSER with given member name NAME, PARENT struct instance, and help string HELP_STR.

addMandatoryCommandLineArgDefaultHelpString(PARSER, PARENT, NAME)

Helper macro to add an optional command line arg to the parser PARSER with given member name NAME, PARENT struct instance, and default help string “Provide the value for NAME”.

namespace chimbuko
template<class T, class R>
struct get_member_ptr_class<R T::*>

Public Types

using type = T
template<class T, class R>
struct get_member_ptr_data_type<R T::*>

Public Types

using type = R
class optionalCommandLineArgBase
#include <commandLineParser.hpp>

Base class for optional arg parsing structs.

Subclassed by chimbuko::ADOutlier::AlgoParams::cmdlineParser, chimbuko::optionalCommandLineArg< MemberType >, chimbuko::optionalCommandLineArgMultiValue< MemberTypes >, chimbuko::optionalCommandLineArgWithFlag< MemberType >

Public Functions

virtual int parse(const std::string &arg, const char **vals, const int vals_size) = 0

If the first string matches the internal arg string (eg “-help”), a number of strings are consumed from the array ‘vals’ and that number returned. A value of -1 indicates the argument did not match.

Parameters:

  • vals – An array of strings

  • vals_size – The length of the string array

virtual void help(std::ostream &os) const = 0

Print the help string for this argument to the ostream.

inline virtual ~optionalCommandLineArgBase()
template<typename MemberType>
class optionalCommandLineArg : public chimbuko::optionalCommandLineArgBase
#include <commandLineParser.hpp>

A class that parses an argument of a given type into the struct.

Public Functions

inline optionalCommandLineArg(MemberType &member, const std::string &arg, const std::string &help_str)

Create an instance with the provided argument and help string.

inline virtual int parse(const std::string &arg, const char **vals, const int vals_size) override

If the first string matches the internal arg string (eg “-help”), a number of strings are consumed from the array ‘vals’ and that number returned. A value of -1 indicates the argument did not match.

Parameters:

  • vals – An array of strings

  • vals_size – The length of the string array

inline virtual void help(std::ostream &os) const override

Print the help string for this argument to the ostream.

Private Members

std::string m_arg

The argument, format “-a”

std::string m_help_str

The help string

MemberType &member
template<typename MemberType>
class optionalCommandLineArgWithFlag : public chimbuko::optionalCommandLineArgBase
#include <commandLineParser.hpp>

A class that parses an argument of a given type into the struct and sets a bool flag argument to true.

Public Functions

inline optionalCommandLineArgWithFlag(MemberType &member, bool &flag, const std::string &arg, const std::string &help_str)

Create an instance with the provided argument and help string.

inline virtual int parse(const std::string &arg, const char **vals, const int vals_size) override

If the first string matches the internal arg string (eg “-help”), a number of strings are consumed from the array ‘vals’ and that number returned. A value of -1 indicates the argument did not match.

Parameters:

  • vals – An array of strings

  • vals_size – The length of the string array

inline virtual void help(std::ostream &os) const override

Print the help string for this argument to the ostream.

Private Members

std::string m_arg

The argument, format “-a”

std::string m_help_str

The help string

MemberType &member
bool &flag
template<typename MemberType, class ...RemainingMemberTypes>
struct optionalCommandLineArgMultiValue_parse
#include <commandLineParser.hpp>

Recursive template class for parsing multiple values.

Public Functions

inline optionalCommandLineArgMultiValue_parse(MemberType &member, RemainingMemberTypes&... rem)
inline void parse(const char **vals)

Public Members

MemberType &member
template<typename MemberType>
struct optionalCommandLineArgMultiValue_parse<MemberType>

Public Functions

inline optionalCommandLineArgMultiValue_parse(MemberType &member)
inline void parse(const char **vals)

Public Members

MemberType &member
template<class ...MemberTypes>
class optionalCommandLineArgMultiValue : public chimbuko::optionalCommandLineArgBase
#include <commandLineParser.hpp>

A class that parses an argument of a given type into the struct with multiple values.

Public Functions

inline optionalCommandLineArgMultiValue(MemberTypes&... members, const std::string &arg, const std::string &help_str)

Create an instance with the provided argument and help string.

inline virtual int parse(const std::string &arg, const char **vals, const int vals_size) override

If the first string matches the internal arg string (eg “-help”), a number of strings are consumed from the array ‘vals’ and that number returned. A value of -1 indicates the argument did not match.

Parameters:

  • vals – An array of strings

  • vals_size – The length of the string array

inline virtual void help(std::ostream &os) const override

Print the help string for this argument to the ostream.

Public Static Attributes

static constexpr int NValues = std::tuple_size<std::tuple<MemberTypes...>>::value

Private Members

std::string m_arg

The argument, format “-a”

std::string m_help_str

The help string

optionalCommandLineArgMultiValue_parse<MemberTypes...> pp
class mandatoryCommandLineArgBase
#include <commandLineParser.hpp>

Base class for mandatory arg parsing structs.

Subclassed by chimbuko::mandatoryCommandLineArg< MemberType >

Public Functions

virtual bool parse(const std::string &val) = 0

Parse the value into the struct. Return false val is unable to be parsed.

virtual void help(std::ostream &os) const = 0

Print the help string for this argument to the ostream.

inline virtual ~mandatoryCommandLineArgBase()
template<typename MemberType>
class mandatoryCommandLineArg : public chimbuko::mandatoryCommandLineArgBase
#include <commandLineParser.hpp>

A class that parses an argument of a given type into the struct.

Public Functions

inline mandatoryCommandLineArg(MemberType &member, const std::string &help_str)

Create an instance with the provided argument and help string.

inline virtual bool parse(const std::string &val) override

Parse the value into the struct. Return false val is unable to be parsed.

inline virtual void help(std::ostream &os) const override

Print the help string for this argument to the ostream.

Private Members

std::string m_help_str

The help string

MemberType &member
class commandLineParser
#include <commandLineParser.hpp>

The main parser class for a generic struct ArgsStruct.

Public Functions

inline void addOptionalArg(optionalCommandLineArgBase *arg_parser)

Add an optional argument parser object. Assumes ownership of pointer.

template<typename MemberType>
inline void addOptionalArg(MemberType &member, const std::string &arg, const std::string &help_str)

Add an optional argument bound to the given member object with provided argument (eg “-a”) and help string.

template<typename MemberType>
inline void addOptionalArgWithFlag(MemberType &member, bool &flag, const std::string &arg, const std::string &help_str)

Add an optional argument bound to the given member object and a bool flag, with provided argument (eg “-a”) and help string.

template<class ...MemberTypes>
inline void addOptionalArgMultiValue(const std::string &arg, const std::string &help_str, MemberTypes&... members)

Add an optional argument that has multiple associated values.

template<typename MemberType>
inline void addMandatoryArg(MemberType &member, const std::string &help_str)

Add an mandatory argument with the given type, member pointer (eg &ArgsStruct::a) and help string.

inline size_t nMandatoryArgs() const

Get the number of mandatory arguments.

inline void parse(const int narg, const char **args)

Parse an array of strings of length ‘narg’ into the structure.

Parsing will commence with first entry of args

inline void parseCmdLineArgs(int argc, char **argv)

Parse the command line arguments into the structure.

Parsing will commence with second entry of argv

inline void help(std::ostream &os = std::cout) const

Print the help information for all the args that can be parsed.

Private Members

std::vector<std::unique_ptr<mandatoryCommandLineArgBase>> m_man_args

Container for the individual mandatory arg parsers

std::vector<std::unique_ptr<optionalCommandLineArgBase>> m_opt_args

Container for the individual optional arg parsers

DispatchQueue

namespace chimbuko
class DispatchQueue
#include <DispatchQueue.hpp>

A class for dispatching work items over a thread pool.

Public Functions

DispatchQueue(std::string name, size_t thread_cnt = 1)

Construct an instance of class, providing a name for the instance and the number of threads.

Parameters:

  • name – The name of the instance

  • thread_cnt – The number of threads (default 1)

~DispatchQueue()
void dispatch(const fp_t &op)

Enqueue a work item (lvalue reference)

Parameters:

op – An instance of std::function<void(void)>

void dispatch(fp_t &&op)

Enqueue a work item (rvalue reference)

Parameters:

op – An instance of std::function<void(void)>

size_t size()

Return the number of outstanding work items in the queue.

Private Types

typedef std::function<void(void)> fp_t

Private Functions

void thread_handler(void)

Private Members

std::string m_name
std::mutex m_lock
std::vector<std::thread> m_threads
std::queue<fp_t> m_q
std::condition_variable m_cv
bool m_quit

error

Defines

recoverable_error(MSG)

Signal a recoverable error.

fatal_error(MSG)

Signal a fatal error.

namespace chimbuko

Functions

ErrorWriter &Error()

The global error writer instance.

void writeErrorTerminateHandler()

For fatal errors we delay writing the error to the output stream in case it is caught. This terminate handler ensures it is written.

After flushing the error the handler calls the terminateHandlerAbortAction above

void set_error_output_stream(const int rank, std::ostream *strm = &std::cerr)

Set the error output of the global error writer to a stream and specify the rank.

void set_error_output_file(const int rank, const std::string &file_stub = "ad_error")

Set the error output of the global error writer to a file and specify the rank.

Parameters:

file_stub – The file name “stub”. The actual filename will be ${file_stub}.${rank}

void stacktrace(std::ostream &out, unsigned int max_frames = 63)

Print a stack trace.

struct ErrorWriter
#include <error.hpp>

A class for writing out errors to an output stream.

Public Functions

ErrorWriter()
inline void setRank(const int rank)

Set the MPI rank. This will add the rank to the error output.

inline void setStream(std::ostream *strm)

Set the output stream.

void recoverable(const std::string &msg, const std::string &func, const std::string &file, const unsigned long line)

Signal a recoverable error.

void fatal(const std::string &msg, const std::string &func, const std::string &file, const unsigned long line)

Signal a fatal error. Not written to output stream unless either uncaught (which will also call abort) or manually flushed.

void flushError(std::exception_ptr e)

Manually flush an exception to the output stream.

void flushError(const std::exception &e)

Private Functions

std::string getErrStr(const std::string &type, const std::string &msg, const std::string &func, const std::string &file, const unsigned long line) const

Private Members

int m_rank
std::ostream *m_ostream
std::mutex m_mutex

hash

namespace chimbuko
template<typename T, size_t N>
struct ArrayHasher
#include <hash.hpp>

Hash function for std::array.

Public Functions

inline std::size_t operator()(const std::array<T, N> &a) const

map

namespace chimbuko

Typedefs

template<typename T>
using mapPRT = std::unordered_map<unsigned long, std::unordered_map<unsigned long, std::unordered_map<unsigned long, T>>>

Define a mapping of process/rank/thread to a data type.

Functions

template<typename T>
T *getElemPRT(const unsigned long pid, const unsigned long rid, const unsigned long tid, std::unordered_map<unsigned long, std::unordered_map<unsigned long, std::unordered_map<unsigned long, T>>> &map)

Get an element from the commonly-occuring triple-depth map of process/rank/thread to element (non-const)

Parameters:

  • pid – The process index

  • rid – The rank index

  • tid – The thread index

  • map – The map

Returns:

A pointer to the element if it exists, nullptr otherwise

template<typename T>
T const *getElemPRT(const unsigned long pid, const unsigned long rid, const unsigned long tid, const std::unordered_map<unsigned long, std::unordered_map<unsigned long, std::unordered_map<unsigned long, T>>> &map)

Get an element from the commonly-occuring triple-depth map of process/rank/thread to element (const)

Parameters:

  • pid – The process index

  • rid – The rank index

  • tid – The thread index

  • map – The map

Returns:

A pointer to the element if it exists, nullptr otherwise

template<typename T>
std::unordered_map<unsigned long, T> *getMapPR(const unsigned long pid, const unsigned long rid, std::unordered_map<unsigned long, std::unordered_map<unsigned long, std::unordered_map<unsigned long, T>>> &map)

Get the map between thread and element from the commonly-occuring triple-depth map of process/rank/thread to element (non-const)

Parameters:

  • pid – The process index

  • rid – The rank index

  • map – The map

Returns:

A pointer to the map element if it exists, nullptr otherwise

template<typename T>
std::unordered_map<unsigned long, T> const *getMapPR(const unsigned long pid, const unsigned long rid, const std::unordered_map<unsigned long, std::unordered_map<unsigned long, std::unordered_map<unsigned long, T>>> &map)

Get the map between thread and element from the commonly-occuring triple-depth map of process/rank/thread to element (const)

Parameters:

  • pid – The process index

  • rid – The rank index

  • map – The map

Returns:

A pointer to the map element if it exists, nullptr otherwise

template<typename T>
void unordered_map_plus_equals(T &into, const T &from)

For nested std::unordered_map instances, recursively merge using operator+= for the underlying elements, copying data where appropriate for keys not present in the output.

template<typename T>
struct _plus_equals
#include <map.hpp>

Implementation of recursive += for unordered map.

Public Static Functions

static inline void doit(T &into, const T &from)
template<typename KeyType, typename ValueType>
struct _plus_equals<std::unordered_map<KeyType, ValueType>>

Public Static Functions

static inline void doit(std::unordered_map<KeyType, ValueType> &into, const std::unordered_map<KeyType, ValueType> &from)

memutils

namespace chimbuko

Functions

size_t getMemPageSize()

Get the memory page size in bytes.

void getMemUsage(size_t &vm_total, size_t &vm_resident)

Get the memory usage in kB.

Parameters:

  • vm_total – Total virtual memory usage (resident + disk)

  • vm_resident – Total resident (physical) memory usage

mtQueue

template<typename T>
class mtQueue
#include <mtQueue.hpp>

A multi-threaded wrapper around FIFO queue (std::queue)

Public Functions

inline mtQueue()
inline ~mtQueue()
inline bool tryPop(T &out)

Try to obtain a value from the front of the queue.

Parameters:

out – [out] The value

Returns:

True if the value is populated, false if the queue is invalid or the queue is empty

inline bool waitPop(T &out)

Wait until the queue either has an entry or is invalidated. Value taken from front of queue.

Parameters:

out – [out] The value

Returns:

True if queue is valid, false otherwise

inline void push(T value)

Push a new value onto the end of the queue.

inline bool empty() const

Return true if the queue is empty.

inline void clear()

Remove all entries from the queue.

inline void invalidate()

Mark the queue as invalid.

inline bool is_valid() const

Check if the queue has been invalidated

inline size_t size() const

The number of entries in the queue.

Private Members

std::atomic_bool m_valid = {true}
mutable std::mutex m_mutex
std::queue<T> m_queue
std::condition_variable m_cond

PerfStats

namespace chimbuko
class PerfTimer
#include <PerfStats.hpp>

A timer class that only measures time if _PERF_METRIC compile flag is set.

Public Functions

PerfTimer(bool start_now = true)
void start()

(Re)start the timer

void pause()

Pause the timer.

void unpause()

Unpause the timer.

This is the same as start but it does not zero the accumulated time from previous active periods

double elapsed_us() const

Compute the elapsed time in microseconds since start/unpause plus accumulated time from previoud active periods.

double elapsed_ms() const

Compute the elapsed time in milliconds since start/unpause plus accumulated time from previoud active periods.

class PerfStats
#include <PerfStats.hpp>

A class that maintains performance statistics of various aspects of the AD module It’s constituent functions only do anything if _PERF_METRIC flag enabled.

Public Functions

PerfStats()

Construct with empty path and filename (no output will be written unless these are set)

PerfStats(const std::string &output_path, const std::string &filename)
void add(const std::string &label, const double value)
void setWriteLocation(const std::string &output_path, const std::string &filename)

Set the output path and file name.

void write() const

Write the running statistics to the file. Only writes out if a path and filename have been provided.

void write(std::ostream &os) const

Write the running statistics to a stream.

PerfStats &operator+=(const PerfStats &r)

Combine the statistics with another.

inline void clear()

Clear the metrics state.

class PerfPeriodic
#include <PerfStats.hpp>

A class for storing and writing periodic data, eg memory usage, outstanding provDB requests. It stores and writes only if _PERF_METRIC is active, otherwise it does nothing.

Public Functions

PerfPeriodic()

Construct with empty path and filename (no output will be written unless these are set)

PerfPeriodic(const std::string &output_path, const std::string &filename)
template<typename T>
inline void add(const std::string &label, const T &value)
inline void add(const std::string &label, const std::string &value)
void setWriteLocation(const std::string &output_path, const std::string &filename)

Set the output path and file name.

void write()

Write the running statistics to the file. Only writes out if a path and filename have been provided. After writing, stored values are purged.

RunMetric

namespace chimbuko
class RunMetric
#include <RunMetric.hpp>

A class containing a map of a string to its aggregated statistics, used for performance logging.

Public Functions

inline RunMetric()
inline ~RunMetric()
inline void add(std::string name, double val)

Add a value to the statistics tagged by the provided name.

A new entry in the map is created if the name has not been provided previously

inline void dump(std::string path, std::string filename = "metric.json") const

Write the data to disk in JSON form.

inline void dump(std::ostream &os) const

Write the data to a stream.

inline RunMetric &operator+=(const RunMetric &r)

Combine this instance with another Does not perform any action on the last recorded value.

inline RunStats const *getMetric(const std::string &tag) const

Get the statistics for a particular metric. Returns nullptr if the tag does not exist.

inline std::pair<bool, double> getLastRecorded(const std::string &tag) const

Get the last recorded value for a particular metric.

Returns:

A bool,double pair where the first entry indicates whether the tag exists, and the second its value

inline void clear()

Clear the state.

Private Members

std::unordered_map<std::string, RunStats> m_metrics

Map of tag to statistics object

std::unordered_map<std::string, double> m_last

Map of tag to last recorded value

RunStats

namespace chimbuko

Functions

RunStats operator+(const RunStats &a, const RunStats &b)
bool operator==(const RunStats &a, const RunStats &b)
bool operator!=(const RunStats &a, const RunStats &b)
double static_mean(const std::vector<double> &data, double ddof = 1.0)

The mean of the data vector of N data normalized by N-ddof.

double static_std(const std::vector<double> &data, double ddof = 1.0)

The mean of the data vector of N data, with variance normalized by N-ddof.

class RunStats
#include <RunStats.hpp>

Compute statistics in a single pass.

Computes the minimum, maximum, mean, variance, standard deviation, skewness, and kurtosis. Optionally, also computes accumulated values.

RunStats objects may also be added together and copied.

Based entirely on the C++ code by John D Cook at http://www.johndcook.com/skewness_kurtosis.html

Public Functions

RunStats(bool do_accumulate = false)

Constructor.

Parameters:

do_accumulate – If true the sum of the provided values will also be collected

~RunStats()
void clear()

Reset the statistics.

template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal, for example as part of a compound object.

std::string serialize_cerealpb() const

Serialize into Cereal portable binary format

void deserialize_cerealpb(const std::string &strstate)

Serialize from Cereal portable binary format

std::string net_serialize() const

Serialize this class for communication over the network.

void net_deserialize(const std::string &s)

Unserialize this class after communication over the network.

void push(double x)

Add a new value to be included in internal statistics.

double count() const

Get the number of values added to the statistics.

double minimum() const
double maximum() const
double accumulate() const

If m_do_accumulate, the accumulated sum of all values added, otherwise 0.

double mean() const
double variance(double ddof = 1.0) const

Return the variance of the data.

If ddof=1 (default) the variance will include Bessel’s correction, and represents an estimate of the population variance. If ddof=0 the variance will be the variance of the sample

double stddev(double ddof = 1.0) const
double skewness() const
double kurtosis() const
inline void set_do_accumulate(bool do_accumulate)

Set whether the sum of all values is to be maintained.

inline bool get_do_accumulate() const

Determine whether the sum of all values is to be maintained.

nlohmann::json get_json() const

Get the current statistics as a JSON object.

RunStatsValues get_stat_values() const

Get the current statistics as a RunStatsValues object.

RunStats &operator+=(const RunStats &rs)

Combine two RunStats instances such that the resulting statistics are the union of the two.

bool equiv(const RunStats &b) const

Test for equivalence up to a fixed tolerance allowing for finite-precision errors.

inline void set_eta(double to)

Set the eta (mean) parameter.

inline void set_rho(double to)

Set the rho parameter (variance * [count-1])

inline void set_count(double to)

Set the count parameter.

Protected Attributes

double m_count

count of instances

double m_eta

mean

double m_rho

= M2 = \sum_i (x_i - \bar x)^2

double m_tau

= M3 = \sum_i (x_i - \bar x)^3

double m_phi

= M4 = \sum_i (x_i - \bar x)^4

double m_min

minimum

double m_max

maximum

double m_acc

sum

bool m_do_accumulate

True if the sum of the input values are maintained

Friends

friend RunStats operator+(const RunStats &a, const RunStats &b)

Combine two RunStats instances such that the resulting statistics are the union of the two.

friend bool operator==(const RunStats &a, const RunStats &b)

Comparison operator.

friend bool operator!=(const RunStats &a, const RunStats &b)

Negative comparison operator.

struct RunStatsValues
#include <RunStats.hpp>

A serializable object containing the stats values.

Public Functions

template<class Archive>
inline void serialize(Archive &archive)

Serialize using cereal.

inline bool operator==(const RunStatsValues &r) const

Comparison operator.

Public Members

double count
double minimum
double maximum
double accumulate
double mean
double stddev
double skewness
double kurtosis

string

namespace chimbuko

Functions

template<typename T>
T strToAny(const std::string &s)

Convert string to anything.

template<>
inline std::string strToAny<std::string>(const std::string &s)
template<>
inline bool strToAny<bool>(const std::string &s)
template<typename T>
std::string anyToStr(const T &v)

Convert any type to string.

template<>
inline std::string anyToStr<std::string>(const std::string &s)
template<>
inline std::string anyToStr<bool>(const bool &v)
std::string stringize(const char *format, ...)

C-style string formatting but without the nasty mem buffer concerns.

std::vector<std::string> parseStringArray(const std::string &array, char delimiter)

Break up a string into an array of strings around some delimiter.

threadPool

class threadPool
#include <threadPool.hpp>

A class maintaining a queue of tasks that are performed by a pool of threads.

Public Functions

inline threadPool()
inline explicit threadPool(const std::uint32_t nt)

Instantiate a pool of nt threads.

Parameters:

nt – The number of threads to instantiate

threadPool(const threadPool &rhs) = delete

The class is not copyable but can be moved.

threadPool &operator=(const threadPool &rhs) = delete
inline ~threadPool()
template<typename Func, typename ...Args>
inline auto sumit(Func &&func, Args&&... args)

Submit a function object and its arguments to the queue.

inline size_t pool_size() const

Return the number of threads in the pool.

inline size_t queue_size() const

Return the number of tasks in the queue.

Private Functions

inline void worker()
inline void destroy()

Private Members

std::atomic_bool m_done
mtQueue<std::unique_ptr<IThreadTask>> m_workQueue
std::vector<std::thread> m_threads
class IThreadTask

Base class of thread tasks.

Public Functions

IThreadTask() = default
virtual ~IThreadTask() = default
IThreadTask(const IThreadTask &rhs) = delete
IThreadTask &operator=(const IThreadTask &rhs) = delete
IThreadTask(IThreadTask &&other) = default
IThreadTask &operator=(IThreadTask &&other) = default
virtual void execute() = 0

Perform the task (executed by thread)

template<typename T>
class TaskFuture
#include <threadPool.hpp>

A wrapper class for an std::future instance representing the result of an asynchronous operation.

Public Functions

inline TaskFuture(std::future<T> &&future)
inline ~TaskFuture()

The destructor waits for the asynchronous operation to complete before exiting.

TaskFuture(const TaskFuture &rhs) = delete
TaskFuture &operator=(const TaskFuture &rhs) = delete
TaskFuture(TaskFuture &&other) = default
TaskFuture &operator=(TaskFuture &&other) = default
inline auto get()

Wait until the asynchronous operation has completed and return the value.

Private Members

std::future<T> m_future
template<typename Func>
class ThreadTask : public threadPool::IThreadTask

A thread task executing a functional object.

Public Functions

inline ThreadTask(Func &&func)
~ThreadTask() override = default
ThreadTask(const ThreadTask &rhs) = delete
ThreadTask &operator=(const ThreadTask &rhs) = delete
ThreadTask(ThreadTask &&other) = default
ThreadTask &operator=(ThreadTask &&other) = default
inline void execute() override

Private Members

Func m_func
namespace DefaultThreadPool

Functions

inline threadPool &getThreadPool()
template<typename Func, typename ...Args>
inline auto submitJob(Func &&func, Args&&... args)

time

namespace chimbuko

Functions

std::string getDateTime()

Get the local date and time in format “YYYY/MM/DD HH:MM:SS”.

std::string getDateTimeFileExt()

Get the local date and time in format YYYY.MM.DD-HH.MM.SS suitable for a filename extension.

class Timer
#include <time.hpp>

A timer / stopwatch class.

Public Functions

Timer(bool start_now = true)
void start()

(Re)start the timer

void pause()

Pause the timer.

void unpause()

Unpause the timer.

This is the same as start but it does not zero the accumulated time from previous active periods

double elapsed_us() const

Compute the elapsed time in microseconds since start/unpause plus accumulated time from previoud active periods.

double elapsed_ms() const

Compute the elapsed time in milliconds since start/unpause plus accumulated time from previoud active periods.

Private Types

typedef std::chrono::high_resolution_clock Clock
typedef std::chrono::milliseconds MilliSec
typedef std::chrono::microseconds MicroSec

Private Members

Clock::time_point m_start

The start timepoint

Clock::duration m_add

Durations between previous start/unpause and pause

bool m_running

Is the timer running?

verbose

Defines

verboseStream

Macro for log output that appears when verbose logging is enabled.

Example usage: verboseStream << “Hello world!” << std::endl;

verboseStreamAdd

Macro for log output that appears when verbose logging is enabled. This version does not include the prefix and so can be used as a line continuance.

Example usage: verboseStreamAdd << “Hello world!” << std::endl;

progressStream

Macro for log output that includes the date and time, intended for reporting progress on service components for which there is only one rank.

Example usage: progressStream << “Hello world!” << std::endl;

headProgressStream(rank)

Macro for log output that appears when either the rank is equal to the head rank or verbose logging is enabled.

Parameters:

  • rank – The rank of the current process Example usage: progressStream(rank) << “Hello world!” << std::endl;

namespace chimbuko

Functions

inline bool &enableVerboseLogging()

Global control of whether verbose logging is active (default false)

inline int &progressHeadRank()

Choose the rank designated as head rank upon which progress output will be reported; default 0.